Important: We are no longer accepting new registrations for the Play EMM API. Learn more.

Provision user accounts

Identity provisioning (or account provisioning) is the process of setting up accounts and establishing connections among the three systems, and in some cases setting up connections between users and their devices.

In an Android enterprise environment, as many as three different systems hold account information:

The organization’s user directory is the definitive source of information about users.
You (the EMM solution provider) must maintain at least a minimal directory of the organization’s users.
Google maintains some information about managed Google Play Accounts and Google Accounts to provide app management through Google Play.

A Users resource represents an account associated with an enterprise. The account can be specific to a device, or can be associated with an individual who has multiple devices (mobile phone, tablet, and so on) and uses the account across them all. The account can provide access to managed Google Play only, or to other Google services, depending on how you set up your customer's enterprise:

Managed Google Play Accounts provide a transparent means for enterprises to create user or device accounts automatically through their enterprise mobility management (EMM) solution provider. These accounts provide access to managed Google Play only.
Google Accounts are existing accounts managed by Google, and require synchronization to Google Account sources.

Table 1: Users API fields and methods

	Managed Google Play Accounts	Google managed accounts
Field
id
kind
accountIdentifier	A unique identifier that you create and map to the ID (`userId`) returned from Google Play. Don’t use personally identifiable information (PII).	Not set.
accountType	deviceAccount, userAccount	userAccount
displayName	The name you display in UI items, such as within Google Play. Don’t use personally identifiable information.	Not set.
managementType	emmManaged	googleManaged, emmManaged
primaryEmail	Not set.	This field is the primary key by which you manage synchronization from Google-managed domain accounts to user accounts in your system.
Methods
delete
generateAuthenticationToken
generateToken
get
getAvailableProductSet
insert
list
revokeToken
setAvailableProductSet
update

Managed Google Play Accounts

There are two types of managed Google Play Accounts:

User account: Provides a single user access to managed Google Play from all their devices. You must provision user accounts for your users—they don’t have the credentials to add managed Google Play Accounts themselves.; To create a user account, call Users.insert. Set the account type to userType, and set an accountIdentifier, which uniquely references the user within the enterprise.; Best practice: Don’t use the same account on more than 10 devices.
Device account: Provides access to managed Google Play from a single device. If an authentication token has been issued for a device account, a new request for an authentication token for that device account deactivates the previous token. Each device should have its own separate licenses for apps.; To create a device account, call Users.insert and set the account type to deviceType.

You create and maintain a mapping between the user or device identities and the corresponding managed Google Play Accounts, and you manage the accounts through their life cycle. The organization doesn’t need any direct control over these managed Google Play Accounts, as the accounts exist purely for application management.

Requirements for EMM consoles and servers

Managed Google Play Accounts are created on-demand, programmatically, using the Google Play EMM APIs and Android framework APIs across the components of your EMM solution (EMM console, EMM server, and DPC). These components interact at runtime to create a user account and to provision the work profile on the target device. Your EMM console or server must:

Provide a mechanism to create unique anonymous account identifiers (the accountIdentifier field) to use in the call to Users.insert. For example, you might use some internal value for the user ("sanjeev237389"), or a cryptic asset tag number ("asset#44448"). Avoid using personally identifiable information (PII) for the account identifier.
Store the mapping between the userId (returned from the insert call) and the accountIdentifier you select.

For requirements for your DPC, see Build a device policy controller.

Create a managed Google Play user account

A user signs in to your DPC using (typically) corporate credentials.
The DPC requests details about the user from the EMM server or console. Assuming the user is unknown to your system:
1. Submit request for new managed Google Play Account by calling Users.insert with values for new accountIdentifier, displayName, and accountType.
  - Your system must create the accountIdentifier. The account identifier must be a unique value across your system. Don’t use PII for the account identifier.
  - The displayName is shown in the account switcher of the Google Play Store and should have some meaning to the user (but not PII about the user). For example, the name could include the organization name or a generic name related to the EMM.
  - Set the accountType to userAccount or deviceAccount. A userAccount can be used on multiple devices, while a deviceAccount is specific to a single device. The accountType specified can be deviceType or userType.
  - Set the managementType to emmManaged.
2. Google Play processes the request, creates the account, and returns a userId.
3. Store the mapping between the accountIdentifier and the userId in your datastore.
4. Call Users.generateAuthenticationToken with the userId and the enterpriseId. Google Play returns an authentication token that can be used once, and which must be used within a few minutes.
5. Securely forward the authentication token to your DPC.
The DPC provisions the work profile and adds the account to the work profile or device.
The user can access managed Google Play within the work profile or device.

Admin accounts

When an admin creates an enterprise with managed Google Play Accounts, the Google Account they use can't be a G Suite account. The account they use becomes an owner for the enterprise, and the owner can add more owners and admins in the managed Google Play console.

Both Enterprises.get and Enterprises.completeSignup return a list of admin email addresses that are associated with an enterprise (enterprises with managed Google Play Accounts only).

Manage account life cycles

In a managed Google Play Accounts deployment, you're responsible for user and device account life cycles, which means you create, update, and delete these accounts.

You create the accounts during device provisioning, a process that involves your DPC app and your EMM console. For instructions, see the managed Google Play Accounts method.

To change an account’s information, call Users.update.

To delete an account, call Users.delete.

Admins can’t delete individual accounts, but they can delete an enterprise with managed Google Play Accounts. When they do this, the device and user accounts associated with the enterprise are eventually deleted, as described in Unenroll, re-enroll, delete.

Account expiration

Occasionally accounts or their tokens expire, which can happen for a number of reasons:

The authentication token that was obtained to add the account to the device has expired.
The account or enterprise has been deleted.
For device accounts, the account has been added to a new device and is therefore disabled on the old device.
Automatic abuse checks are triggered.

In most cases (unless the EMM is intentionally moving a device account to a new device), the best practice is to use the Play EMM API to request a new token from the EMM server, note the state of the account and enterprise and any returned errors, and then take appropriate action on the device. For example, refresh the token, or if the error isn't recoverable, reset or unenroll the device.

Google Play services version 9.0.00 notifies your DPC that the account has expired using the broadcast action:

When the managed Google Play Account is invalidated on a device, the DPC receives a broadcast with the following action:
```
com.google.android.gms.auth.ACCOUNT_REAUTH_REQUIRED
```
The broadcast intent contains a Parcelable extra with name account, which is the Account object of the invalidated account.
The DPC checks Account#name with the EMM server to identify the invalidated account.
The DPC either requests new credentials or a new account, following the same flow used to provision the device initially.

Google Accounts

For organizations that use Google Accounts, user accounts in an EMM’s solution mirror existing user accounts associated with another Google service (for example, G Suite). These accounts are googleManaged (Table 1) because Google's backend services are the source for the creation of and information about the account.

As an EMM, you can provide mechanisms in your console to facilitate the creation and ongoing synchronization of user accounts held in your system with their Google domain account sources using tools such as Google Cloud Directory Sync (GCDS) and the Google Admin SDK Directory API. for an overview of various approaches.) The Google-managed domain identity model requires that the user account exists in the context of your solution (EMM console, EMM server, perhaps in a datastore) before it can be provisioned on any of the user's devices in the context of a work profile.

During identity provisioning, the organization’s Google-managed domain is populated with user accounts. In some cases, users’ existing online identities (for example, their Microsoft Exchange accounts) are synchronized with their Google Accounts.

After the initial synchronization, but before apps are distributed to a user’s device, the user must activate their Google Account, as described in Activate accounts on devices. This activation allows the device to access managed Google Play.

Synchronize customer accounts

In a Google Accounts deployment, the organization can use the GCDS tool to synchronize the data in their G Suite domain with the data in their LDAP directory. Alternatively, you can use GCDS to do this on the organization’s behalf, if the organization gives you access.

The GCDS tool calls the Google Directory API and synchronizes usernames, but not passwords.

If the organization uses Microsoft Active Directory and wants to keep users' G Suite passwords in sync with their Active Directory passwords, then they—or you—can use the G Suite Password Sync (GSPS) tool with GCDS.

For GCDS instructions for admins, see Prepare your G Suite domain for synchronization.

Google Directory API

In a Google Accounts deployment, you can use the Google Directory API to synchronize active directories, passwords, or both:

Using the Directory API for directory-only sync. If you have read-only access to the organization’s managed Google domain, you can use the Google Directory API to get Google Account information, such as usernames (but not passwords) from Google. Because you’re unable to write any data to users’ Google Accounts, the organization is fully responsible for account life cycles.

Scenario 1 and SAML-based SSO authentication scenarios describe this situation more fully.

For information about using the Directory API in this way, see Retrieve all account users in the Directory API documentation.
Using the Directory API for directory and optional password sync. If you have read-write access to the organization’s managed Google domain, you can use the Google Directory API to get usernames, passwords, and other Google Account information. You can update this information and sync it with your own database, and you might have full or partial responsibility for account life cycles, depending on the solution that you’re offering to your customer.

Scenario 2 describes this situation more fully.

For more about using the Directory API to manage user account information, see the Directory API: User Accounts developer’s guide.

Google Accounts scenarios

A few typical Google Accounts identity-provisioning scenarios are described below.

Scenario 1: Customer responsible for account life cycles

Using the Directory API (with read-only access) and GCDS

In this scenario, your customer creates and maintains Google Accounts for its users.

You get user account information from the organization’s LDAP directory, and you correlate this with Google Account data that you get from Google via the Google Directory API.

The organization is fully responsible for account life cycles. For example, when a new Google Account is created, the organization adds the user to their LDAP directory. The next time you sync your database to the LDAP directory, your database receives information about this new user.

In this scenario:

You have read-only access to Google Accounts.
Your database acquires Google Account names, but no LDAP usernames or passwords.
You use the Google Directory API to get basic account information for your customer’s users. (The information available to you is the non-writable information returned by a Users.get request). You use this information to verify that users’ Google Accounts exist so that users can authenticate to their devices.
Your customer uses the GCDS tool to do a one-way sync to populate users’ Google Accounts. (The organization probably also uses GCDS for their own ongoing synchronization after identity provisioning is complete.) Optionally, the organization can also use the GSPS tool to sync not only usernames, but also passwords.

Scenario 2: EMM responsible for account life cycles

Using the Directory API with
read-write access

In this scenario, you handle the process of creating Google Accounts on behalf of your customer, and you're responsible for the users’ account life cycles.

For example, when user information changes in the organization’s LDAP directory, you're responsible for updating the user’s Google Account. GCDS is not used in this scenario.

In this scenario:

You have read-write access to Google Accounts.
Your database acquires Google Account names and LDAP usernames (and optionally, password hashes).
You use the Google Directory API on behalf of your customer to read and write account information for the organization’s users. (The information available to you is the non-writable information returned by a Users.get request). You use this information to verify that users’ Google Accounts exist so that users can authenticate to their devices.
The GCDS tool is not used.

SAML-based SSO authentication scenarios

In a Google Accounts deployment, you or your customer might use Security Assertion Markup Language (SAML) with an identity provider (IdP) to authenticate the Google Account associated with each user. You use the Google Account names as verification that users’ Google Accounts exist, which is needed for user authentication when users sign in to their devices. For example, SAML could be used in Scenario 2. For details about how to set this up, see Set up Single Sign-On (SSO) for G Suite accounts.

Activate accounts on devices

For apps to be distributed to a user device via managed Google Play, the user must sign in to the device during device provisioning:

In managed Google Play Accounts device provisioning, your DPC guides the user to sign in using credentials accepted by your EMM console, typically corporate email credentials.
In a Google Accounts deployment, your DPC guides the user to input their Google Account sign-in credentials. Normally these credentials match the ones with which users sign in to their corporate domain when they’re synchronized with GCDS or GSPS, or when an organization uses an IdP for authentication. This activates the user’s Google Account, generates a unique device ID, and binds the user’s Google Account identity and the device ID of their device.