Autorisierung

Apps autorisieren Aufrufe der Kunden-API für die Zero-Touch-Registrierung mit OAuth. In diesem Dokument wird die Autorisierung der API für EMM-Anbieter (Enterprise Mobility Management) und IT-Entwickler in Unternehmen erläutert. Nachdem Sie dieses Dokument gelesen haben, wissen Sie, wie Sie API-Anfragen in Ihrer App autorisieren und den Nutzern Ihrer App die Kontoanforderungen erläutern.

Kurzanleitung zur Autorisierung

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

Übersicht

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

Kundenkonten

Die Konfigurationen, Geräte und (IT-Administrator) Nutzer 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. Sie übergeben die Kundennummer beim Aufrufen von API-Methoden als Teil des URL-Pfads. Ihre App muss die Kundennummer eines Nutzers abrufen, bevor API-Methoden aufgerufen werden können.

Das folgende Beispiel zeigt, 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 Ergebnisseiten des Kontos aufrufen, da im obigen Beispiel nur die ersten 100 Konten ausgegeben werden. Weitere Informationen dazu finden Sie unter Seitenergebnisse.

Eine Organisation hat normalerweise 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 dabei helfen, neue Kundenkonten zu finden und zu verwenden. Kennzeichnen Sie in Ihrer Anwendung jedes Kundenkonto mit dem Wert companyName.

Nutzer

IT-Administratoren autorisieren die API-Anfragen, die Ihre App in ihrem Namen sendet. Der Nutzer Ihrer Anwendung muss folgende Schritte ausführen, um API-Anfragen zu autorisieren:

1. Google-Konto mit E-Mail-Adresse verknüpfen
2. Sie können einem Kundenkonto mit derselben E-Mail-Adresse beitreten.
3. Akzeptieren Sie die Nutzungsbedingungen für die Zero-Touch-Registrierung.

Wie Sie den Nutzern Ihrer Anwendung bei der Einrichtung helfen, können Sie unsere Anleitungen für IT-Administratoren unter Erste Schritte und Google-Konto verknüpfen in Ihrer eigenen Dokumentation wiederverwenden.

Nutzerverwaltung

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

Annahme der Nutzungsbedingungen

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

Das Portal fordert Nutzer bei der Anmeldung automatisch auf, die neuesten Nutzungsbedingungen zu akzeptieren. Informationen zu den empfohlenen Ansätzen, die Ihre Anwendung beinhalten könnte, finden Sie in den Nutzungsbedingungen für den Umgang mit EMM.

Autorisierung zur App hinzufügen

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

Wichtiger Hinweis: Um die Einrichtung der Autorisierung und Authentifizierung zu vereinfachen, bietet Google Clientbibliotheken, mit denen Sie weniger Code schreiben und Ihren Code robuster machen können. Wir empfehlen, eine Clientbibliothek zum Aufrufen der Customer API 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 Anwendung einzurichten.

Schritt 1: Zero-Touch-Registrierungs-API 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 unter „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 geschehen, 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 einen Anwendungstyp für die Art der Anwendung aus, die Sie erstellen möchten.
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, um die Clientbibliothek zu installieren.

Weitere Informationen zur Autorisierung finden Sie unter Mit OAuth 2.0 auf Google APIs zugreifen.

Autorisierungsbereiche

Verwenden Sie den API-Autorisierungsbereich https://www.googleapis.com/auth/androidworkzerotouchemm in Ihrer Anwendung, um ein OAuth 2.0-Zugriffstoken anzufordern.

Ein Bereichsparameter steuert die Gruppe von Ressourcen und Vorgängen, die über ein Zugriffstoken aufgerufen werden können. Zugriffstoken sind nur für die im Vorgang der Tokenanfrage beschriebenen Vorgänge und Ressourcen gültig. Die API deckt alle Methoden und Ressourcen mit dem oben beschriebenen Bereich für die Zero-Touch-Registrierung ab.

Ein Beispiel für die Zero-Touch-Registrierung, die 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 Mit OAuth 2.0 auf Google APIs zugreifen.

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 Belastungen Ihres Kontos führen könnte. Beachte die folgenden Best Practices, um deine API-Schlüssel zu schützen:

API-Schlüssel nicht direkt in Code einbetten

API-Schlüssel, die in Code eingebettet sind, können versehentlich öffentlich zugänglich gemacht werden – z. B. wenn Sie vergessen, die Schlüssel aus freigegebenem Code zu entfernen. Anstatt Ihre 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 du API-Schlüssel in Dateien speicherst, solltest du die Dateien außerhalb der Quellstruktur der Anwendung aufbewahren, damit deine Schlüssel nicht im Verwaltungssystem des Quellcodes landen. Das ist besonders wichtig, wenn Sie ein öffentliches Quellcode-Verwaltungssystem wie GitHub verwenden.

API-Schlüssel auf die IP-Adressen, Verweis-URLs und mobilen Apps beschränken, die sie benötigen

Wenn Sie die IP-Adressen, Verweis-URLs und mobilen Apps, die jeden Schlüssel verwenden dürfen, einschränken, können Sie die Auswirkungen eines manipulierten API-Schlüssels reduzieren. Sie können die Hosts und Anwendungen angeben, die die einzelnen Schlüssel über die Google API Console verwenden können. Öffnen Sie dazu die Seite „Anmeldedaten“ und erstellen Sie dann 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

Um das Risiko von Angriffen zu minimieren, sollten Sie alle API-Schlüssel löschen, die Sie nicht mehr benötigen.

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 Neu generieren. Aktualisieren Sie dann Ihre Anwendungen so, dass die neu generierten Schlüssel verwendet werden. Die alten Schlüssel funktionieren noch 24 Stunden, nachdem Sie Ersatzschlüssel generiert haben.

Code vor der Veröffentlichung prüfen

Achten Sie darauf, dass Ihr Code keine API-Schlüssel oder andere private Informationen enthält, bevor Sie ihn öffentlich verfügbar machen.