From 262b43153b7b7992498bae9dd0df72eacb4926cb Mon Sep 17 00:00:00 2001 From: Katie McCormick Date: Thu, 30 Sep 2010 16:27:25 -0700 Subject: Doc change: Adding new docs for Device Admin API. commit cc4206420a80db7a75136ffb8293ef115a1f94a8 Author: Katie McCormick Date: Wed Sep 1 17:49:11 2010 -0700 Doc change: New doc for Device Admin API Change-Id: Ic4ae029f5a16c3e2ec8b833fc3714b62e0c61db0 --- docs/html/guide/guide_toc.cs | 3 + docs/html/guide/topics/admin/device-admin.jd | 494 +++++++++++++++++++++ .../images/admin/device-admin-activate-prompt.png | Bin 0 -> 38584 bytes docs/html/images/admin/device-admin-app.png | Bin 0 -> 31310 bytes 4 files changed, 497 insertions(+) create mode 100644 docs/html/guide/topics/admin/device-admin.jd create mode 100755 docs/html/images/admin/device-admin-activate-prompt.png create mode 100755 docs/html/images/admin/device-admin-app.png (limited to 'docs/html') diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 35ce17e..43a5e8d 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -257,6 +257,9 @@
  • Testing and Instrumentation new!
    • +
  • + Device Administration + new!
    • diff --git a/docs/html/guide/topics/admin/device-admin.jd b/docs/html/guide/topics/admin/device-admin.jd new file mode 100644 index 0000000..4d9a14f --- /dev/null +++ b/docs/html/guide/topics/admin/device-admin.jd @@ -0,0 +1,494 @@ +page.title=Android Device Administration API +@jd:body + + +

    Android 2.2 introduces support for enterprise applications by offering the +Android Device Administration API. The Device Administration API provides device +administration features at the system level. These APIs allow you to create +security-aware applications that are useful in enterprise settings, in which IT +professionals require rich control over employee devices. For example, the +built-in Android Email application has leveraged the new APIs to improve +Exchange support. Through the Email application, Exchange administrators can +enforce password policies — including alphanumeric passwords or numeric +PINs — across devices. Administrators can also remotely wipe (that is, +restore factory defaults on) lost or stolen handsets. Exchange users can sync +their email and calendar data.

    + +

    This document is intended for developers who want to develop enterprise +solutions for Android-powered devices. It discusses the various features +provided by the Device Administration API to provide stronger security for +employee devices that are powered by Android.

    +

    Device Administration API Overview

    +

    Here are examples of the types of applications that might use the Device Administration API:

    + + +

    How Does it Work?

    +

    You use the Device Administration API to write device admin applications that users +install on their devices. The device admin application enforces the desired +policies. Here's how it works:

    +

    If users do not enable the device admin app, it remains on the device, but in an inactive state. Users will not be subject to its policies, and they will conversely not get any of the application's benefits—for example, they may not be able to sync data.

    +

    If a user fails to comply with the policies (for example, if a user sets a +password that violates the guidelines), it is up to the application to decide +how to handle this. However, typically this will result in the user not being +able to sync data.

    +

    If a device attempts to connect to a server that requires policies not +supported in the Device Administration API, the connection will not +be allowed. The Device Administration API does not currently allow partial +provisioning. In other words, if a device (for example, a legacy device) does +not support all of the stated policies, there is no way to allow the +device to connect.

    +

    If a device contains multiple enabled admin applications, the strictest policy is +enforced. There is no way to target a particular admin +application.

    +

    To uninstall an existing device admin application, users need to +first unregister the application as an administrator.

    + +

    Policies

    +

    In an enterprise setting, it's often the case that employee devices must +adhere to a strict set of policies that govern the use of the device. The +Device Administration API supports the policies listed in Table 1. +Note that the Device Administration API currently only supports passwords for screen +lock:

    +

    Table 1. Policies supported by the Device Administration API.

    + + + + + + + + + + + + + + + + + + + + + + + +
    PolicyDescription
    Password enabledRequires that devices ask for PIN or passwords.
    Minimum password lengthSet the required number of characters for the password. For example, you +can require PIN or passwords to have at least six characters.
    Alphanumeric password requiredRequires that passwords have a +combination of letters and numbers. They may include symbolic characters. +
    Maximum failed password attempts Specifies how many times a user can enter the wrong password before the +device wipes its data. The Device Administration API also allows administrators to +remotely reset the device to factory defaults. This secures data in case the +device is lost or stolen.
    Maximum inactivity time lockSets the length of time since the user last touched the screen or +pressed a button before the device locks the screen. When this happens, users +need to enter their PIN or passwords again before they can use their devices and +access data. The value can be between 1 and 60 minutes.
    +

    Other Features

    +

    In addition to supporting the policies listed in the above table, the Device +Administration API lets you do the following:

    + + +

    Sample Application

    +

    The examples used in this document are based on the Device Administration API +sample, which is included in the SDK samples. For information on downloading and +installing the SDK samples, see +Getting the Samples. Here is the complete code for +the sample.

    +

    The +sample application offers a demo of device admin features. It presents users +with a user interface that lets them enable the device admin application. Once +they've enabled the application, they can use the buttons in the user interface +to do the following:

    + + + +

    Figure 1. Screenshot of the Sample Application

    + +

    Developing a Device Administration Application

    + +

    System administrators can use the Device Administration API to write an application +that enforces remote/local device security policy enforcement. This section +summarizes the steps involved in creating a device administration +application.

    +

    Creating the Manifest

    +

    To use the Device Administration API, the application's +manifest must include the following:

    + +

    Here is an excerpt from the Device Administration sample manifest:

    +
    <activity android:name=".app.DeviceAdminSample$Controller"
+          android:label="@string/activity_sample_device_admin">
+    <intent-filter>
+        <action android:name="android.intent.action.MAIN" />
+        <category android:name="android.intent.category.SAMPLE_CODE" />
+    </intent-filter>
+</activity>
+
+<receiver android:name=".app.DeviceAdminSample"
+          android:label="@string/sample_device_admin"
+          android:description="@string/sample_device_admin_description"
+          android:permission="android.permission.BIND_DEVICE_ADMIN">
+    <meta-data android:name="android.app.device_admin"
+               android:resource="@xml/device_admin_sample" />
+    <intent-filter>
+        <action android:name="android.app.action.DEVICE_ADMIN_ENABLED" />
+    </intent-filter>
+</receiver>
    + +

    Note that:

    + +
    <device-admin xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-policies>
+    <limit-password />
+    <watch-login />
+    <reset-password />
+    <force-lock />
+    <wipe-data />
+  </uses-policies>
+</device-admin>
+
    +

    In designing your device administration application, you don't need to +include all of the policies, just the ones that are relevant for your app. +

    +For more discussion of the manifest file, see the Android Developers Guide. +

    Implementing the Code

    +

    The Device Administration API includes the following classes:

    +
    +
    {@link android.app.admin.DeviceAdminReceiver}
    +
    Base class for implementing a device administration component. This class provides +a convenience for interpreting the raw intent actions that are sent by the +system. Your Device Administration application must include a +{@link android.app.admin.DeviceAdminReceiver} subclass.
    +
    {@link android.app.admin.DevicePolicyManager}
    +
    A class for managing policies enforced on a device. Most clients of +this class must have published a {@link android.app.admin.DeviceAdminReceiver} that the user +has currently enabled. The {@link android.app.admin.DevicePolicyManager} manages policies for +one or more {@link android.app.admin.DeviceAdminReceiver} instances
    +
    {@link android.app.admin.DeviceAdminInfo}
    +
    This class is used to specify metadata +for a device administrator component.
    +
    +

    These classes provide the foundation for a fully functional device administration application. +The rest of this section describes how you use the {@link +android.app.admin.DeviceAdminReceiver} and +{@link android.app.admin.DevicePolicyManager} APIs to write a device admin application.

    +

    Subclassing DeviceAdminReceiver

    +

    To create a device admin application, you must subclass +{@link android.app.admin.DeviceAdminReceiver}. The {@link android.app.admin.DeviceAdminReceiver} class +consists of a series of callbacks that are triggered when particular events +occur.

    +

    In its {@link android.app.admin.DeviceAdminReceiver} subclass, the sample application +simply displays a {@link android.widget.Toast} notification in response to particular +events. For example:

    +
    public class DeviceAdminSample extends DeviceAdminReceiver {
+
+... 
+    @Override
+    public void onEnabled(Context context, Intent intent) {
+        showToast(context, "Sample Device Admin: enabled");
+    }
+
+    @Override
+    public CharSequence onDisableRequested(Context context, Intent intent) {
+        return "This is an optional message to warn the user about disabling.";
+    }
+
+    @Override
+    public void onDisabled(Context context, Intent intent) {
+        showToast(context, "Sample Device Admin: disabled");
+    }
+
+    @Override
+    public void onPasswordChanged(Context context, Intent intent) {
+        showToast(context, "Sample Device Admin: pw changed");
+    }
+
+    void showToast(Context context, CharSequence msg) {
+        Toast.makeText(context, msg, Toast.LENGTH_SHORT).show();
+    }
+...
+}
    +

    Enabling the Application

    +

    One of the major events a device admin application has to handle is the user +enabling the application. The user must explicitly enable the application for +the policies to be enforced. If the user chooses not to enable the application +it will still be present on the device, but its policies will not be enforced, and the user will not +get any of the application's benefits.

    +

    The process of enabling the application begins when the user performs an +action that triggers the {@link android.app.admin.DevicePolicyManager#ACTION_ADD_DEVICE_ADMIN} +intent. In the +sample application, this happens when the user clicks the Enable +Admin button.

    +

    When the user clicks the Enable Admin button, the display +changes to prompt the user to enable the device admin application, as shown in Figure 2.

    + + +

    Figure 2. Sample Application: Activating the Application

    +

    Below is the code that gets executed when the user clicks the Enable +Admin button shown in Figure 1.

    + +
     private OnClickListener mEnableListener = new OnClickListener() {
+    public void onClick(View v) {
+        // Launch the activity to have the user enable our admin.
+        Intent intent = new Intent(DevicePolicyManager.ACTION_ADD_DEVICE_ADMIN);
+        intent.putExtra(DevicePolicyManager.EXTRA_DEVICE_ADMIN, 
+               mDeviceAdminSample);
+        intent.putExtra(DevicePolicyManager.EXTRA_ADD_EXPLANATION,
+               "Additional text explaining why this needs to be added.");
+        startActivityForResult(intent, RESULT_ENABLE);
+    }
+};
+
+...
+// This code checks whether the device admin app was successfully enabled.
+@Override
+protected void onActivityResult(int requestCode, int resultCode, Intent data) {
+    switch (requestCode) {
+        case RESULT_ENABLE:
+            if (resultCode == Activity.RESULT_OK) {
+                Log.i("DeviceAdminSample", "Administration enabled!");
+            } else {
+                Log.i("DeviceAdminSample", "Administration enable FAILED!");
+            }
+            return;
+    }
+    super.onActivityResult(requestCode, resultCode, data);
+}
    + +

    The line +intent.putExtra(DevicePolicyManager.EXTRA_DEVICE_ADMIN, +mDeviceAdminSample) states that mDeviceAdminSample (which is +a {@link android.app.admin.DeviceAdminReceiver} component) is the target policy. +This line invokes the user interface shown in Figure 2, which guides users through +adding the device administrator to the system (or allows them to reject it).

    + +

    When the application needs to perform an operation that is contingent on the +device admin application being enabled, it confirms that the application is +active. To do this it uses the {@link android.app.admin.DevicePolicyManager} method +{@link android.app.admin.DevicePolicyManager#isAdminActive(android.content.ComponentName) isAdminActive()}. Notice that the {@link android.app.admin.DevicePolicyManager} +method {@link android.app.admin.DevicePolicyManager#isAdminActive(android.content.ComponentName) isAdminActive()} takes a {@link android.app.admin.DeviceAdminReceiver} +component as its argument:

    +
    +DevicePolicyManager mDPM;
+...
+boolean active = mDPM.isAdminActive(mDeviceAdminSample);
+if (active) {
+    // Admin app is active, so do some admin stuff
+               ...
+} else {
+    // do something else
+}
+
    +

    Managing Policies

    +

    {@link android.app.admin.DevicePolicyManager} is a public class for managing policies +enforced on a device. {@link android.app.admin.DevicePolicyManager} manages policies for one +or more {@link android.app.admin.DeviceAdminReceiver} instances.

    +

    You get a handle to the {@link android.app.admin.DevicePolicyManager} as follows:

    +
    DevicePolicyManager mDPM =
+(DevicePolicyManager)getSystemService(Context.DEVICE_POLICY_SERVICE);
    +

    This section describes how to use {@link android.app.admin.DevicePolicyManager} to perform + administrative tasks:

    + +

    Set password policies

    +

    {@link android.app.admin.DevicePolicyManager} includes APIs for setting and enforcing the +device password policy. In the Device Administration API, the password only applies to +screen lock. This section describes common password-related tasks.

    +
    Set a password for the device
    +

    This code displays a user interface prompting the user to set a password:

    +
    Intent intent = new Intent(DevicePolicyManager.ACTION_SET_NEW_PASSWORD);
+startActivity(intent);
+
    +
    Set the password quality
    +

    The password quality can be one of the following {@link android.app.admin.DevicePolicyManager} constants:

    +
    +
    {@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_ALPHABETIC}
    The user must enter a +password containing at least alphabetic (or other symbol) characters.
    +
    {@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_ALPHANUMERIC}
    The user must enter a +password containing at least both numeric and alphabetic (or +other symbol) characters.
    +
    {@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_NUMERIC}
    The user must enter a password +containing at least numeric characters.
    +
    {@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_SOMETHING}
    The policy requires some kind +of password, but doesn't care what it is.
    +
    {@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_UNSPECIFIED}
    + The policy has no requirements for the password.
    +
    +

    For example, this is how you would set the password policy to require an alphanumeric password:

    +
    +DevicePolicyManager mDPM;
+ComponentName mDeviceAdminSample;
+...
+mDPM.setPasswordQuality(mDeviceAdminSample, DevicePolicyManager.PASSWORD_QUALITY_ALPHANUMERIC);
+
    +
    Set the minimum password length
    +

    You can specify that a password must be at least the specified minimum +length. For example:

    +
    DevicePolicyManager mDPM;
+ComponentName mDeviceAdminSample;
+int pwLength;
+...
+mDPM.setPasswordMinimumLength(mDeviceAdminSample, pwLength);
+
    +
    Set maximum failed password attempts
    +

    You can set the maximum number of allowed failed password attempts before the +device is wiped (that is, reset to factory settings). For example:

    +
    DevicePolicyManager mDPM; 
+ComponentName mDeviceAdminSample; 
+int maxFailedPw;
+ ...
+mDPM.setMaximumFailedPasswordsForWipe(mDeviceAdminSample, maxFailedPw);
    +

    Set device lock

    +

    You can set the maximum period of user inactivity that can occur before the +device locks. For example:

    +
    +DevicePolicyManager mDPM; 
+ComponentName mDeviceAdminSample;
+...
+long timeMs = 1000L*Long.parseLong(mTimeout.getText().toString());
+mDPM.setMaximumTimeToLock(mDeviceAdminSample, timeMs);
+
    +

    You can also programmatically tell the device to lock immediately:

    +
    +DevicePolicyManager mDPM; 
+mDPM.lockNow();
    +

    Perform data wipe

    +

    You can use the {@link android.app.admin.DevicePolicyManager} method +{@link android.app.admin.DevicePolicyManager#wipeData wipeData()} to reset the device to factory settings. This is useful +if the device is lost or stolen. Often the decision to wipe the device is the +result of certain conditions being met. For example, you can use +{@link android.app.admin.DevicePolicyManager#setMaximumFailedPasswordsForWipe setMaximumFailedPasswordsForWipe()} to state that a device should be +wiped after a specific number of failed password attempts.

    +

    You wipe data as follows:

    +
    +DevicePolicyManager mDPM; 
+mDPM.wipeData(0);
    +

    The {@link android.app.admin.DevicePolicyManager#wipeData wipeData()} method takes as its parameter a bit mask of +additional options. Currently the value must be 0.

    diff --git a/docs/html/images/admin/device-admin-activate-prompt.png b/docs/html/images/admin/device-admin-activate-prompt.png new file mode 100755 index 0000000..fd001bd Binary files /dev/null and b/docs/html/images/admin/device-admin-activate-prompt.png differ diff --git a/docs/html/images/admin/device-admin-app.png b/docs/html/images/admin/device-admin-app.png new file mode 100755 index 0000000..d966a28 Binary files /dev/null and b/docs/html/images/admin/device-admin-app.png differ -- cgit v1.1