Autorisierung

Apps autorisieren Aufrufe der Kunden-API für die Zero-Touch-Registrierung über OAuth. In diesem Dokument wird die Autorisierung der API für EMM-Anbieter (Enterprise Mobility Management) und IT-Entwickler in Unternehmen erläutert. In diesem Dokument erfahren Sie, wie Sie API-Anfragen in Ihrer Anwendung autorisieren und den Nutzern Ihrer Anwendung die Kontoanforderungen erklären.

Kurzanleitung zur Autorisierung

• Führen Sie diesen Assistenten aus, um ein Google Cloud Platform-Projekt mit der Zero-Touch-Registrierungs-API und OAuth-Clientschlüsseln einzurichten.
• Erstellen Sie den Beispielcode der Kurzanleitung für Java, .NET oder Python. Verwenden Sie die API-Clientbibliotheken von Google zur Unterstützung anderer Sprachen.

Überblick

1. Mindestens ein IT-Administrator ist Nutzer eines Kundenkontos mit Zero-Touch-Registrierung.
2. IT-Administratoren authentifizieren sich mit einem Google-Konto.
3. Bei API-Anfragen wird ein OAuth2-Token übergeben, um API-Anfragen im Namen eines IT-Administrators zu autorisieren.

Kundenkonten

Die Konfigurationen, Geräte und Nutzer (IT-Administrator) einer Organisation gehören zu einem Kundenkonto. Ein Kundenkonto ähnelt einer Gruppe und ist kein einzelner Nutzer. Ein Reseller richtet einen Kunden ein, wenn die Organisation zum ersten Mal Geräte für die Zero-Touch-Registrierung kauft. IT-Administratoren verwalten andere Nutzer in ihrer Organisation über das Portal für die Zero-Touch-Registrierung.

Die API verwendet numerische Kundennummern, um Konten zu identifizieren. Beim Aufrufen von API-Methoden übergeben Sie die Kundennummer als Teil des URL-Pfads. Ihre Anwendung muss die Kundennummer eines Nutzers abrufen, bevor API-Methoden aufgerufen werden.

Im folgenden Beispiel wird gezeigt, wie Sie die Kundenkonten für den Nutzer abrufen, der den API-Aufruf autorisiert:

Java

AndroidProvisioningPartner.Customers.List accountRequest = service.customers().list();
accountRequest.setPageSize(100);
CustomerListCustomersResponse accountResponse = accountRequest.execute();

List<Company> customers = accountResponse.getCustomers();
if (customers == null || customers.isEmpty()) {
    // No accounts found for the user. Confirm the Google Account
    // that authorizes the request can access the zero-touch portal.
    System.out.println("No zero-touch enrollment account found.");
} else {
    // Print the customers in this page.
    for (Company customer : customers) {
        System.out.format("%s\tcustomers/%d\n",
              customer.getCompanyName(), customer.getCompanyId());
    }
}

.NET

CustomersResource.ListRequest accountRequest = service.Customers.List();
accountRequest.PageSize = 100;
CustomerListCustomersResponse accountResponse = accountRequest.Execute();
IList<Company> customers = accountResponse.Customers ?? new List<Company>();
if (customers.Count == 0)
{
    // No accounts found for the user. Confirm the Google Account
    // that authorizes the request can access the zero-touch portal.
    Console.WriteLine("No zero-touch enrollment account found.");
}
foreach (Company customer in customers)
{
    Console.WriteLine("{0}\tcustomers/{1}",
                      customer.CompanyName,
                      customer.CompanyId);
}

Python

response = service.customers().list(pageSize=100).execute()
if 'customers' not in response:
  # No accounts found for the user. Confirm the Google Account
  # that authorizes the request can access the zero-touch portal.
  print('No zero-touch enrollment account found.')
  response['customers'] = []

for customer in response['customers']:
  print('{0}\tcustomers/{1}'.format(
      customer['companyName'], customer['companyId']))

In Ihrer Anwendung müssen Sie die Kontoergebnisseiten aufrufen, da im obigen Beispiel nur die ersten 100 Konten gedruckt werden. Informationen hierzu finden Sie unter Ausgewählte Ergebnisse.

Eine Organisation hat in der Regel ein Kundenkonto, aber größere Organisationen verwenden möglicherweise separate Kundenkonten für jede Abteilung. Da ein IT-Administrator Mitglied verschiedener Kundenkonten sein kann, sollte Ihre Anwendung Nutzern helfen, neue Kundenkonten zu finden und zu verwenden. Kennzeichnen Sie in Ihrer App jedes Kundenkonto mit dem Wert companyName.

Nutzende

IT-Administratoren autorisieren die API-Anfragen, die Ihre App in ihrem Namen sendet. Zur Autorisierung von API-Anfragen müssen die Nutzer Ihrer Anwendung Folgendes tun:

1. Google-Konto mit der entsprechenden E-Mail-Adresse verknüpfen
2. Fügen Sie einem Kundenkonto mit derselben E-Mail-Adresse hinzu.
3. Akzeptieren Sie die Nutzungsbedingungen für Kunden mit Zero-Touch-Registrierung.

Um die Nutzer Ihrer App bei der Einrichtung zu unterstützen, verwenden Sie unsere Hinweise für IT-Administratoren unter Erste Schritte und Google-Konto verknüpfen in Ihrer eigenen Dokumentation.

Nutzerverwaltung

IT-Administratoren verwalten die Nutzer ihrer Kundenkonten im Portal für die Zero-Touch-Registrierung. Nutzer in einem Kundenkonto haben entweder die Rolle Inhaber oder Administrator. Beide Rollen haben denselben Zugriff auf die Kunden-API, aber ein Inhaber kann andere Nutzer verwalten.

Annahme der Nutzungsbedingungen

Bevor Nutzer Ihrer Anwendung API-Aufrufe autorisieren können, müssen sie die aktuellen Nutzungsbedingungen akzeptieren. Dies ist der Fall, wenn IT-Administratoren die Zero-Touch-Registrierung zum ersten Mal verwenden oder wir die Nutzungsbedingungen aktualisieren. Wenn ein Nutzer die aktuellen Nutzungsbedingungen nicht akzeptiert hat, gibt die API einen HTTP-Statuscode 403 Forbidden zurück und der Antworttext enthält einen TosError.

Das Portal fordert Nutzer bei der Anmeldung automatisch auf, die aktuellen Nutzungsbedingungen zu akzeptieren. Vorschläge für Ansätze für deine App findest du im Leitfaden zur Integration von EMM unter Nutzungsbedingungen.

Autorisierung zur App hinzufügen

Jede Anfrage, die Ihre App an die Kunden-API sendet, muss ein Autorisierungstoken enthalten. Anhand dieses Tokens wird deine Anwendung Google gegenüber identifiziert. Da die Kunden-API auf Nutzerdaten zugreift, muss die Autorisierung vom Inhaber der Daten erfolgen. Ihre App delegiert die API-Autorisierung mithilfe des OAuth 2.0-Protokolls an IT-Administratoren.

Wichtiger Hinweis: Google bietet Clientbibliotheken an, mit denen Sie die Menge an Code reduzieren und die Stabilität des Codes erhöhen können, um die Einrichtung der Autorisierung und Authentifizierung zu vereinfachen. Wir empfehlen, zum Aufrufen der API des Kunden eine Clientbibliothek zu verwenden. Weitere Informationen finden Sie in den Kurzanleitungen für Java, .NET und Python.

Anleitung

Wir bieten Kurzanleitungen für Java-, .NET- und Python-Anwendungen. Wenn Sie eine andere Sprache verwenden, führen Sie die beiden folgenden Schritte aus, um die Autorisierung für Ihre App einzurichten.

Schritt 1: API für die Zero-Touch-Registrierung aktivieren

1. Verwenden Sie diesen Assistenten, um ein Projekt in der Google Developers Console zu erstellen oder auszuwählen und die API automatisch zu aktivieren. Klicken Sie auf Weiter und dann auf Zu den Anmeldedaten.
2. Klicken Sie im Abschnitt „Anmeldedaten erstellen“ auf Abbrechen.
3. Klicken Sie oben auf der Seite auf den Tab OAuth-Zustimmungsbildschirm. Wählen Sie eine E-Mail-Adresse aus, geben Sie einen Produktnamen ein, falls noch nicht festgelegt, und klicken Sie auf die Schaltfläche Speichern.
4. Wählen Sie den Tab Anmeldedaten aus, klicken Sie auf die Schaltfläche Anmeldedaten erstellen und wählen Sie OAuth-Client-ID aus.
5. Wählen Sie je nach Art der zu erstellenden Anwendung einen Anwendungstyp aus.
6. Geben Sie unter Name den Namen Ihrer App ein.
7. Klicken Sie auf Erstellen.
8. Klicken Sie auf JSON herunterladen.
9. Verschieben Sie die Datei in Ihr Arbeitsverzeichnis und benennen Sie sie in client_secret.json um.

Schritt 2: Clientbibliothek installieren

So installieren Sie die Clientbibliothek für Ihre Sprache:

1. Rufen Sie die Google API-Clientbibliotheken auf und wählen Sie Ihre Sprache aus der Liste der unterstützten Sprachen aus.
2. Folgen Sie der Anleitung zum Installieren der Clientbibliothek.

Weitere Informationen zur Autorisierung finden Sie unter OAuth 2.0 für den Zugriff auf Google APIs verwenden.

Autorisierungsbereiche

Fordern Sie mit dem API-Autorisierungsbereich https://www.googleapis.com/auth/androidworkzerotouchemm in Ihrer Anwendung ein OAuth 2.0-Zugriffstoken an.

Ein Bereichsparameter steuert die Ressourcen und Vorgänge, für die ein Zugriffstoken Aufrufe zulässt. Zugriffstokens sind nur für die Vorgänge und Ressourcen gültig, die im Bereich der Tokenanfrage beschrieben werden. Die API deckt alle Methoden und Ressourcen mit dem oben gezeigten einzelnen Bereich für die Zero-Touch-Registrierung ab.

Ein Beispiel für den Bereich der Zero-Touch-Registrierung, der mit der Google API-Clientbibliothek verwendet wird, finden Sie in den Kurzanleitungen für Java, .NET und Python. Weitere Informationen zur Verwendung von Google API-Bereichen finden Sie unter OAuth 2.0 für den Zugriff auf Google APIs verwenden.

Best Practices für API-Schlüssel

Wenn Sie API-Schlüssel in Ihren Anwendungen verwenden, achten Sie auf deren Sicherheit. Wenn Sie Ihre Anmeldedaten öffentlich preisgeben, gefährden Sie damit möglicherweise Ihr Konto, was zu unerwarteten Kosten auf Ihrem Konto führen kann. Beachten Sie die folgenden Best Practices, um die Sicherheit Ihrer API-Schlüssel zu wahren:

Betten Sie API-Schlüssel nicht direkt in den Code ein.

In Code eingebettete API-Schlüssel können versehentlich der Öffentlichkeit zugänglich gemacht werden, z. B. wenn Sie vergessen, die Schlüssel aus dem freigegebenen Code zu entfernen. Anstatt die API-Schlüssel in Ihre Anwendungen einzubetten, sollten Sie sie in Umgebungsvariablen oder Dateien außerhalb der Quellstruktur der Anwendung speichern.

Speichern Sie API-Schlüssel nicht in Dateien in der Quellstruktur der Anwendung

Wenn Sie API-Schlüssel in Dateien speichern, sollten Sie die Dateien außerhalb der Quellstruktur der Anwendung aufbewahren, damit die Schlüssel nicht in Ihrem Quellcode-Steuerungssystem landen. Das ist besonders wichtig, wenn Sie ein öffentliches Verwaltungssystem für Quellcode wie GitHub verwenden.

Schränken Sie Ihre API-Schlüssel so ein, dass sie nur von den IP-Adressen, Verweis-URLs und mobilen Apps verwendet werden, die sie benötigen

Wenn Sie die IP-Adressen, Verweis-URLs und mobilen Apps, die die einzelnen Schlüssel verwenden können, einschränken, können Sie die Auswirkungen eines manipulierten API-Schlüssels reduzieren. Du kannst die Hosts und Anwendungen, die die einzelnen Schlüssel verwenden dürfen, über die Google API Console angeben. Öffne dazu die Seite „Anmeldedaten“ und erstellen Sie einen neuen API-Schlüssel mit den gewünschten Einstellungen oder bearbeiten Sie die Einstellungen eines API-Schlüssels.

Nicht benötigte API-Schlüssel löschen

Löschen Sie nicht mehr benötigte API-Schlüssel, um das Risiko von Angriffen zu minimieren.

API-Schlüssel regelmäßig neu generieren

Sie können API-Schlüssel über die Google API Console neu generieren. Öffnen Sie dazu die Seite „Anmeldedaten“, wählen Sie einen API-Schlüssel aus und klicken Sie für jeden Schlüssel auf Schlüssel neu generieren. Aktualisieren Sie dann Ihre Anwendungen so, dass sie die neu generierten Schlüssel verwenden. Ihre alten Schlüssel funktionieren noch 24 Stunden, nachdem Sie Ersatzschlüssel generiert haben.

Code vor der Veröffentlichung prüfen

Der Code darf keine API-Schlüssel oder andere private Informationen enthalten, bevor Sie ihn öffentlich verfügbar machen.