Integrationsleitfaden für EMM

Dieser Leitfaden hilft Anbietern von Enterprise Mobility Management (EMM), die Zero-Touch-Registrierung in ihre Konsole zu integrieren. Lesen Sie weiter, um mehr über die Registrierung zu erfahren und Best Practices für die Bereitstellung von Geräten mit Ihrem DPC (Device Policy Controller) anzusehen. Wenn Sie einen DPC haben, lernen Sie Best Practices für die Bereitstellung von Geräten kennen und erhalten Tipps zur Unterstützung bei Entwicklung und Tests.

Funktionen für IT-Administratoren

Mit der Customer API können IT-Administratoren die Zero-Touch-Registrierung direkt über Ihre Konsole einrichten. Hier sind einige Aufgaben, die ein IT-Administrator in Ihrer Konsole ausführen könnte:

• Sie können Konfigurationen für die Zero-Touch-Registrierung basierend auf Ihren Richtlinien für Mobilgeräte erstellen, bearbeiten und löschen.
• Legen Sie eine Standardkonfiguration fest, damit Ihr DPC zukünftige Geräte bereitstellt, die die Organisation kauft.
• Sie können einzelne Konfigurationen auf Geräte anwenden oder Geräte aus der Zero-Touch-Registrierung entfernen.

Weitere Informationen zur Zero-Touch-Registrierung finden Sie in der Übersicht.

Voraussetzungen

Bevor Sie der EMM-Konsole die Zero-Touch-Registrierung hinzufügen, prüfen Sie, ob Ihre Lösung Folgendes unterstützt:

• Ihre EMM-Lösung muss ein unternehmenseigenes Gerät mit Android 8.0 oder höher (Pixel 7.1 oder höher) im vollständig verwalteten Modus bereitstellen. Unternehmenseigene Geräte mit Android 10 oder höher können als vollständig verwaltet oder mit einem Arbeitsprofil bereitgestellt werden.
• Da bei der Zero-Touch-Registrierung automatisch ein DPC heruntergeladen und installiert wird, muss dieser bei Google Play verfügbar sein. Wir führen eine Liste kompatibler DPCs, die IT-Administratoren über die Kunden-API oder das Portal konfigurieren können. Senden Sie eine Produktänderungsanfrage über die EMM-Anbieter-Community, um Ihren DPC der Liste hinzuzufügen.
• Ihre Kunden benötigen ein Konto für die Zero-Touch-Registrierung, um die Customer API aufzurufen. Ein Partner-Reseller richtet das Konto für die Organisation eines IT-Administrators ein, wenn die Organisation ihre Geräte kauft.
• Das Gerät muss mit Google Mobile-Diensten (GMD) kompatibel sein und die Google Play-Dienste müssen jederzeit aktiviert sein, damit die Zero-Touch-Registrierung ordnungsgemäß funktioniert.

API aufrufen

Die Nutzer Ihrer Console autorisieren die Nutzer Ihrer Console (mit ihrem Google-Konto) Ihre API-Anfragen an die Kunden-API. Dieser Ablauf unterscheidet sich von der Autorisierung, die Sie für andere EMM APIs ausführen. Unter Autorisierung erfahren Sie, wie Sie dies in Ihrer App tun.

Nutzungsbedingungen

Ihre Nutzer müssen den aktuellen Nutzungsbedingungen zustimmen, bevor sie die API aufrufen. Wenn der API-Aufruf den HTTP-Statuscode 403 Forbidden zurückgibt und der Antworttext TosError enthält, fordern Sie den Nutzer auf, die Nutzungsbedingungen zu akzeptieren. Dazu muss er sich im Portal für die Zero-Touch-Registrierung anmelden. Das folgende Beispiel zeigt eine der Möglichkeiten:

// Authorize this method call as a user that hasn't yet accepted the ToS.
final String googleApiFormatHttpHeader = "X-GOOG-API-FORMAT-VERSION";
final String googleApiFormatVersion = "2";
final String tosErrorType =
      "type.googleapis.com/google.android.device.provisioning.v1.TosError";

try {
  // Send an API request to list all the DPCs available including the HTTP header
  // X-GOOG-API-FORMAT-VERSION with the value 2. Import the  exception:
  // from googleapiclient.errors import HttpError
  AndroidProvisioningPartner.Customers.Dpcs.List request =
        service.customers().dpcs().list(customerAccount);
  request.getRequestHeaders().put(googleApiFormatHttpHeader, googleApiFormatVersion);
  CustomerListDpcsResponse response = request.execute();
  return response.getDpcs();

} catch (GoogleJsonResponseException e) {
  // Get the error details. In your app, check details exists first.
  ArrayList<Map> details = (ArrayList<Map>) e.getDetails().get("details");
  for (Map detail : details) {
    if (detail.get("@type").equals(tosErrorType)
          && (boolean) detail.get("latestTosAccepted") != true) {
      // Ask the user to accept the ToS. If they agree, open the portal in a browser.
      // ...
    }
  }
  return null;
}

// Authorize this method call as a user that hasn't yet accepted the ToS.
try
{
    var request = service.Customers.Dpcs.List(customerAccount);
    CustomerListDpcsResponse response = request.Execute();
    return response.Dpcs;
}
catch (GoogleApiException e)
{
    foreach (SingleError error in e.Error?.Errors)
    {
        if (error.Message.StartsWith("The user must agree the terms of service"))
        {
            // Ask the user to accept the ToS. If they agree, open the portal in a browser.
            // ...
        }
    }
}

# Authorize this method call as a user that hasn't yet accepted the ToS.
tos_error_type = ('type.googleapis.com/'
                  'google.android.device.provisioning.v1.TosError')
portal_url = 'https://partner.android.com/zerotouch'

# Send an API request to list all the DPCs available including the HTTP
# header X-GOOG-API-FORMAT-VERSION with the value 2. Import the exception:
# from googleapiclient.errors import HttpError
try:
  request = service.customers().dpcs().list(parent=customer_account)
  request.headers['X-GOOG-API-FORMAT-VERSION'] = '2'
  response = request.execute()
  return response['dpcs']

except HttpError as err:
  # Parse the JSON content of the error. In your app, check ToS exists first.
  error = json.loads(err.content)
  tos_error = error['error']['details'][0]

  # Ask the user to accept the ToS (not shown here). If they agree, then open
  # the portal in a browser.
  if (tos_error['@type'] == tos_error_type
      and tos_error['latestTosAccepted'] is not True):
    if raw_input('Accept the ToS in the zero-touch portal? y|n ') == 'y':
      webbrowser.open(portal_url)

Wenn Ihr Google API-Client detaillierte Fehler (Java-, Python- oder HTTP-Anfragen) unterstützt, fügen Sie den HTTP-Header X-GOOG-API-FORMAT-VERSION mit dem Wert 2 in Ihre Anfragen ein. Wenn Ihr Client keine detaillierten Fehler (.NET und andere) unterstützt, passen Sie die Fehlermeldung an.

Wenn wir die Nutzungsbedingungen in Zukunft aktualisieren und du diesem Ansatz folgst, wird der Nutzer in deiner App aufgefordert, die neuen Nutzungsbedingungen noch einmal zu akzeptieren.

Link zum Portal

IT-Administratoren verwenden das Portal für die Zero-Touch-Registrierung, um die Nutzer ihrer Organisation zu verwalten. Dies ist nicht über die Kunden-API möglich. IT-Administratoren können auch Geräte und Konfigurationen über das Portal verwalten. Wenn Sie von Ihrer Konsole oder in Ihrer Dokumentation auf das Portal verlinken müssen, verwenden Sie diese URL:

https://partner.android.com/zerotouch

Informieren Sie IT-Administratoren darüber, dass sie aufgefordert werden, sich mit ihrem Google-Konto anzumelden.

Geräteregistrierung

Die Zero-Touch-Registrierung ist ein Mechanismus zur Registrierung von Geräten und ist ähnlich wie die NFC-Registrierung oder die QR-Code-Registrierung. Ihre Konsole muss verwaltete Geräte unterstützen und Ihr DPC muss im vollständig verwalteten Gerätemodus ausgeführt werden können.

Die Zero-Touch-Registrierung ist auf unterstützten Geräten mit Android 8.0 oder höher verfügbar. IT-Administratoren müssen unterstützte Geräte von einem Partner-Reseller erwerben. In der Console kann durch Aufrufen von customers.devices.list erfasst werden, welche Geräte des IT-Administrators für die Zero-Touch-Registrierung verfügbar sind.

So funktioniert die Registrierung:

1. Ein Gerät meldet sich beim ersten Start (oder nach dem Zurücksetzen auf die Werkseinstellungen) für die Zero-Touch-Registrierung bei einem Google-Server an.
2. Wenn der IT-Administrator eine Konfiguration auf das Gerät angewendet hat, führt die Zero-Touch-Registrierung den Android-Einrichtungsassistenten für vollständig verwaltete Geräte aus und personalisiert die Bildschirme mit Metadaten aus der Konfiguration.
3. Bei der Zero-Touch-Registrierung wird Ihr DPC bei Google Play heruntergeladen und installiert.
4. Der DPC empfängt den ACTION_PROVISION_MANAGED_DEVICE-Intent und stellt das Gerät bereit.

Wenn keine Internetverbindung vorhanden ist, wird die Prüfung durchgeführt, sobald eine verfügbar ist. Weitere Informationen zur Gerätebereitstellung mit Zero-Touch-Registrierung finden Sie unter Bereitstellung unten.

Standardkonfigurationen

Die Zero-Touch-Registrierung ist für IT-Administratoren besonders hilfreich, wenn sie eine Standardkonfiguration festlegen, die auf alle neuen Geräte der Organisation angewendet wird. Wenn keine Standardkonfiguration festgelegt ist, stufen Sie sie von Ihrer Konsole aus hoch. Sie können den Wert von customers.configurations.isDefault prüfen, um herauszufinden, ob eine Organisation eine Standardkonfiguration festgelegt hat.

Das folgende Beispiel zeigt, wie Sie eine vorhandene Konfiguration als Standard festlegen können:

// Send minimal data with the request. Just the 2 required fields.
// targetConfiguration is an existing configuration that we want to make the default.
Configuration configuration = new Configuration();
configuration.setIsDefault(true);
configuration.setConfigurationId(targetConfiguration.getConfigurationId());

// Call the API, including the FieldMask to avoid setting other fields to null.
AndroidProvisioningPartner.Customers.Configurations.Patch request = service
      .customers()
      .configurations()
      .patch(targetConfiguration.getName(), configuration);
request.setUpdateMask("isDefault");
Configuration results = request.execute();

// Send minimal data with the request. Just the 2 required fields.
// targetConfiguration is an existing configuration that we want to make the default.
Configuration configuration = new Configuration
{
    IsDefault = true,
    ConfigurationId = targetConfiguration.ConfigurationId,
};

// Call the API, including the FieldMask to avoid setting other fields to null.
var request = service.Customers.Configurations.Patch(configuration,
                                                     targetConfiguration.Name);
request.UpdateMask = "IsDefault";
Configuration results = request.Execute();

# Send minimal data with the request. Just the 2 required fields.
# target_configuration is an existing configuration we'll make the default.
configuration = {
    'isDefault': True,
    'configurationId': target_configuration['configurationId']}

# Call the API, including the FieldMask to avoid setting other fields to null.
response = service.customers().configurations().patch(
    name=target_configuration['name'],
    body=configuration, updateMask='isDefault').execute()

Verweis auf Ihren DPC

Wir empfehlen, den API-Ressourcennamen customers.dpcs.name zu verwenden, um Ihren DPC zu identifizieren und in Konfigurationen zu verwenden. Der Ressourcenname enthält eine eindeutige, unveränderliche Kennzeichnung für den DPC. Rufen Sie customers.dpcs.list auf, um die Liste aller unterstützten DPCs abzurufen. Da der Ressourcenname auch die Kundennummer enthält, filtern Sie die Liste nach der letzten Pfadkomponente, um eine übereinstimmende Dpc-Instanz zu finden. Das folgende Beispiel zeigt, wie Sie Ihren DPC abgleichen und für die spätere Verwendung in einer Konfiguration beibehalten können:

// Return a customer Dpc instance for the specified DPC ID.
String myDpcIdentifier = "AH6Gbe4aiS459wlz58L30cqbbXbUa_JR9...xMSWCiYiuHRWeBbu86Yjq";
final int dpcIdIndex = 3;
final String dpcComponentSeparator = "/";
// ...
for (Dpc dpcApp : dpcs) {
    // Because the DPC name is in the format customers/{CUST_ID}/dpcs/{DPC_ID}, check the
    // fourth component matches the DPC ID.
    String dpcId = dpcApp.getName().split(dpcComponentSeparator)[dpcIdIndex];
    if (dpcId.equals(myDpcIdentifier)) {
        System.out.format("My DPC is: %s\n", dpcApp.getDpcName());
        return dpcApp;
    }
}
// Handle the case when the DPC isn't found...

// Return a customer Dpc instance for the specified DPC ID.
var myDpcIdentifer = "AH6Gbe4aiS459wlz58L30cqbbXbUa_JR9...fE9WdHcxMSWCiYiuHRWeBbu86Yjq";
const int dpcIdIndex = 3;
const String dpcComponentSeparator = "/";
// ...
foreach (Dpc dpcApp in dpcs)
{
    // Because the DPC name is in the format customers/{CUST_ID}/dpcs/{DPC_ID}, check the
    // fourth component matches the DPC ID.
    String dpcId = dpcApp.Name.Split(dpcComponentSeparator)[dpcIdIndex];
    if (dpcId.Equals(myDpcIdentifer))
    {
        Console.WriteLine("Matched DPC is: {0}", dpcApp.DpcName);
        return dpcApp;
    }
}
// Handle the case when the DPC isn't found...

# Return a customer Dpc instance for the specified DPC ID.
my_dpc_id = 'AH6Gbe4aiS459wlz58L30cqb...fE9WdHcxMSWCiYiuHRWeBbu86Yjq'
# ...
for dpc_app in dpcs:
  # Because the DPC name is in the format customers/{CUST_ID}/dpcs/{DPC_ID},
  # check the fourth component matches the DPC ID.
  dpc_id = dpc_app['name'].split('/')[3]
  if dpc_id == my_dpc_id:
    return dpc_app

# Handle the case when the DPC isn't found...

Wenn Sie den Namen eines DPC in der Benutzeroberfläche Ihrer Konsole anzeigen möchten, zeigen Sie den von customers.dpcs.dpcName zurückgegebenen Wert an.

Wird bereitgestellt

Nutzen Sie diese Gelegenheit, um Nutzern bei der Gerätebereitstellung eine positive Erfahrung zu bieten. Für die Bereitstellung des Geräts sollten nur ein Nutzername und ein Passwort erforderlich sein. Denken Sie daran, dass Reseller Geräte möglicherweise direkt an Remote-Nutzer versenden. Nehmen Sie alle anderen Einstellungen in customers.configuration.dpcExtras auf, z. B. den EMM-Server oder die Organisationseinheit.

Das folgende JSON-Snippet zeigt einen Teil einer Beispielkonfiguration:

{
  "android.app.extra.PROVISIONING_LOCALE": "en_GB",
  "android.app.extra.PROVISIONING_TIME_ZONE": "Europe/London",
  "android.app.extra.PROVISIONING_LEAVE_ALL_SYSTEM_APPS_ENABLED": true,
  "android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE": {
    "workflow_type": 3,
    "default_password_quality": 327680,
    "default_min_password_length": 6,
    "company_name": "XYZ Corp",
    "organizational_unit": "sales-uk",
    "management_server": "emm.example.com",
    "detail_tos_url": "https://www.example.com/policies/terms/",
    "allowed_user_domains": "[\"example.com\", \"example.org\", \"example.net\"]"
    }
}

Bei der Zero-Touch-Registrierung wird Ihr DPC mit einem Android-Intent installiert und gestartet. Das System sendet die Werte im JSON-Attribut android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE als Extras im Intent an Ihren DPC. Der DPC kann die Bereitstellungseinstellungen aus dem PersistableBundle mit denselben Schlüsseln lesen.

Empfohlen – verwenden Sie die folgenden Intent-Extras, um Ihren DPC einzurichten:

• EXTRA_PROVISIONING_ADMIN_EXTRAS_BUNDLE
• EXTRA_PROVISIONING_LOCALE
• EXTRA_PROVISIONING_TIME_ZONE
• EXTRA_PROVISIONING_LOCAL_TIME
• EXTRA_PROVISIONING_LEAVE_ALL_SYSTEM_APPS_ENABLED
• EXTRA_PROVISIONING_MAIN_COLOR
• EXTRA_PROVISIONING_DISCLAIMERS

Nicht empfohlen: Lassen Sie die folgenden Extras weg, die Sie in anderen Registrierungsmethoden verwenden könnten:

• EXTRA_PROVISIONING_DEVICE_ADMIN_COMPONENT_NAME
• EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_CHECKSUM
• EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_DOWNLOAD_COOKIE_HEADER
• EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_DOWNLOAD_LOCATION
• EXTRA_PROVISIONING_DEVICE_ADMIN_SIGNATURE_CHECKSUM

Informationen zum Extrahieren und Verwenden dieser Einstellungen in Ihrem DPC finden Sie unter Kundengeräte bereitstellen.

Entwicklung und Tests

Zum Entwickeln und Testen der Funktionen Ihrer Konsole für die Zero-Touch-Registrierung benötigen Sie Folgendes:

• ein unterstütztes Gerät
• ein Kundenkonto mit Zero-Touch-Registrierung

Für Entwicklung und Tests Geräte wie das Google Pixel, die die Zero-Touch-Registrierung unterstützen. Sie müssen Ihre Entwicklungsgeräte nicht bei einem Reseller-Partner erwerben.

Kontaktieren Sie uns, um ein Testkundenkonto zu erhalten und auf das Portal für die Zero-Touch-Registrierung zuzugreifen. Senden Sie uns eine E-Mail über Ihre geschäftliche E-Mail-Adresse, die mit einem Google-Konto verknüpft ist. Teile uns den Hersteller und die IMEI-Nummer für ein oder zwei Geräte mit. Wir fügen sie deinem Entwicklungskonto hinzu.

Da bei der Zero-Touch-Registrierung ein DPC automatisch heruntergeladen und installiert wird, muss dieser bei Google Play verfügbar sein, damit Sie die Bereitstellung testen können. Tests mit einer Entwicklerversion Ihres DPC sind nicht möglich.

Support für IT-Administratoren

Wenn Sie IT-Administratoren bei der Benutzeroberfläche Ihrer Konsole oder Ihrer Dokumentation helfen müssen, finden Sie weitere Informationen unter Zero-Touch-Registrierung für IT-Administratoren. Sie können die Nutzer Ihrer Console auch auf diesen Hilfeartikel verweisen.

Weitere Informationen

In diesen Dokumenten erfahren Sie, wie Sie die Zero-Touch-Registrierung in Ihre Konsole integrieren:

• Zero-Touch-Registrierung für IT-Administratoren in der Android Enterprise-Hilfe
• Stellen Sie Kundengeräte über die Website für Android EMM-Entwickler bereit.