From d3cd0948c8c4662c8711433b756c82fbe2f7a3ad Mon Sep 17 00:00:00 2001 From: Andrew Solovay Date: Thu, 19 Feb 2015 17:57:50 -0800 Subject: docs: New doc for creating an AfW Work Policy Controller See first comment for doc stage location. Change-Id: I0c9c0f849c049d33fc66e2bd8ac5ba284c7b9415 --- docs/html/training/enterprise/work-policy-ctrl.jd | 339 ++++++++++++++++++++++ 1 file changed, 339 insertions(+) create mode 100644 docs/html/training/enterprise/work-policy-ctrl.jd (limited to 'docs/html/training') diff --git a/docs/html/training/enterprise/work-policy-ctrl.jd b/docs/html/training/enterprise/work-policy-ctrl.jd new file mode 100644 index 0000000..5854e65 --- /dev/null +++ b/docs/html/training/enterprise/work-policy-ctrl.jd @@ -0,0 +1,339 @@ +page.title=Building a Work Policy Controller +page.metaDescription=Learn how to develop a Work Policy Controller to create and administer a managed profile on an employee's device. +@jd:body + +
+
+ +

This lesson teaches you to

+
    +
  1. Create a Managed Profile
    2. +
  2. Set Up Device Policies
    3. +
  3. Apply App Restrictions
    4. +
+ + + +

+ You should also read +

+ + + +

Resources

+ + +
+
+ + +

+ In an Android for Work deployment, an enterprise needs to maintain control + over certain aspects of the employees' devices. The enterprise needs to + ensure that work-related information is encrypted and is kept separate from + employees' personal data. The enterprise may also need to limit device + capabilities, such as whether the device is allowed to use its camera. And + the enterprise may require that approved apps provide app restrictions, so + the enterprise can turn app capability on or off as needed. +

+ +

+ To handle these tasks, an enterprise develops and deploys a Work Policy + Controller app. This app is installed on each employee's device. The + controller app installed on each employee's device and creates a work user + profile, which accesses enterprise apps and data separately from the user's + personal account. The controller app also acts as the + bridge between the enterprise's management software and the device; the + enterprise tells the controller app when it needs to make configuration + changes, and the controller app makes the appropriate settings changes for the + device and for other apps. +

+ +

+ This lesson describes how to develop a Work Policy Controller app for devices + in an Android for Work deployment. The lesson describes how to create a work + user profile, how to set device policies, and how to apply + restrictions to other apps running on the managed profile. +

+ +

+ Note: This lesson does not cover the situation where the + only profile on the device is the managed profile, under the enterprise's + control. +

+ +

Device Administration Overview

+ +

+ In an Android for Work deployment, the enterprise administrator can set + policies to control the behavior of employees' devices and apps. The + enterprise administrator sets these policies with software provided by their + Enterprise Mobility Management (EMM) provider. The EMM software communicates + with a Work Policy Controller on each device. The Work Policy Controller, in + turn, manages the settings and behavior of the work user profile on each + individual’s device. +

+ +

+ Note: A Work Policy Controller is built on the existing + model used for device administration applications, as described in Device Administration. + In particular, your app needs to create a subclass of {@link + android.app.admin.DeviceAdminReceiver}, as described in that document. +

+ +

Managed profiles

+ +

+ Users often want to use their personal devices in an enterprise setting. This + situation can present enterprises with a dilemma. If the user can use their + own device, the enterprise has to worry that confidential information (like + employee emails and contacts) are on a device the enterprise does not + control. +

+ +

+ To address this situation, Android 5.0 (API level 21) allows enterprises to + set up a special work user profile using the Managed Profile API. This + user profile is called a managed profile, or a work profile + in the Android for Work program. If a device has a + managed profile for work, the profile's settings are under the control of the + enterprise administrator. The administrator can choose which apps are allowed + for that profile, and can control just what device features are available to + the profile. +

+ +

Create a Managed Profile

+ +

To create a managed profile on a device that already has a personal profile, +first check that the device can support a managed profile, by seeing if the +device supports the {@link +android.content.pm.PackageManager#FEATURE_MANAGED_USERS FEATURE_MANAGED_USERS} +system feature:

+ +
PackageManager pm = getPackageManager();
+if (!pm.hasSystemFeature(PackageManager.FEATURE_MANAGED_USERS)) {
+
+    // This device does not support native managed profiles!
+
+}
+ +

If the device supports managed profiles, create one by sending an intent with +an {@link android.app.admin.DevicePolicyManager#ACTION_PROVISION_MANAGED_PROFILE +ACTION_PROVISION_MANAGED_PROFILE} action. Include the device admin package +name as an extra.

+ +
Activity provisioningActivity = getActivity();
+
+// You'll need the package name for the WPC app.
+String myWPCPackageName = "com.example.myWPCApp";
+
+// Set up the provisioning intent
+Intent provisioningIntent =
+        new Intent("android.app.action.PROVISION_MANAGED_PROFILE");
+intent.putExtra(myWPCPackageName,
+        provisioningActivity.getApplicationContext().getPackageName());
+
+if (provisioningIntent.resolveActivity(provisioningActivity.getPackageManager())
+         == null) {
+
+    // No handler for intent! Can't provision this device.
+    // Show an error message and cancel.
+} else {
+
+    // REQUEST_PROVISION_MANAGED_PROFILE is defined
+    // to be a suitable request code
+    startActivityForResult(provisioningIntent,
+            REQUEST_PROVISION_MANAGED_PROFILE);
+    provisioningActivity.finish();
+}
+ +

The system responds to this intent by doing the following:

+ + + +

Override {@link android.app.Activity#onActivityResult onActivityResult()} to +see whether the provisioning was successful, as shown in the following +example code:

+ +
@Override
+public void onActivityResult(int requestCode, int resultCode, Intent data) {
+
+    // Check if this is the result of the provisioning activity
+    if (requestCode == REQUEST_PROVISION_MANAGED_PROFILE) {
+
+        // If provisioning was successful, the result code is 
+        // Activity.RESULT_OK
+        if (resultCode == Activity.RESULT_OK) {
+            // Hurray! Managed profile created and provisioned!
+        } else {
+            // Boo! Provisioning failed!
+        }
+        return;
+
+    } else {
+        // This is the result of some other activity, call the superclass
+        super.onActivityResult(requestCode, resultCode, data);
+    }
+}
+ +

After Creating the Managed Profile

+ +

When the profile has been provisioned, the system calls the Work Policy +Controller app's {@link +android.app.admin.DeviceAdminReceiver#onProfileProvisioningComplete +DeviceAdminReceiver.onProfileProvisioningComplete()} method. Override this +callback method to finish enabling the managed profile.

+ +

Typically, your {@link +android.app.admin.DeviceAdminReceiver#onProfileProvisioningComplete +DeviceAdminReceiver.onProfileProvisioningComplete()} callback implementation +would perform these tasks:

+ + + +

Once you have completed these tasks, call the device policy manager's +{@link android.app.admin.DevicePolicyManager#setProfileEnabled +setProfileEnabled()} method to activate the managed profile:

+ + +
// Get the device policy manager
+DevicePolicyManager myDevicePolicyMgr =
+        (DevicePolicyManager) getSystemService(Context.DEVICE_POLICY_SERVICE);
+
+ComponentName componentName = myDeviceAdminReceiver.getComponentName(this);
+
+// Set the name for the newly created managed profile.
+myDevicePolicyMgr.setProfileName(componentName, "My New Managed Profile");
+
+// ...and enable the profile
+manager.setProfileEnabled(componentName);
+ +

Set Up Device Policies

+ +

+ The Work Policy Controller app is responsible for applying the enterprise's + device policies. For example, a particular enterprise might require that all + devices become locked after a certain number of failed attempts to enter the + device password. The controller app queries the EMM to find out what + the current policies are, then uses the Device Administration + API to apply those policies. +

+ +

For information on how to apply device policies, see the +Device +Administration guide.

+ + +

Apply App Restrictions

+ +

Enterprise environments may require that approved apps implement apps +implement security or feature restrictions. App developers must implement these +restrictions and declare them for use by enterprise administrators, as described +in Implementing +App Restrictions. The Work Policy Controller receives restriction changes +from the enterprise administrator, and forwards those restriction changes to the +apps.

+ +

For example, a particular news app might have a restriction setting that +controls whether the app is allowed to download videos over a cellular +network. When the EMM wants to disable cellular downloads, it sends a +notification to the controller app. The controller app, in turn, +notifies the news app that the restriction setting has changed.

+ +

Note: This document covers how the Work Policy +Controller app changes the restriction settings for the other apps on the +managed profile. Details on how the Work Policy Controller app communicates with +the EMM are out of scope for this document.

+ +

To change an app's restrictions, call the {@link +android.app.admin.DevicePolicyManager#setApplicationRestrictions +DevicePolicyManager.setApplicationRestrictions()} method. This method is passed +three parameters: the controller app's {@link +android.app.admin.DeviceAdminReceiver}, the package name of the app whose +restrictions are being changed, and a {@link android.os.Bundle Bundle} that +contains the restrictions you want to set.

+ +

For example, suppose there's an app on the managed profile with the package +name "com.example.newsfetcher". This app has a single boolean +restriction that can be configured, with the key +"downloadByCellular". If this restriction is set to +false, the newsfetcher app is not allowed to download data through +a cellular network; it must use a Wi-Fi network instead.

+ +

+ If your Work Policy Controller app needs to turn off cellular downloads, it + would first fetch the device policy service object, as described above. It + then assembles a restrictions bundle and passes this bundle to {@link + android.app.admin.DevicePolicyManager#setApplicationRestrictions + setApplicationRestrictions()}: +

+ +
// Fetch the DevicePolicyManager
+DevicePolicyManager myDevicePolicyMgr =
+        (DevicePolicyManager) thisActivity
+                .getSystemService(Context.DEVICE_POLICY_SERVICE);
+
+// Set up the restrictions bundle
+bundle restrictionsBundle = new Bundle();
+restrictionsBundle.putBoolean("downloadByCellular", false);
+
+// Pass the restrictions to the policy manager. Assume the WPC app
+// already has a DeviceAdminReceiver defined (myDeviceAdminReceiver).
+myDevicePolicyMgr.setApplicationRestrictions(
+        myDeviceAdminReceiver, "com.example.newsfetcher", restrictionsBundle);
+ + +

Note: The device policy service conveys the restrictions +change to the app you name. However, it is up to that app to actually implement +the restriction. For example, in this case, the app would be responsible for +disabling its ability to use cellular networks for video downloads. Setting the +restriction does not cause the system to enforce this restriction on the app. +For more information, see Implementing App Restrictions.

-- cgit v1.1