Create android enterprise account

Create an enterprise

An Enterprise resource binds an organization to your Android Management solution. Devices and Policies both belong to an enterprise. Typically, a single enterprise resource is associated with a single organization. However, you can create multiple enterprises for the same organization based on their needs. For example, an organization may want separate enterprises for its different departments or regions.

The basic steps of how to create an enterprise are described in the Quickstart guide. This page outlines the process in more detail. There are two ways to create an enterprise:

• EMM-managed (recommended)
• Customer-managed (legacy)

EMM-managed enterprises

This is the recommended way to create an enterprise. With this method, EMMs have control over the full lifecycle of an enterprise. Make sure to review the Terms of Service, which includes things like what information to collect, and your obligations to your customers for this feature, to ensure your solution meets all requirements of the API. We’ll highlight some of those details below.

Pre-requisites

1. Collect the enterprise admin’s email address.
2. Allow your customer to provide you with the contact information for their data protection officer and European Union representative. You must also allow the customer to modify the contact information, and if they do, communicate the new contact information to Google (with enterprises.patch ).
3. Show the enterprise admin the Managed Google Play Agreement, and record the identity of the customer and user, and the date and time of the acceptance in your own system.

Create the enterprise

To create an enterprise, call enterprises.create , passing the following values:

• Set agreementAccepted to true , based on completion of step 3 in the pre-requisites.
• Set contactInfo in the Enterprise resource using the contact details you collected from the enterprise admin in steps 1 and 2. Note that the contactEmail is required. This may include:
• In addition to creating a unique enterprise ID, this method allows you to define certain enterprise-specific settings. For instance, you can set the predominant color to display in the device management app UI ( primaryColor ), along with the name or title ( enterpriseDisplayName ) and logo ( logo ) shown to end users.

You are responsible for the lifecycle — creating, updating, and deleting — of the enterprise. You can now update it using enterprises.patch and delete it using enterprises.delete . You must delete the enterprise when your customer terminates their relationship with you.

Update and list your enterprises

In order to change the contactInfo for an enterprise, call enterprises.patch , and set contactInfo in the Enterprise resource. Please note the following:

• If update_mask includes contactInfo and you pass an empty contactInfo value, the call will fail.
• If update_mask is not set and contactInfo is omitted, no change will be made to contactInfo .

To retrieve a list of all your EMM-managed enterprises, call enterprises.list . The response only contains these fields for each enterprise:

• name : The name of the enterprise in the form enterprises/ .
• enterpriseDisplayName : The name of the enterprise displayed to users.

To retrieve the other fields, call enterprises.get with a specific enterprise’s name .

Example

The following examples uses the Java client library to create an enterprise and return its name. See the sample page for more details about using the library.

To create an enterprise:

To delete an enterprise:

Customer-managed enterprises

This is now the «legacy» way to create an enterprise, and if you currently use this method, you can continue to use the existing APIs. We recommend using the Partner-managed Enterprises for new enterprises. Benefits of the Partner-managed method include: it no longer requires the customer to visit the Managed Google Play signup page; and, it doesn’t require the customer to use a Gmail account to administer the enterprise.

1. Retrieve the sign up url

Call signupUrls.create to retrieve the sign up URL. You need to specify two parameters:

• callbackUrl : An https URL the setup wizard redirects to after enterprise sign up is complete. This is typically your management console.
• projectId : Your project ID.

The response contains a url and name . Open the url and take note of the name .

2. Enterprise IT admin completes the sign up flow

The url guides the enterprise admin through the enterprise sign-up process. They need a Gmail account that’s not already associated with an enterprise. After successfully registering their enterprise, the sign-up flow redirects to your callbackUrl . An enterpriseToken is appended to the callbackUrl .

Example

3. Create an enterprise

To create an enterprise, call enterprises.create . In addition to creating a unique enterprise ID, this method allows you to define certain enterprise-specific settings. For instance, you can set the predominant color displayed during device provisioning ( primaryColor ), along with the name or title ( enterpriseDisplayName ) and logo ( logo ) that’s shown to end users.

Example

The following examples uses the Java client library to create an enterprise and return its name. See the sample page for more details about using the library.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Источник

Create an enterprise

To enroll a new customer through your EMM console, you need to create an enterprise. An Enterprises resource represents the binding between an EMM and an organization. You use an instance of it to invoke operations on behalf of the organization.

The Play EMM API provides two ways to create an enterprise instance, depending on the account type the enterprise intends to support:

Managed Google Play Accounts sign-up —An organization wants to use managed Google Play Accounts. You can integrate Google’s Android sign-up UI with your EMM console and provide your customers a quick and easy way to create an enterprise instance that binds them to you as EMM. This approach supports creating multiple enterprises within a given organization and enables managed Google Play Accounts for users and devices. This approach is sometimes referred to as EMM-initiated in the API documentation.

Google domain-based enterprise enrollment —An organization has an existing Google-managed domain. Administrators complete several manual tasks, such as verifying domain ownership with Google, obtaining an EMM token, and creating an enterprise service account. This approach is sometimes referred to as Google-initiated in the API documentation.

You can support either approach in your EMM console using the Enterprises resource. Table 1 shows the relevant fields and operations of this resource for binding organizations to EMMs.

Table 1: Enterprises APIs and the alternative binding processes

Managed Google Play Accounts	Google managed Accounts	Description
Field
id	Unique identifier for the organization, returned from enroll and completeSignup calls.
kind	Identifies the type of resource using a fixed string value, “androidenterprise#enterprise”.
name	Organization (customer) associated with the enterprise object.
primaryDomain	Not set	Because the EMM-initiated Android sign-up process is not tied to the Google domain model, this field is relevant only for the Google enrollment process.
administrator[]	Not set	The administrator who signs up for Android using the EMM-initiated sign-up process becomes the administrator (owner) of the enterprise. Using the managed Google Play console, the administrator can invite other users in the enterprise to participate in administration tasks. See Managed Google Play Help Center.
administrator[].email	Not set
Methods
completeSignup	Given a completionToken and an enterpriseToken , returns an Enterprises resource in the response body.
generateSignupUrl	Given a callbackUrl , returns a URL and a completionToken .
enroll	Enrolls the caller with the EMM whose token is submitted with the request.
getServiceAccount	Returns a service account and credentials.
setAccount	Sets the account that will be used to authenticate to the API as the enterprise.
unenroll	EMMs can sever the binding to either type of enterprise using unenroll. Must be invoked using the EMM’s credentials for the MSA, not the ESA credentials.

Managed Google Play Accounts enterprise enrollment

You can integrate the enrollment process in your EMM console. The user accounts provisioned from this type of enterprise enrollment are referred to as managed Google Play Accounts, and they provide access to apps through Google Play. See Provision user accounts for information about Play EMM APIs available for provisioning managed Google Play Accounts).

Figure 1. Managed Google Play Accounts admin signup workflow

An IT admin initiates the process of creating an enterprise. To do this, the IT admin:

1. Signs in to your EMM console.
2. Clicks or selects Configure Android (for example) and is redirected to a sign-up UI hosted by Google Play.
3. Provides details about the enterprise in the sign-up UI.
4. Is redirected to your EMM console.

The IT admin’s Google Account is now an admin account for a new enterprise.

Best practice: Follow the Google security guidelines to help keep the admin account secure.

Prerequisites

For IT admins

Access to your EMM console and the permissions needed to make the appropriate selection in your console (Try Android for example, as a menu choice).

A Google Account. This account should be a personal account, not an account associated with G Suite or other managed domain accounts.

For your EMM console

To implement the managed Google Play Accounts sign-up flow, your EMM console must be able to:

Use your MSA credentials when invoking calls on the Play EMM APIs. Your MSA is used to invoke many of the operations on behalf of an IT admin until the organization’s enterprise service account (ESA) is set.

Handle redirection via a secure URL to a Google-provided external site to initiate the sign-up flow and complete the enrollment process.

Be configurable with ESA credentials after enrollment. Because your EMM console can be used to create many enterprises within any given customer site, you’ll need a way to associate each enterpriseId with its own service account and credentials. Consider creating service accounts for your customer by calling Enterprises.getServiceAccount and handling key management using Serviceaccountkeys APIs. See Create enterprise service accounts programmatically for more details.

The Android sign-up process requires you to provide a secure (https) service for your console’s use at runtime. The URL to this secure service can be a local URL and can include session or other unique identifying information, as long as it’s well-formed so that the system can parse it. For example:

Enrollment process

The sign-up process is designed to take less than 5 minutes. The steps below assume that the server hosting the callbackUrl is up and running. These steps also assume that your console includes UI component, such as a menu selection with Try Android as an option, that starts the sign-up process when an authenticated IT admin selects the option.

Figure 2. 12-step process to enroll a managed Google Play Accounts enterprise

An IT admin initiates an enrollment request in your EMM console.

Call Enterprises.generateSignupUrl with callbackURL as the only parameter. Example:

The response will contain a sign-up URL (valid for 30 minutes) and a completion token. Extract and save the completion token.

Best practice: Associate the completion token with the Google account the IT admin used to initiate the enrollment request.

Extract the url from the generateSignupURL response.

Redirect to the URL extracted in step 4.

The IT admin follows the setup flow in the sign-up UI to create an enterprise:

The IT admin signs in with a Google Account or creates a new account.

Note: If the Google Account was already used to create a managed Google Play Accounts enterprise but no ESA is set, the sign-up flow will redirect the admin to your EMM console and continue the setup process from step 8.

The IT admin is shown the EMM name, and they confirm that the new enterprise will be enrolled with this EMM.

The IT admin enters a name for the enterprise and agrees to the terms of service.

The sign-up UI generates a callback URL based on the URL specified in step 2.

The sign-up UI redirects the IT admin to the callback URL. Extract and save the enterprise token to the URL. Example:

Call Enterprises.completeSignup , passing the completionToken (step 3) and enterpriseToken (step 8).

The call returns an Enterprises instance in the response body. Store the id , name , and administrator email for future use, because:

• Managed Google Play accounts enterprises are not returned when calling Enterprises.list .
• A single IT admin can manage multiple enterprises. As a result, storing only the administrator email may not be anough to identify an enterprise.

Create an enterprise service account (ESA). ESA credentials take the form of an email address and a private key. There are two ways to create an ESA:

• Best practice:Create the ESA programmatically, using the Play EMM API.
• Display a page that instructs the IT admin to create an ESA in the Google API Console. See Creating a Service Account for more detailed information (instruct the administrator to select project > Editor as their role and check the private key download box). After the IT admin creates an ESA, configure your console with the ESA’s private-key credentials

Using your MSA credentials, call setAccount to set the ESA for this organization.

The enrollment process is complete

• The new managed Google Play Accounts enterprise is enrolled.
• The IT admin’s Google Account is configured as an admin of the enterprise and can access https://play.google.com/work to manage the enterprise’s apps.
• Your EMM console can use the ESA to manage the enterprise’s data through the Google Play EMM API.

Create ESAs programmatically

To simplify key management for ESAs, use the Google Play EMM API to generate service accounts for enterprises instead of the Google API Console. Service accounts generated through the Play EMM API:

• Are not visible on any Cloud Console or API Console project that belongs to you or the enterprise; they must be managed programmatically.
• Are deleted when you unenroll the enterprise.

To generate a service account programmatically:

Call Enterprises.getServiceAccount with the enterpriseId (see step 10 in the Enrollment process) and specify the type of key ( keyType ) you want (googleCredentials, pkcs12). The system returns a service account name and a private key for the service account (in the same formats returned by the Google API Console).

Call Enterprises.setAccount and set the service account for the enterprise.

Best practice: Support having the IT admin change the ESA credentials. To do this in your EMM console, use the existing ESA to call setAccount .

Manage service account keys

The service accounts returned from Enterprises.getServiceAccount are created transparently by Google. As an EMM, you don’t have access to these accounts. However, you can integrate the Serviceaccountkeys API into your console to allow customers to manage their own programmatically generated ESAs and keys.

The Serviceaccountkeys API allows an enterprise to insert, delete, and list the active credentials for their service accounts. These APIs must be invoked while authorized as the ESA that’s been set for the enterprise, and that ESA must have been generated from getServiceAccount . In other words, after an enterprise calls Enterprises.setAccount (using the service account generated by Enterprises.getServiceAccount ), only that enterprise is authorized to invoke calls on the Serviceaccountkeys API to manage the account.

Table 2. Serviceaccountkeys API

Fields
id	An opaque unique string identifier for the ServiceAccountKey assigned by the server.
kind	Identifies the resource using the fixed string androidenterprise#serviceAccountKey .
type	File format of the generated key data. Acceptable values: googleCredentials pkcs12
data	A string comprising the body of the private credentials file. Populated upon creation. Not stored by Google.
Methods
delete	Remove and invalidate specified credentials for the service account (specified with enterpriseId and keyId ).
insert	Generate new credentials for the service account associated with the enterprise.
list	List all active credentials for the service account associated with the enterprise. Returns only the ID and key type.

Notifications

You can obtain notifications from programmatically generated ESAs by calling Enterprises.pullNotificationSet . See Set up EMM notifications for more information.

Google domain-based enterprise enrollment

To support Google domain-based enterprise enrollment, you need to establish a connection between your EMM console, the organization, and Google.

Prerequisites

The organization must have a managed Google domain, EMM enrollment token, and enterprise service account (ESA). Instructions for IT admins on how to obtains these details are available in the Android Enterprise Help Center.

Managed Google domain

If the organization’s IT admin claimed a managed domain when they signed up for G Suite, they can sign enable Android management from the Google Admin console. If the organization doesn’t have a managed Google domain, their IT admin must go through a one-time web registration process with Google.

EMM token

IT admins can obtain an EMM token from the Google Admin console (under Security > Manage EMM provider for Android).

ESA

You or organization’s IT admin can create the ESA, typically through the Google API Console on a project associated with your EMM console. ESAs have a name, an ID, and a key that authenticates the account for actions taken on their behalf. The ID is formatted similarly to an email address, with the name of the service account preceding the @ symbol and the project name following, along with Google services information (for example, some-orgs-esa@myemmconsole313302.iam.gserviceaccount.com).

Enrollment process

1. An IT admin gets an EMM token from the Google Admin console.
2. The IT admin shares the EMM token with you, which authorizes you to manage Android on their domain.
3. Through your EMM console, use the EMM token to call Enterprises.enroll . This binds the organization’s Android solution to their Google domain.
   • The enroll method returns a unique enterpriseId , which you can retrieve later (for Google domain-based enterprises only) using the list method.
   • Optionally, you can store information about the binding ( enterpriseId , primaryDomain ) in a datastore to avoid making API calls to obtain these details. In a Google Accounts scenario, the organization’s primaryDomain is the unique key that identifies the organization to the EMM and to Google.
4. To make organization-specific calls to the Google Play EMM API:
   • Either you create an ESA on behalf of the enterprise, or an admin creates the ESA, then shares it with you.
   • Through your EMM console, call setAccount , using the enterpriseId and the email address of the ESA. This enables the ESA to authenticate to the API as the enterprise.

Example

Here’s an example that enrolls an organization, given a primaryDomainName , serviceAccountEmail , and authenticationToken :

This example uses the client library for Java and the AndroidEnterprise service class from the com.google.api.services.androidenterprise.model package. The procedure shown in the sample can be summarized in these steps:

1. Create a new AndroidEnterprise object with the parameters provided by bind , a model class containing the primary domain name, the service account email address, and the EMM enrollment token.
2. Specify the primary domain name of the newly created enterprise object.
3. Call the enroll method, providing the enterprise object and the enrollment token.
4. Create a new EnterpriseAccount object with the customer’s ESA ID ( serviceAccountEmail ).
5. Set the account by providing both the enterpriseId (returned in step 3) and enterpriseAccount fields.

Optionally, you can store information about the binding ( enterpriseId , primaryDomain ) in a datastore to avoid making API calls to obtain these details. In a Google Accounts scenario, the organization’s primaryDomain is the unique key that identifies the organization to the EMM and to Google.

Set up an on-premises deployment

If an organization requires its data to remain on site, inaccessible to you, you need to make sure your servers never see an active set of credentials for the ESA. To do this, generate and store a set of ESA credentials on site:

1. Complete the enrollment flow:
   1. As shown in step 11, use your MSA to call getServiceAccount . This generates ESA credentials.
   2. As shown in step 12, use setAccount on the ESA to set it as the ESA for this organization.
2. Pass the ESA to the organization’s on-premises server.
3. Take the following steps on the on-premises server :
   1. Call Serviceaccountkeys.insert to create a new key for the ESA. This private key is not stored on Google servers and is only returned once, when the account is created. It is not accessible any other way.
   2. Use the new ESA credentials to call Serviceaccountkeys.list . This returns the active service account credentials.
   3. Call Serviceaccountkeys.delete to delete all credentials except the ESA credentials that were just created on premises.
   4. (Optional) Call Serviceaccountkeys.list to verify that the credentials currently being used on premises are the only valid credentials for the service account.

The on-premises server is now the only server with the ESA credentials. Only an ESA generated through getServiceAccount can access ServiceAccountKeys —your MSA is not allowed to call it.

Best practice: Don’t store your master service account (MSA) credentials on premises. Use a separate ESA for each on-premises deployment.

Unenroll, re-enroll, or delete an enterprise

Unenroll

To unbind an enterprise from your EMM solution, use unenroll . An enterprise isn’t deleted when it’s unenrolled, but its EMM-managed users and all their related user data is deleted after 30 days. Here’s an example implementation:

Best practice: If you have a datastore for enterprise name and enterprise ID mappings, delete the information from your datastore after calling unenroll .

Re-enroll

An IT admin can re-enroll an enterprise using their existing enterpriseId . To do this, they sign in with an owner-level account and follow the enrollment process.

The re-enrollment flow is transparent from your perspective: there’s no way to determine if the enterprise token returned in the redirect URL (step 8) is from a new enterprise or an enterprise that was previously enrolled with another EMM.

If an enterprise was previously enrolled with your EMM solution, you might be able to recognize the enterprise ID. You can restore EMM-managed users and related user data if an IT admin re-enrolls an enterprise no more than 30 days after it was unenrolled from you. If an enterprise was previously enrolled with a different EMM, the user IDs of EMM-managed users created by the other EMM won’t be accessible to you. This is because these user IDs are EMM-specific.

Delete

An IT admin can delete their enterprise from managed Google Play. Within 24 hours the enterprise’s data, accounts, license assignments, and other resources are made inaccessible to the admin, the end users, and you. As a result, your API calls will return an HTTP 404: Not Found status code for the enterpriseId parameter. To handle this error in your EMM console, prompt the IT admin for confirmation before removing any association with the enterprise.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Источник