diff options
author | Scott Main <smain@google.com> | 2011-12-15 10:43:46 -0800 |
---|---|---|
committer | Android Git Automerger <android-git-automerger@android.com> | 2011-12-15 10:43:46 -0800 |
commit | fbc17eccea267c7cee344ac7e7898709f86b37df (patch) | |
tree | f5280d507cbf7a9a84827438634446bc852765bd | |
parent | ecaee21d3050f34bcb8c6d4bafec9764ab1a7027 (diff) | |
parent | cf927f229f55849caf3461621023b5bd61908334 (diff) | |
download | frameworks_base-fbc17eccea267c7cee344ac7e7898709f86b37df.zip frameworks_base-fbc17eccea267c7cee344ac7e7898709f86b37df.tar.gz frameworks_base-fbc17eccea267c7cee344ac7e7898709f86b37df.tar.bz2 |
am cf927f22: am aed4ced6: Android U Class: Developing Android Applications for the Enterprise. This class uses a sample app.
* commit 'cf927f229f55849caf3461621023b5bd61908334':
Android U Class: Developing Android Applications for the Enterprise. This class uses a sample app.
-rw-r--r-- | Android.mk | 5 | ||||
-rwxr-xr-x | docs/html/images/training/device-mgmt-activate-device-admin.png | bin | 0 -> 42791 bytes | |||
-rw-r--r-- | docs/html/resources/resources-data.js | 10 | ||||
-rw-r--r-- | docs/html/shareables/training/DeviceManagement.zip | bin | 0 -> 19978 bytes | |||
-rw-r--r-- | docs/html/training/enterprise/device-management-policy.jd | 220 | ||||
-rw-r--r-- | docs/html/training/enterprise/index.jd | 51 |
6 files changed, 285 insertions, 1 deletions
@@ -500,7 +500,10 @@ web_docs_sample_code_flags := \ -samplecode $(sample_dir)/XmlAdapters \ resources/samples/XmlAdapters "XML Adapters" \ -samplecode $(sample_dir)/TtsEngine \ - resources/samples/TtsEngine "Text To Speech Engine" + resources/samples/TtsEngine "Text To Speech Engine" \ + -samplecode $(sample_dir)/training/device-management-policy \ + resources/samples/training/device-management-policy "Device Management Policy" + ## SDK version identifiers used in the published docs # major[.minor] version for current SDK. (full releases only) diff --git a/docs/html/images/training/device-mgmt-activate-device-admin.png b/docs/html/images/training/device-mgmt-activate-device-admin.png Binary files differnew file mode 100755 index 0000000..1be1831 --- /dev/null +++ b/docs/html/images/training/device-mgmt-activate-device-admin.png diff --git a/docs/html/resources/resources-data.js b/docs/html/resources/resources-data.js index d96bfde..779525a 100644 --- a/docs/html/resources/resources-data.js +++ b/docs/html/resources/resources-data.js @@ -508,6 +508,16 @@ var ANDROID_RESOURCES = [ } }, { + tags: ['sample', 'new'], + path: 'samples/training/device-management-policy/index.html', + title: { + en: 'Device Policy Management' + }, + description: { + en: 'This is a security-aware sample application that demonstrates the enforcement of device administration policies on Android 2.2 or above platforms.' + } + }, + { tags: ['sample'], path: 'samples/Home/index.html', title: { diff --git a/docs/html/shareables/training/DeviceManagement.zip b/docs/html/shareables/training/DeviceManagement.zip Binary files differnew file mode 100644 index 0000000..9f7ec69 --- /dev/null +++ b/docs/html/shareables/training/DeviceManagement.zip diff --git a/docs/html/training/enterprise/device-management-policy.jd b/docs/html/training/enterprise/device-management-policy.jd new file mode 100644 index 0000000..52f0e37 --- /dev/null +++ b/docs/html/training/enterprise/device-management-policy.jd @@ -0,0 +1,220 @@ +page.title=Enhancing Security with Device Management Policies +parent.title=Developing Android Applications for the Enterprise +parent.link=index.html +@jd:body + + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#DeclarePolicy">Define and Declare Your Policy</a></li> + <li><a href="#CreateDeviceAdminReceiver">Create a Device Administration Receiver</a></li> + <li><a href="#ActivateDeviceAdmin">Activate the Device Administrator</a></li> + <li><a href="#ImplementDevicePolicyController">Implement the Device Policy Controller</a></li> +</ol> + +<!-- related docs (NOT javadocs) --> +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}guide/topics/admin/device-admin.html">Device Administration</a></li> +</ul> + +<h2>Try it out</h2> + +<div class="download-box"> + <a href="http://developer.android.com/shareables/training/DeviceManagement.zip" +class="button">Download the sample</a> + <p class="filename">DeviceManagement.zip</p> +</div> + +</div> +</div> + + +<p>Since Android 2.2 (API level 8), the Android platform offes system-level device management +capabilities through the Device Administration APIs.</p> + +<p>In this lesson, you will learn how to create a security-aware application that manages access to +its content by enforcing device management policies. Specifically, the application can be configured +such that it ensures a screen-lock password of sufficient strength is set up before displaying +restricted content to the user.</p> + + +<h2 id="DeclarePolicy">Define and Declare Your Policy</h2> + +<p>First, you need to define the kinds of policy to support at the functional level. Policies may +cover screen-lock password strength, expiration timeout, encryption, etc.</p> + +<p>You must declare the selected policy set, which will be enforced by the application, in the +<code>res/xml/device_admin.xml</code> file. The Android manifest should also reference the +declared policy set.</p> + +<p>Each declared policy corresponds to some number of related device policy methods in {@link +android.app.admin.DevicePolicyManager} (defining minimum password length and minimum number of +uppercase characters are two examples). If an application attempts to invoke methods whose +corresponding policy is not declared in the XML, this will result in a {@link +java.lang.SecurityException} at runtime. Other permissions, +such as <code>force-lock</code>, are available if the application intends to manage +other kinds of policy. As you'll see later, as part of the device administrator activation process, +the list of declared policies will be presented to the user on a system screen.</p> + +<p>The following snippet declares the limit password policy in <code>res/xml/device_admin.xml</code>:</p> + +<pre> +<device-admin xmlns:android="http://schemas.android.com/apk/res/android"> + <uses-policies> + <limit-password /> + </uses-policies> +</device-admin> +</pre> + +<p>Policy declaration XML referenced in Android manifest:</p> + +<pre> +<receiver android:name=".Policy$PolicyAdmin" + android:permission="android.permission.BIND_DEVICE_ADMIN"> + <strong><meta-data android:name="android.app.device_admin" + android:resource="@xml/device_admin" /></strong> + <intent-filter> + <action android:name="android.app.action.DEVICE_ADMIN_ENABLED" /> + </intent-filter> +</receiver> +</pre> + + +<h2 id="CreateDeviceAdminReceiver">Create a Device Administration Receiver</h2> + +<p>Create a Device Administration broadcast receiver, which gets notified of events related to the policies you’ve declared to support. An application can selectively override callback methods.</p> + +<p>In the sample application, Device Admin, when the device administrator is deactivated by the +user, the configured policy is erased from the shared preference. You should consider implementing +business logic that is relevant to your use case. For example, the application might take some +actions to mitigate security risk by implementing some combination of deleting sensitive data on the +device, disabling remote synchronization, alerting an administrator, etc.</p> + +<p>For the broadcast receiver to work, be sure to register it in the Android manifest as illustrated in the above snippet.</p> + +<pre> +public static class PolicyAdmin extends DeviceAdminReceiver { + + @Override + public void onDisabled(Context context, Intent intent) { + // Called when the app is about to be deactivated as a device administrator. + // Deletes previously stored password policy. + super.onDisabled(context, intent); + SharedPreferences prefs = context.getSharedPreferences(APP_PREF, Activity.MODE_PRIVATE); + prefs.edit().clear().commit(); + } +} +</pre> + + +<h2 id="ActivateDeviceAdmin">Activate the Device Administrator</h2> + +<p>Before enforcing any policies, the user needs to manually activate the application as a device +administrator. The snippet below illustrates how to trigger the settings activity in which the +user can activate your application. It is good practice to include the explanatory text to highlight +to users why the application is requesting to be a device administrator, by specifying the +{@link android.app.admin.DevicePolicyManager#EXTRA_ADD_EXPLANATION} extra in the intent.</p> + +<div class="figure" style="width:220px"> +<img src="/images/training/device-mgmt-activate-device-admin.png" /> +<p class="img-caption"><strong>Figure 1.</strong> The user activation screen in which you can +provide a description of your device policies.</p> +</div> + +<pre> +if (!mPolicy.isAdminActive()) { + + Intent activateDeviceAdminIntent = + new Intent(DevicePolicyManager.ACTION_ADD_DEVICE_ADMIN); + + activateDeviceAdminIntent.putExtra( + DevicePolicyManager.EXTRA_DEVICE_ADMIN, + mPolicy.getPolicyAdmin()); + + // It is good practice to include the optional explanation text to + // explain to user why the application is requesting to be a device + // administrator. The system will display this message on the activation + // screen. + activateDeviceAdminIntent.putExtra( + DevicePolicyManager.EXTRA_ADD_EXPLANATION, + getResources().getString(R.string.device_admin_activation_message)); + + startActivityForResult(activateDeviceAdminIntent, + REQ_ACTIVATE_DEVICE_ADMIN); +} +</pre> + +<p>If the user chooses "Activate," the application becomes a device administrator and can begin +configuring and enforcing the policy.</p> + +<p>The application also needs to be prepared to handle set back situations where the user abandons +the activation process by hitting the Cancel button, the Back key, or the Home key. Therefore, +{@link android.app.Activity#onResume onResume()} in the Policy Set Up Activity needs to have logic +to reevaluate the condition and present the Device Administrator Activation option to the user if +needed.</p> + + +<h2 id="ImplementDevicePolicyController">Implement the Device Policy Controller</h2> + +<p>After the device administrator is activated successfully, the application then configures Device +Policy Manager with the requested policy. Keep in mind that new policies are being added to +Android with each release. It is appropriate to perform version checks in your application if using +new policies while supporting older versions of the platform. For example, the Password Minimum +Upper Case policy is only available with API level 11 (Honeycomb) and above. The following code +demonstrates how you can check the version at runtime.</p> + +<pre> +DevicePolicyManager mDPM = (DevicePolicyManager) + context.getSystemService(Context.DEVICE_POLICY_SERVICE); +ComponentName mPolicyAdmin = new ComponentName(context, PolicyAdmin.class); +... +mDPM.setPasswordQuality(mPolicyAdmin, PASSWORD_QUALITY_VALUES[mPasswordQuality]); +mDPM.setPasswordMinimumLength(mPolicyAdmin, mPasswordLength); +if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) { + mDPM.setPasswordMinimumUpperCase(mPolicyAdmin, mPasswordMinUpperCase); +} +</pre> + +<p>At this point, the application is able to enforce the policy. While the application has no access +to the actual screen-lock password used, through the Device Policy Manager API it can determine +whether the existing password satisfies the required policy. If it turns out that the existing +screen-lock password is not sufficient, the device administration API does not automatically take +corrective action. It is the application’s responsibility to explicitly launch the system +password-change screen in the Settings app. For example:</p> + +<pre> +if (!mDPM.isActivePasswordSufficient()) { + ... + // Triggers password change screen in Settings. + Intent intent = + new Intent(DevicePolicyManager.ACTION_SET_NEW_PASSWORD); + startActivity(intent); +} +</pre> + +<p>Normally, the user can select from one of the available lock mechanisms, such as None, Pattern, +PIN (numeric), or Password (alphanumeric). When a password policy is configured, those password +types that are weaker than those defined in the policy are disabled. For example, if the +“Numeric” password quality is configured, the user can select either PIN (numeric) or Password +(alphanumeric) password only.</p> + +<p>Once the device is properly secured by setting up a proper screen-lock password, the application +allows access to the secured content.</p> + +<pre> +if (!mDPM.isAdminActive(..)) { + // Activates device administrator. + ... +} else if (!mDPM.isActivePasswordSufficient()) { + // Launches password set-up screen in Settings. + ... +} else { + // Grants access to secure content. + ... + startActivity(new Intent(context, SecureActivity.class)); +} +</pre> diff --git a/docs/html/training/enterprise/index.jd b/docs/html/training/enterprise/index.jd new file mode 100644 index 0000000..05bb29c --- /dev/null +++ b/docs/html/training/enterprise/index.jd @@ -0,0 +1,51 @@ +page.title=Developing Android Applications for the Enterprise + +trainingnavtop=true +startpage=true +next.title=Enhancing Security with Device Management Policies +next.link=device-management-policy.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<!-- Required platform, tools, add-ons, devices, knowledge, etc. --> +<h2>Dependencies and prerequisites</h2> +<ul> + <li>Android 2.0 (API Level 5) or higher</li> + <li>Experience with <a href="{@docRoot}guide/topics/media/mediaplayer.html">Media +Playback</a></li> +</ul> + +<!-- related docs (NOT javadocs) --> +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}guide/topics/admin/device-admin.html">Device Administration</a></li> +</ul> + +<h2>Try it out</h2> + +<div class="download-box"> + <a href="http://developer.android.com/shareables/training/DeviceManagement.zip" +class="button">Download the sample</a> + <p class="filename">DeviceManagement.zip</p> +</div> + +</div> +</div> + + +<p>In this class, you'll learn APIs and techniques you can use when developing applications +for the enterprise.</p> + + +<h2>Lessons</h2> + + +<dl> + <dt><b><a href="device-management-policy.html">Enhancing Security with Device Management +Policies</a></b></dt> + <dd>In this lesson, you will learn how to create a security-aware application that manages +access to its content by enforcing device management policies</dd> +</dl> |