1 page.title=Device Administration 2 @jd:body 3 4 <div id="qv-wrapper"> 5 <div id="qv"> 6 <h2>In this document</h2> 7 <ol> 8 <li><a href="#overview">Device Administration API Overview</a> 9 <ol> 10 <li><a href="#how">How does it work?</a></li> 11 <li><a href="#policies">Policies</a></li> 12 </ol> 13 </li> 14 <li><a href="#sample">Sample Application</a></li> 15 <li><a href="#developing">Developing a Device Administration Application</a> 16 <ol> 17 <li><a href="#manifest">Creating the manifest</a></li> 18 <li><a href="#code">Implementing the code</a></li> 19 </ol> 20 </li> 21 22 </ol> 23 24 <h2>Key classes</h2> 25 <ol> 26 <li>{@link android.app.admin.DeviceAdminReceiver}</li> 27 <li>{@link android.app.admin.DevicePolicyManager}</li> 28 <li>{@link android.app.admin.DeviceAdminInfo}</li> 29 </ol> 30 </div> 31 </div> 32 33 <p>Android 2.2 introduces support for enterprise applications by offering the 34 Android Device Administration API. The Device Administration API provides device 35 administration features at the system level. These APIs allow you to create 36 security-aware applications that are useful in enterprise settings, in which IT 37 professionals require rich control over employee devices. For example, the 38 built-in Android Email application has leveraged the new APIs to improve 39 Exchange support. Through the Email application, Exchange administrators can 40 enforce password policies — including alphanumeric passwords or numeric 41 PINs — across devices. Administrators can also remotely wipe (that is, 42 restore factory defaults on) lost or stolen handsets. Exchange users can sync 43 their email and calendar data.</p> 44 45 <p>This document is intended for developers who want to develop enterprise 46 solutions for Android-powered devices. It discusses the various features 47 provided by the Device Administration API to provide stronger security for 48 employee devices that are powered by Android.</p> 49 50 51 <h2 id="overview">Device Administration API Overview</h2> 52 53 <p>Here are examples of the types of applications that might use the Device Administration API:</p> 54 <ul> 55 <li>Email clients.</li> 56 <li>Security applications that do remote wipe.</li> 57 <li>Device management services and applications.</li> 58 </ul> 59 60 <h3 id="how">How does it work?</h3> 61 <p>You use the Device Administration API to write device admin applications that users 62 install on their devices. The device admin application enforces the desired 63 policies. Here's how it works:</p> <ul> 64 <li>A system administrator writes a device admin application that enforces 65 remote/local device security policies. These policies could be hard-coded into 66 the app, or the application could dynamically fetch policies from a third-party 67 server. </li> 68 <li>The application is installed on users' devices. Android does 69 not currently have an automated provisioning solution. Some of the ways a sysadmin might 70 distribute the application to users are as follows: 71 <ul> 72 <li>Android Market.</li> 73 <li>Enabling non-market installation.</li> 74 <li>Distributing the application through other means, such as email or websites.</li> 75 76 </ul> 77 78 79 </li> 80 <li>The system prompts the user to enable the device admin application. How 81 and when this happens depends on how the application is implemented.</li> 82 <li>Once users enable the device admin application, they are subject to 83 its policies. Complying with those policies typically confers benefits, such as 84 access to sensitive systems and data.</li> 85 </ul> 86 <p>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.</p> 87 <p>If a user fails to comply with the policies (for example, if a user sets a 88 password that violates the guidelines), it is up to the application to decide 89 how to handle this. However, typically this will result in the user not being 90 able to sync data.</p> 91 <p>If a device attempts to connect to a server that requires policies not 92 supported in the Device Administration API, the connection will not 93 be allowed. The Device Administration API does not currently allow partial 94 provisioning. In other words, if a device (for example, a legacy device) does 95 not support all of the stated policies, there is no way to allow the 96 device to connect.</p> 97 <p>If a device contains multiple enabled admin applications, the strictest policy is 98 enforced. There is no way to target a particular admin 99 application.</p> 100 <p>To uninstall an existing device admin application, users need to 101 first unregister the application as an administrator. </p> 102 103 104 <h3 id="policies">Policies</h3> 105 106 <p>In an enterprise setting, it's often the case that employee devices must 107 adhere to a strict set of policies that govern the use of the device. The 108 Device Administration API supports the policies listed in Table 1. 109 Note that the Device Administration API currently only supports passwords for screen 110 lock:</p> 111 <p class="table-caption"><strong>Table 1.</strong> Policies supported by the Device Administration API.</p> 112 <table border="1"> 113 <tr> 114 <th>Policy</th> 115 <th>Description</th> 116 </tr> 117 <tr> 118 <td>Password enabled</td> 119 <td>Requires that devices ask for PIN or passwords.</td> 120 </tr> 121 <tr> 122 <td>Minimum password length</td> 123 <td>Set the required number of characters for the password. For example, you 124 can require PIN or passwords to have at least six characters. </td> </tr> 125 <tr> 126 <td>Alphanumeric password required</td> 127 <td>Requires that passwords have a 128 combination of letters and numbers. They may include symbolic characters. 129 </td> 130 </tr> 131 <tr> 132 <td>Maximum failed password attempts </td> 133 <td>Specifies how many times a user can enter the wrong password before the 134 device wipes its data. The Device Administration API also allows administrators to 135 remotely reset the device to factory defaults. This secures data in case the 136 device is lost or stolen.</td> 137 </tr> 138 <tr> 139 <td>Maximum inactivity time lock</td> 140 <td>Sets the length of time since the user last touched the screen or 141 pressed a button before the device locks the screen. When this happens, users 142 need to enter their PIN or passwords again before they can use their devices and 143 access data. The value can be between 1 and 60 minutes.</td> </tr> 144 </table> 145 146 <h4>Other features</h4> 147 148 <p>In addition to supporting the policies listed in the above table, the Device 149 Administration API lets you do the following:</p> <ul> 150 <li>Prompt user to set a new password.</li> 151 <li>Lock device immediately.</li> 152 <li>Wipe the device's data (that is, restore the device to its factory defaults).</li> 153 </ul> 154 155 156 <h2 id="sample">Sample Application</h2> 157 158 <p>The examples used in this document are based on the <a 159 href="{@docRoot}resources/samples/ApiDemos/src/com/example/ 160 android/apis/app/DeviceAdminSample.html">Device Administration API 161 sample</a>, which is included in the SDK samples. For information on downloading and 162 installing the SDK samples, see <a 163 href="{@docRoot}resources/samples/get.html"> 164 Getting the Samples</a>. Here is the <a 165 href="{@docRoot}resources/samples/ApiDemos/src/com/example/ 166 android/apis/app/DeviceAdminSample.html">complete code</a> for 167 the sample. </p> 168 <p>The 169 sample application offers a demo of device admin features. It presents users 170 with a user interface that lets them enable the device admin application. Once 171 they've enabled the application, they can use the buttons in the user interface 172 to do the following:</p> 173 <ul> 174 <li>Set password quality.</li> 175 <li>Specify the minimum length for the user's password.</li> 176 <li>Set the password. If the password does not conform to the specified 177 policies, the system returns an error.</li> 178 <li>Set how many failed password attempts can occur before the device is wiped 179 (that is, restored to factory settings).</li> 180 <li>Set the maximum amount of inactive time that can elapse before the device 181 locks.</li> 182 <li>Make the device lock immediately.</li> 183 <li>Wipe the device's data (that is, restore factory settings).</li> 184 </ul> 185 186 <img src="{@docRoot}images/admin/device-admin-app.png"/> 187 <p class="img-caption"><strong>Figure 1.</strong> Screenshot of the Sample Application</p> 188 189 190 191 <h2 id="developing">Developing a Device Administration Application</h2> 192 193 <p>System administrators can use the Device Administration API to write an application 194 that enforces remote/local device security policy enforcement. This section 195 summarizes the steps involved in creating a device administration 196 application.</p> 197 198 <h3 id="manifest">Creating the manifest</h3> 199 200 <p>To use the Device Administration API, the application's 201 manifest must include the following:</p> 202 <ul> 203 <li>A subclass of {@link android.app.admin.DeviceAdminReceiver} that includes the following: 204 <ul> 205 <li>The {@link android.Manifest.permission#BIND_DEVICE_ADMIN} permission.</li> 206 <li>The ability to respond to the {@link android.app.admin.DeviceAdminReceiver#ACTION_DEVICE_ADMIN_ENABLED} 207 intent, expressed in the manifest as an intent filter.</li> 208 </ul> 209 </li> 210 <li>A declaration of security policies used in metadata.</li> 211 </ul> 212 <p>Here is an excerpt from the Device Administration sample manifest:</p> 213 <pre><activity android:name=".app.DeviceAdminSample$Controller" 214 android:label="@string/activity_sample_device_admin"> 215 <intent-filter> 216 <action android:name="android.intent.action.MAIN" /> 217 <category android:name="android.intent.category.SAMPLE_CODE" /> 218 </intent-filter> 219 </activity> 220 221 <receiver android:name=".app.DeviceAdminSample" 222 android:label="@string/sample_device_admin" 223 android:description="@string/sample_device_admin_description" 224 android:permission="android.permission.BIND_DEVICE_ADMIN"> 225 <meta-data android:name="android.app.device_admin" 226 android:resource="@xml/device_admin_sample" /> 227 <intent-filter> 228 <action android:name="android.app.action.DEVICE_ADMIN_ENABLED" /> 229 </intent-filter> 230 </receiver></pre> 231 232 <p>Note that:</p> 233 <ul> 234 <li>The activity in the sample application is an {@link android.app.Activity} 235 subclass called <code>Controller</code>. The syntax 236 <code>".app.DeviceAdminSample$Controller"</code> indicates that 237 <code>Controller</code> is an inner class that is nested inside the 238 <code>DeviceAdminSample</code> class. Note that an Activity does not need to be 239 an inner class; it just is in this example.</li> 240 241 <li>The following attributes refer to string resources that for the sample application reside in 242 <code>ApiDemos/res/values/strings.xml</code>. For more information about resources, see 243 <a 244 href="{@docRoot}guide/topics/resources/index.html">Application Resources</a>. 245 <ul> 246 <li><code>android:label="@string/activity_sample_device_admin"</code> refers to the 247 user-readable label for the activity.</li> 248 249 <li><code>android:label="@string/sample_device_admin"</code> refers to the 250 user-readable label for the permission.</li> 251 252 <li><code>android:description="@string/sample_device_admin_description"</code> refers to 253 the user-readable description of the permission. A descripton is typically longer and more 254 informative than 255 a label.</li> 256 </ul> 257 258 259 <li><code>android:permission="android.permission.BIND_DEVICE_ADMIN" 260 </code> is a permission that a {@link android.app.admin.DeviceAdminReceiver} subclass must 261 have, to ensure that only the system can interact with the receiver (no application can be granted this permission). This 262 prevents other applications from abusing your device admin app.</li> 263 <li><code>android.app.action.DEVICE_ADMIN_ENABLED</code> is the the primary 264 action that a {@link android.app.admin.DeviceAdminReceiver} subclass must handle to be 265 allowed to manage a device. This is set to the receiver when the user enables 266 the device admin app. Your code typically handles this in 267 {@link android.app.admin.DeviceAdminReceiver#onEnabled onEnabled()}. To be supported, the receiver must also 268 require the {@link android.Manifest.permission#BIND_DEVICE_ADMIN} permission so that other applications 269 cannot abuse it. </li> 270 <li>When a user enables the device admin application, that gives the receiver 271 permission to perform actions in response to the broadcast of particular system 272 events. When suitable event arises, the application can impose a policy. For 273 example, if the user attempts to set a new password that doesn't meet the policy 274 requirements, the application can prompt the user to pick a different password 275 that does meet the requirements.</li> 276 277 <li><code>android:resource="@xml/device_admin_sample"</code> 278 declares the security policies used in metadata. The metadata provides additional 279 information specific to the device administrator, as parsed by the {@link 280 android.app.admin.DeviceAdminInfo} class. Here are the contents of 281 <code>device_admin_sample.xml</code>:</li> 282 </ul> 283 <pre><device-admin xmlns:android="http://schemas.android.com/apk/res/android"> 284 <uses-policies> 285 <limit-password /> 286 <watch-login /> 287 <reset-password /> 288 <force-lock /> 289 <wipe-data /> 290 </uses-policies> 291 </device-admin> 292 </pre> 293 <p> In designing your device administration application, you don't need to 294 include all of the policies, just the ones that are relevant for your app. 295 </p> 296 For more discussion of the manifest file, see the <a 297 href="{@docRoot}guide/topics/manifest/manifest-intro.html">Android Developers Guide</a>. 298 299 300 301 <h3 id="code">Implementing the code</h3> 302 303 <p>The Device Administration API includes the following classes:</p> 304 <dl> 305 <dt>{@link android.app.admin.DeviceAdminReceiver}</dt> 306 <dd>Base class for implementing a device administration component. This class provides 307 a convenience for interpreting the raw intent actions that are sent by the 308 system. Your Device Administration application must include a 309 {@link android.app.admin.DeviceAdminReceiver} subclass.</dd> 310 <dt>{@link android.app.admin.DevicePolicyManager}</dt> 311 <dd>A class for managing policies enforced on a device. Most clients of 312 this class must have published a {@link android.app.admin.DeviceAdminReceiver} that the user 313 has currently enabled. The {@link android.app.admin.DevicePolicyManager} manages policies for 314 one or more {@link android.app.admin.DeviceAdminReceiver} instances</dd> 315 <dt>{@link android.app.admin.DeviceAdminInfo}</dt> 316 <dd>This class is used to specify metadata 317 for a device administrator component.</dd> 318 </dl> 319 <p>These classes provide the foundation for a fully functional device administration application. 320 The rest of this section describes how you use the {@link 321 android.app.admin.DeviceAdminReceiver} and 322 {@link android.app.admin.DevicePolicyManager} APIs to write a device admin application.</p> 323 324 <h4 id="receiver">Subclassing DeviceAdminReceiver</h4> 325 <p>To create a device admin application, you must subclass 326 {@link android.app.admin.DeviceAdminReceiver}. The {@link android.app.admin.DeviceAdminReceiver} class 327 consists of a series of callbacks that are triggered when particular events 328 occur.</p> 329 <p>In its {@link android.app.admin.DeviceAdminReceiver} subclass, the sample application 330 simply displays a {@link android.widget.Toast} notification in response to particular 331 events. For example:</p> 332 <pre>public class DeviceAdminSample extends DeviceAdminReceiver { 333 334 ... 335 @Override 336 public void onEnabled(Context context, Intent intent) { 337 showToast(context, "Sample Device Admin: enabled"); 338 } 339 340 @Override 341 public CharSequence onDisableRequested(Context context, Intent intent) { 342 return "This is an optional message to warn the user about disabling."; 343 } 344 345 @Override 346 public void onDisabled(Context context, Intent intent) { 347 showToast(context, "Sample Device Admin: disabled"); 348 } 349 350 @Override 351 public void onPasswordChanged(Context context, Intent intent) { 352 showToast(context, "Sample Device Admin: pw changed"); 353 } 354 355 void showToast(Context context, CharSequence msg) { 356 Toast.makeText(context, msg, Toast.LENGTH_SHORT).show(); 357 } 358 ... 359 }</pre> 360 361 <h4 id="enabling">Enabling the application</h4> 362 <p>One of the major events a device admin application has to handle is the user 363 enabling the application. The user must explicitly enable the application for 364 the policies to be enforced. If the user chooses not to enable the application 365 it will still be present on the device, but its policies will not be enforced, and the user will not 366 get any of the application's benefits.</p> 367 <p>The process of enabling the application begins when the user performs an 368 action that triggers the {@link android.app.admin.DevicePolicyManager#ACTION_ADD_DEVICE_ADMIN} 369 intent. In the 370 sample application, this happens when the user clicks the <strong>Enable 371 Admin</strong> button. </p> 372 <p>When the user clicks the <strong>Enable Admin</strong> button, the display 373 changes to prompt the user to enable the device admin application, as shown in figure 374 2.</p> 375 376 <img src="{@docRoot}images/admin/device-admin-activate-prompt.png"/> 377 <p class="img-caption"><strong>Figure 2.</strong> Sample Application: Activating the Application</p> 378 <p>Below is the code that gets executed when the user clicks the <strong>Enable 379 Admin</strong> button shown in figure 1. </p> 380 381 <pre> private OnClickListener mEnableListener = new OnClickListener() { 382 public void onClick(View v) { 383 // Launch the activity to have the user enable our admin. 384 Intent intent = new Intent(DevicePolicyManager.ACTION_ADD_DEVICE_ADMIN); 385 intent.putExtra(DevicePolicyManager.EXTRA_DEVICE_ADMIN, 386 mDeviceAdminSample); 387 intent.putExtra(DevicePolicyManager.EXTRA_ADD_EXPLANATION, 388 "Additional text explaining why this needs to be added."); 389 startActivityForResult(intent, RESULT_ENABLE); 390 } 391 }; 392 393 ... 394 // This code checks whether the device admin app was successfully enabled. 395 @Override 396 protected void onActivityResult(int requestCode, int resultCode, Intent data) { 397 switch (requestCode) { 398 case RESULT_ENABLE: 399 if (resultCode == Activity.RESULT_OK) { 400 Log.i("DeviceAdminSample", "Administration enabled!"); 401 } else { 402 Log.i("DeviceAdminSample", "Administration enable FAILED!"); 403 } 404 return; 405 } 406 super.onActivityResult(requestCode, resultCode, data); 407 }</pre> 408 409 <p>The line 410 <code>intent.putExtra(DevicePolicyManager.EXTRA_DEVICE_ADMIN, 411 mDeviceAdminSample)</code> states that <code>mDeviceAdminSample</code> (which is 412 a {@link android.app.admin.DeviceAdminReceiver} component) is the target policy. 413 This line invokes the user interface shown in figure 2, which guides users through 414 adding the device administrator to the system (or allows them to reject it).</p> 415 416 <p>When the application needs to perform an operation that is contingent on the 417 device admin application being enabled, it confirms that the application is 418 active. To do this it uses the {@link android.app.admin.DevicePolicyManager} method 419 {@link android.app.admin.DevicePolicyManager#isAdminActive(android.content.ComponentName) isAdminActive()}. Notice that the {@link android.app.admin.DevicePolicyManager} 420 method {@link android.app.admin.DevicePolicyManager#isAdminActive(android.content.ComponentName) isAdminActive()} takes a {@link android.app.admin.DeviceAdminReceiver} 421 component as its argument:</p> 422 <pre> 423 DevicePolicyManager mDPM; 424 ... 425 boolean active = mDPM.isAdminActive(mDeviceAdminSample); 426 if (active) { 427 // Admin app is active, so do some admin stuff 428 ... 429 } else { 430 // do something else 431 } 432 </pre> 433 434 <h3 id="admin_ops">Managing policies</h3> 435 <p>{@link android.app.admin.DevicePolicyManager} is a public class for managing policies 436 enforced on a device. {@link android.app.admin.DevicePolicyManager} manages policies for one 437 or more {@link android.app.admin.DeviceAdminReceiver} instances. </p> 438 <p>You get a handle to the {@link android.app.admin.DevicePolicyManager} as follows: </p> 439 <pre> 440 DevicePolicyManager mDPM = 441 (DevicePolicyManager)getSystemService(Context.DEVICE_POLICY_SERVICE); 442 </pre> 443 <p>This section describes how to use {@link android.app.admin.DevicePolicyManager} to perform 444 administrative tasks:</p> 445 <ul> 446 <li><a href="#pwd">Set password policies</a></li> 447 <li><a href="#lock">Set device lock</a></li> 448 <li><a href="#wipe">Perform data wipe</a></li> 449 </ul> 450 451 <h4 id="pwd">Set password policies</h4> 452 <p>{@link android.app.admin.DevicePolicyManager} includes APIs for setting and enforcing the 453 device password policy. In the Device Administration API, the password only applies to 454 screen lock. This section describes common password-related tasks.</p> 455 456 <h5>Set a password for the device</h5> 457 <p>This code displays a user interface prompting the user to set a password:</p> 458 <pre>Intent intent = new Intent(DevicePolicyManager.ACTION_SET_NEW_PASSWORD); 459 startActivity(intent); 460 </pre> 461 462 <h5>Set the password quality</h5> 463 <p>The password quality can be one of the following {@link android.app.admin.DevicePolicyManager} constants: </p> 464 <dl> 465 <dt>{@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_ALPHABETIC}</dt><dd>The user must enter a 466 password containing at least alphabetic (or other symbol) characters.</dd> 467 <dt>{@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_ALPHANUMERIC}</dt><dd>The user must enter a 468 password containing at least <em>both</em> numeric <em>and</em> alphabetic (or 469 other symbol) characters.</dd> 470 <dt>{@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_NUMERIC}</dt><dd>The user must enter a password 471 containing at least numeric characters.</dd> 472 <dt>{@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_SOMETHING}</dt><dd>The policy requires some kind 473 of password, but doesn't care what it is.</dd> 474 <dt>{@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_UNSPECIFIED}</dt><dd> 475 The policy has no requirements for the password. </dd> 476 </dl> 477 <p>For example, this is how you would set the password policy to require an alphanumeric password:</p> 478 <pre> 479 DevicePolicyManager mDPM; 480 ComponentName mDeviceAdminSample; 481 ... 482 mDPM.setPasswordQuality(mDeviceAdminSample, DevicePolicyManager.PASSWORD_QUALITY_ALPHANUMERIC); 483 </pre> 484 485 <h5>Set the minimum password length</h5> 486 <p>You can specify that a password must be at least the specified minimum 487 length. For example:</p> 488 <pre>DevicePolicyManager mDPM; 489 ComponentName mDeviceAdminSample; 490 int pwLength; 491 ... 492 mDPM.setPasswordMinimumLength(mDeviceAdminSample, pwLength); 493 </pre> 494 495 <h5>Set maximum failed password attempts</h5> 496 <p>You can set the maximum number of allowed failed password attempts before the 497 device is wiped (that is, reset to factory settings). For example:</p> 498 <pre>DevicePolicyManager mDPM; 499 ComponentName mDeviceAdminSample; 500 int maxFailedPw; 501 ... 502 mDPM.setMaximumFailedPasswordsForWipe(mDeviceAdminSample, maxFailedPw);</pre> 503 504 <h4 id="lock">Set device lock</h4> 505 <p>You can set the maximum period of user inactivity that can occur before the 506 device locks. For example:</p> 507 <pre> 508 DevicePolicyManager mDPM; 509 ComponentName mDeviceAdminSample; 510 ... 511 long timeMs = 1000L*Long.parseLong(mTimeout.getText().toString()); 512 mDPM.setMaximumTimeToLock(mDeviceAdminSample, timeMs); 513 </pre> 514 <p>You can also programmatically tell the device to lock immediately:</p> 515 <pre> 516 DevicePolicyManager mDPM; 517 mDPM.lockNow();</pre> 518 519 <h4 id="wipe">Perform data wipe</h4> 520 521 <p>You can use the {@link android.app.admin.DevicePolicyManager} method 522 {@link android.app.admin.DevicePolicyManager#wipeData wipeData()} to reset the device to factory settings. This is useful 523 if the device is lost or stolen. Often the decision to wipe the device is the 524 result of certain conditions being met. For example, you can use 525 {@link android.app.admin.DevicePolicyManager#setMaximumFailedPasswordsForWipe setMaximumFailedPasswordsForWipe()} to state that a device should be 526 wiped after a specific number of failed password attempts.</p> 527 <p>You wipe data as follows:</p> 528 <pre> 529 DevicePolicyManager mDPM; 530 mDPM.wipeData(0);</pre> 531 <p>The {@link android.app.admin.DevicePolicyManager#wipeData wipeData()} method takes as its parameter a bit mask of 532 additional options. Currently the value must be 0. </p> 533