*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. ![](https://developers.google.com/static/android/work/play/emm-api/images/3-systems.png) 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`](https://developers.google.com/android/work/play/emm-api/v1/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](https://developers.google.com/android/work/overview#customer_onboarding): - **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 | Yes | Yes | | kind | Yes | Yes | | 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 | Yes | No | | generateAuthenticationToken | Yes | No | | generateToken | No | Yes | | get | Yes | Yes | | getAvailableProductSet | Yes | Yes | | insert | Yes | No | | list | No | Yes | | revokeToken | No | Yes | | setAvailableProductSet | Yes | Yes | | update | Yes | No | *** ** * ** *** ## 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`](https://developers.google.com/android/work/play/emm-api/v1/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`](https://developers.google.com/android/work/play/emm-api/v1/user s/insert) and set the account type to `deviceType`. ![](https://developers.google.com/static/android/work/play/emm-api/images/mgpa-scenario.png) 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 lifecycle. 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](https://developers.google.com/android/work/play/emm-api/prov-devices) . 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`](https://developers.google.com/android/work/play/emm-api/v1/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. > [!NOTE] > **Note:** When you create a managed Google Play Account, use an anonymous identifier, one that doesn't reveal the user's actual identity to Google. For example: > > - Set `accountIdentifier` to an existing internal ID or a new mapping that you create. Don't use the user's email address or name. > - Leave the `displayName` property unset, or set it to something generic for you or the organization, for example "ACME, Inc." For requirements for your DPC, see [Build a device policy controller](https://developer.android.com/work/dpc/build-dpc.html). ### Create a managed Google Play user account 1. A user signs in to your DPC using (typically) corporate credentials. 2. 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`](https://developers.google.com/android/work/play/emm-api/v1/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`](https://developers.google.com/android/work/play/emm-api/v1/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. 3. The DPC provisions the work profile and adds the account to the work profile or device. 4. The user can access managed Google Play within the work profile or device. > [!NOTE] > **Note:** The `userId` is specific to an EMM and cannot be used with another EMM. If an enterprise unenrolls from one EMM and enrolls with another, the `userId` isn't recognized by the new EMM. EMMs can use [Users.delete](https://developers.google.com/android/work/play/emm-api/v1/users/delete) to delete EMM-managed users. ### Admin accounts When an admin [creates an enterprise with managed Google Play Accounts](https://developers.google.com/android/work/play/emm-api/create-enterprise#managed_google_play_accounts_enterprise_enrollment), the Google Account they use can't be a Google Workspace 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`](https://developers.google.com/android/work/play/emm-api/v1/enterprises/get) and [`Enterprises.completeSignup`](https://developers.google.com/android/work/play/emm-api/v1/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](https://developers.google.com/android/work/play/emm-api/prov-devices#managed_google_play_accounts_method). > [!NOTE] > **Important privacy note:** When you create a managed Google Play Account, use an anonymous identifier, one that doesn't reveal actual user identity to Google. For example: > > - Set `accountIdentifier` to an existing internal ID or a new mapping that you create. Don't use the user's email address or name. > - Leave the `displayName` property unset, or set it to something generic for you or the organization, for example "ACME, Inc." To change an account's information, call [Users.update](https://developers.google.com/android/work/play/emm-api/v1/users/update). To delete an account, call [Users.delete](https://developers.google.com/android/work/play/emm-api/v1/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](https://developers.google.com/android/work/play/emm-api/create-enterprise#unenroll_re-enroll_or_delete_an_enterprise). ### Account expiration Occasionally accounts or their tokens expire, which can happen for a number of reasons: - The [authentication token](https://developers.google.com/android/work/play/emm-api/v1/users/generateAuthenticationToken) that was obtained to add the account to the device has expired. - The account or enterprise has been [deleted](https://developers.google.com/android/work/play/emm-api/create-enterprise#unenroll_re-enroll_or_delete_an_enterprise). - 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. - If a device is offline for more than 270 days, its information may be deleted due to a batch cleanup process. 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, renew the token, or if the error isn't recoverable, reset or unenroll the device. To properly renew the token you should: 1. Call[`users.generateAuthenticationToken`](https://developers.google.com/android/work/play/emm-api/v1/users/generateAuthenticationToken) to request a new authentication token for the account. 2. If the call is successful, remove the existing account and add the new account using the DPC support library. 3. If the call is unsuccessful, remove the account from the device and create a new user using [`users.insert`](https://developers.google.com/android/work/play/emm-api/v1/users/insert), generate an authentication token and add the account to the device. [Google Play services](https://developers.google.com/android/guides/overview) version 9.0.00 notifies your DPC that the account has expired using the broadcast action: 1. 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 `https://developer.android.com/reference/android/accounts/Account.html` object of the invalidated account. 2. The DPC checks `https://developer.android.com/reference/android/accounts/Account.html#name` with the EMM server to identify the invalidated account. 3. The DPC either requests new credentials or a new account, following the same flow used to [provision the device](https://developers.google.com/android/work/play/emm-api/prov-devices#managed_google_play_accounts_method) 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, Google Workspace). These accounts are `googleManaged` ([Table 1](https://developers.google.com/android/work/play/emm-api/user-accounts#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)](https://support.google.com/a/answer/106368) and the [Google Admin SDK Directory API](https://developers.google.com/admin-sdk/directory/). 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](https://developers.google.com/android/work/play/emm-api/user-accounts#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 Google Workspace 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' Google Workspace passwords in sync with their Active Directory passwords, see [Get ready to use Password Sync](https://knowledge.workspace.google.com/admin/users/get-ready-to-use-password-sync). For GCDS instructions for admins, see [Authorize your Google Account](https://support.google.com/a/answer/6126573). ### 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](https://developers.google.com/android/work/play/emm-api/user-accounts#scenario-1) and [SAML-based SSO authentication scenarios](https://developers.google.com/android/work/play/emm-api/user-accounts#scenario-saml) describe this situation more fully. For information about using the Directory API in this way, see [Retrieve all account users](https://developers.google.com/admin-sdk/directory/v1/guides/manage-users#get_all_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](https://developers.google.com/android/work/play/emm-api/user-accounts#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](https://developers.google.com/admin-sdk/directory/v1/guides/manage-users) 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](https://developers.google.com/static/android/work/play/emm-api/images/scenario-1.png) 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](https://developers.google.com/admin-sdk/directory). 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`](https://developers.google.com/admin-sdk/directory/v1/reference/users#resource) 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](https://support.google.com/a/answer/2611859) 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](https://developers.google.com/static/android/work/play/emm-api/images/scenario-2.png) 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`](https://developers.google.com/admin-sdk/directory/v1/reference/users#resource) 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. > [!NOTE] > **Tip:**Synchronize the accounts at the same time as you set up users' Google Accounts. That way, when the organization creates Android enterprise user accounts for their employees, the users' email addresses and network passwords are already synchronized across any accounts that the users need to access. #### 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 [About SSO](https://knowledge.workspace.google.com/admin/apps/setting-up-sso). ## 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](https://developers.google.com/android/work/play/emm-api/prov-devices): - In [managed Google Play Accounts device provisioning](https://developers.google.com/android/work/play/emm-api/prov-devices#managed_google_play_accounts_method), 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.