Enroll and provision a device  |  Android Management API  |  Google for Developers (2024)

Provisioning is the process of setting up a device to be managed viapolicies by anenterprise. During theprocess a device installs Android Device Policy, which is used to receive andenforce policies.If provisioning is successful, the API creates adevices object,binding the device to an enterprise.

Android Management API uses enrollment tokens to trigger the provisioningprocess. The enrollment token and provisioning method you use establishes adevice's ownership (personally-owned or company-owned) and management mode(work profile or fully managed device).

Personally-owned devices

Android 5.1+

Devices owned by employees can be set up with a work profile. A work profileprovides a self-contained space for work apps and data, separate from personalapps and data. Most app, data, and other management policiesapply to the work profile only, while the employee's personal apps and dataremain private.

To set up a work profile on a personally-owned device, create an enrollmenttoken (ensureallowPersonalUsage is set to PERSONAL_USAGE_ALLOWED) and use one of thefollowing provisioning methods:

• Add work profile from "Settings"
• Download Android Device Policy
• Enrollment token link
• Sign-in URL

Company-owned devices for work and personal use

Android 8+

Setting up a company-owned device with a work profile enables the device forboth work and personal use. On company-owned devices with work profiles:

• Most app, data, and other management policies apply to the work profileonly.
• The employee's personal profile remains private. However, enterprises canenforce certain device-wide policiesand personal usage policies.
• Enterprises can use blockScope to enforce compliance actions on an entire device or only its work profile.
• devices.deleteand device commandsapply to an entire device.

To set up a company-owned device with a work profile, create an enrollmenttoken (ensureallowPersonalUsage is set to PERSONAL_USAGE_ALLOWED) and use one of thefollowing provisioning methods:

• Zero-touch enrollment
• QR code
• Sign-in URL
• DPC identifier

Company-owned devices for work use only

Android 5.1+

Full device management is suitable for company-owned devices intendedexclusively for work purposes. Enterprises can manage all apps on the device andcan enforce the full spectrum of Android Management API's policies and commands.

It's also possible to lock a device down (via policy)to a single app or small set of apps to serve a dedicated purpose or use case.This subset of fully managed devices is referred to as dedicated devices.

To set up full management on a company-owned device, create an enrollment token(ensure allowPersonalUsage is set to PERSONAL_USAGE_DISALLOWED) and use oneof the following provisioning methods:

• Zero-touch enrollment
• QR code
• Sign-in URL (not suitable for dedicated devices)
• NFC
• DPC identifier

Policies can impact the generation of the UI during device provisioning.Such policies are:

• PasswordPolicyScope: This determines password requirements.
• PermittedInputMethods: This determines package input methods.
• PermittedAccessibilityServices: This determines which accessibility services are permitted for fully managed devices and work profile.
• SetupActions: This determines what actions are executed during setup.
• ApplicationsPolicy: This determines the policy for an individual app.

If you wish for password steps to be shown alongside installation of work apps and device register cards during device provisioning, we suggest updating your policies to delay initiation of the UI generation by keeping the device in a quarantine state, which occurs if enrolled without an associated policy, until specifying the final desired policy for device setup populated with items relevant to your setup needs. Once provisioning of the device has been completed, you can change the policy as required.

Create an enrollment token

You need an enrollment token for each device that you want to enroll (you canuse the same token for multiple devices). To request an enrollment token, callenterprises.enrollmentTokens.create.Enrollment tokens expire after one hour by default, but you can specify acustom expiration time (duration) up to approximately 10,000 years.

A successful request returns an enrollmentToken object containing anenrollmentTokenId and a qrcode that IT admins and end users can use toprovision devices.

Specify a policy

You might also want to specify a policyName in the request to apply a policyat the same time a device is enrolled. If you don't specify a policyName,see Enroll a device without a policy.

Specify a user

The enrollmentTokens resource includes a userAccountIdentifier field. If youdon't specify a userAccountIdentifier, the API will silently create a new,unique account each time a device is enrolled with the enrollment token.

If you specify a userAccountIdentifier that hasn't been activated on a device,the API will silently create a account for the identifier when a device isenrolled with the enrollment token.

If you specify a userAccountIdentifier that was previously activated onanother device, the API will re-use the existing user and activate it on eachdevice that is enrolled with the enrollment token. Best practice: Anaccount should not be activated more than 10 devices.

Specify personal usage

allowPersonalUsage determines if a work profile can be added to the deviceduring provisioning. Set to PERSONAL_USAGE_ALLOWED to allow a user to create awork profile (required for personally-owned devices, optional for company-owneddevices).

About QR codes

QR codes work as an efficient device provisioning method for enterprises thatmaintain many different policies. The QR code returned fromenterprises.enrollmentTokens.create is made up of a payload of key-value pairscontaining an enrollment token and all the information that’s needed for AndroidDevice Policy to provision a device.

Example QR code bundle

The bundle includes the download location of Android Device Policy and anenrollment token.

{ "android.app.extra.PROVISIONING_DEVICE_ADMIN_COMPONENT_NAME": "com.google.android.apps.work.clouddpc/.receivers.CloudDeviceAdminReceiver", "android.app.extra.PROVISIONING_DEVICE_ADMIN_SIGNATURE_CHECKSUM": "I5YvS0O5hXY46mb01BlRjq4oJJGs2kuUcHvVkAPEXlg", "android.app.extra.PROVISIONING_DEVICE_ADMIN_PACKAGE_DOWNLOAD_LOCATION": "https://play.google.com/managed/downloadManagingApp?identifier=setup", "android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE":{ "com.google.android.apps.work.clouddpc.EXTRA_ENROLLMENT_TOKEN": "{enrollment-token}" }}

You can use the QR code returned from enterprises.enrollmentTokens.createdirectly or customize it. For a full list of properties that you can include ina QR code bundle, see Create a QR code.

To convert the qrcode string into a scannable QR code, use a QR code generatorsuch as ZXing.

Provisioning methods

This section describes different methods for provisioning a device.

Add work profile from "Settings"

Android 5.1+

To set up a work profile on their device, a user can:

1. Go to Settings > Google > Set up & restore.
2. Tap Set up your work profile.

These steps initiate a setup wizard that downloads Android Device Policy on thedevice. Next, the user will be prompted to scan a QR code ormanually enter an enrollment token to complete the work profile setup.

Download Android Device Policy

Android 5.1+

To set up a work profile on their device, a user can download Android DevicePolicy from the Google Play Store. After the app is installed, the user will beprompted to QR code or manually enter an enrollment token tocomplete the work profile setup.

Enrollment token link

Android 5.1+

Using the enrollment token returned from enrollmentTokens.create or theenterprise's signinEnrollmentToken(see Sign-in URL below), generate a URL with the followingformat:

https://enterprise.google.com/android/enroll?et=<enrollmentToken>

You can provide this URL to IT admins, who can provide it to their end users.When an end user opens the link from their device, they will be guided throughthe work profile setup.

Sign-in URL

With this method, users are provided with a URL that prompts them for theircredentials. Based on their credentials, you can calculate the appropriatepolicy for the user before proceeding with device provisioning. For example:

1. Specify your sign-in URL in enterprises.signInDetails[].Set allowPersonalUsage to PERSONAL_USAGE_ALLOWED if you want to allow auser to create a work profile (required for personally-owned devices,optional for company-owned devices).

   Add the resulting signinEnrollmentToken as provisioning extra to aQR code, NFC payload, orZero-touch configuration. Alternatively, you canprovide the signinEnrollmentToken to users directly.

2. Choose an option:

   1. Company-owned devices: After turning on a new or factory-resetdevice, pass the signinEnrollmentToken to the device (via QR code, NFCbump, etc.) or ask users need to enter the token manually. The devicewill open the sign-in URL specified in Step 1.
   2. Personally-owned devices: Ask users to add a work profile from “Settings”.When prompted, the user scans a QR code containing thesigninEnrollmentToken or enters the token manually. The device willopen the sign-in URL specified in Step 1.
   3. Personally-owned devices: Provide users with an enrollment token link,where the enrollment token is the signinEnrollmentToken. The devicewill open the sign-in URL specified in Step 1.

3. Your sign-in URL should prompt users to enter their credentials. Based ontheir identity, you can determine the appropriate policy.

4. Call enrollmentTokens.create,specifying the appropriate policyId based on the user's credentials.

5. Return the enrollment token generated in Step 4 via URL redirect, in the formhttps://enterprise.google.com/android/enroll?et=<token>.

QR code method

Android 7.0+

To provision a company-owned device, you can generate a QR codeand display it in your EMM console:

1. On a new or factory-reset device, the user (typically an IT admin) taps thescreen six times in the same spot. This triggers the device to prompt theuser to scan a QR code.
2. The user scans the QR code that you display in your management console (orsimilar application) to enroll and provision the device.

NFC method

Android 6.0+

This method requires you to create an NFC programmer app that contains theenrollment token, initial policies and Wi-Fi configuration, settings, and allother provisioning details required by your customer to provision a fullymanaged or dedicated device. When you or your customer installs the NFCprogrammer app on an Android device, that device becomes the programmer device.

Detailed guidance on how to support the NFC method is available in the PlayEMM API developerdocumentation. The site also includes sample code of the defaultparameters pushedto a device on an NFC bump. To install Android Device Policy, set the downloadlocation of the device admin package to:

https://play.google.com/managed/downloadManagingApp?identifier=setup

DPC identifier method

If Android Device Policy can't be added via QR code or NFC a user or IT admincan follow these steps to provision a company-owned device:

1. Follow the setup wizard on a new or factory-reset device.
2. Enter Wi-Fi login details to connect the device to the internet.
3. When prompted to sign in, enter afw#setup, which downloadsAndroid Device Policy.
4. Scan a QR code or manually enter an enrollment token toprovision the device.

Zero-touch enrollment

Android 8.0+ (Pixel 7.1+)

Devices purchased from an authorized zero-touch resellerare eligible for zero-touch enrollment, a streamlined method for preconfiguringdevices to provision themselves automatically on first boot.

Organizations can create configurations containing provisioning details fortheir zero-touch devices, either through the zero-touch enrollment portalor using your EMM console (see the zero-touch customer API).On first boot, a zero-touch device checks if it's been assigned a configuration.If so, the device downloads Android Device Policy, which then completes setup ofthe device using the provisioning extras specified in its assignedconfiguration.

If your customers use the zero-touch enrollment portal,they need to select Android Device Policy as the EMM DPC for each configurationthey create. Detailed instructions on how to use the portal, including how tocreate and assign configurations to devices, are available in the AndroidEnterprise help center.

If you prefer your customers to set and assign configurations directly fromyour EMM console, you need to integrate with the zero-touch customer API.When creating a configuration,you specify provisioning extras in the dpcExtras field. The JSON snippetbelow shows a basic example of what to include in dpcExtras, with an addedsign-in token.

{ "android.app.extra.PROVISIONING_DEVICE_ADMIN_COMPONENT_NAME":"com.google.android.apps.work.clouddpc/.receivers.CloudDeviceAdminReceiver", "android.app.extra.PROVISIONING_DEVICE_ADMIN_SIGNATURE_CHECKSUM":"I5YvS0O5hXY46mb01BlRjq4oJJGs2kuUcHvVkAPEXlg", "android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE":{ "com.google.android.apps.work.clouddpc.EXTRA_ENROLLMENT_TOKEN":"{Sign In URL token}" }}

Launch an app during setup

In policies, you can specify one app for Android Device Policy to launchduring device or work profile setup. For example, you could launch a VPN appso users can configure VPN settings as part of the setup process. The app mustreturn RESULT_OKto signal completion and allow Android Device Policy to complete device orwork profile provisioning. To launch an app during setup:

Ensure the app's installType is REQUIRED_FOR_SETUP. If the app can't beinstalled or launched on the device, provisioning will fail.

{ "applications":[ { "packageName":"com.my.vpnapp.", "installType":"REQUIRED_FOR_SETUP" } ]}

Add the app's package name to setupActions. Use title and description tospecify user-facing instructions.

{ "setupActions":[ { "title":{ "defaultMessage":"Configure VPN" }, "description":{ "defaultMessage":"Enable your VPN client to access corporate resources." }, "launchApp":{ "packageName":"com.my.vpnapp." } } ]}

To distinguish that an app is launched from launchApp, the activity that'sfirst launched as part of the app contains the boolean intent extracom.google.android.apps.work.clouddpc.EXTRA_LAUNCHED_AS_SETUP_ACTION (set totrue). This extra allows you to customize your app based on whether it'slaunched from setupActions or by a user.

After the app returns RESULT_OK, Android Device Policy completes anyremaining steps required to provision the device or work profile.

Cancelling enrollment during setup

The app launched asSetupActioncan cancel enrollment returning RESULT_CANCELED.

Cancelling the enrollment resets a company-owned device or deletes the workprofile on a personally-owned device.

Note: Cancelling the enrollment triggers the action without a userconfirmation dialog. It is responsibility of the app to show an appropriateerror dialog to user prior to returning result.

Apply a policy to newly enrolled devices

The method you use to apply policies to newly enrolled devices is up to you andthe requirements of your customers. Here we present three different approaches:

• (Recommended) When creating an enrollment token,you can specify the name of the policy (policyName) that will be initiallylinked to the device. When you enroll a device with the token, the policy isautomatically applied to the device.

• Set a policy as the default policy for an enterprise.If no policy name is specified in the enrollment token and there is a policywith the name enterprises/<enterprise_id>/policies/default, each new deviceis automatically linked to the default policy at the time of enrollment.

• Subscribe to a Cloud Pub/Sub topicto receive notifications about newly enrolled devices. In response to anENROLLMENTnotification, call enterprises.devices.patchto link the device with a policy.

Enroll a device without a policy

If a device is enrolled without a valid policy, then the device is placed intoquarantine. Quarantined devices are blocked from all device functions untilthe device is linked to a policy.

If a device is not linked to a policy in five minutes, then device enrollmentfails and the device is factory reset. The quarantine device state gives you theopportunity to implement licensing checks or other enrollment validationprocesses as part of your solution.

Example licensing check workflow

1. A device is enrolled without a default policy or specific policy.
2. Check how many licenses the enterprise has remaining.
3. If there are licences available, use devices.patchto attach a policy to the device, and then decrement your license count. Ifthere are no licenses available, use devices.patch to disable the device.Alternatively, the API factory resets any device that is not attached to apolicy within five minutes of enrollment.