OAuth 2.0 für mobile und Desktop-Apps

In diesem Dokument wird erläutert, wie Anwendungen, die auf Geräten wie Smartphones, Tablets und Computern installiert sind, die OAuth 2.0-Endpunkte von Google verwenden, um den Zugriff auf Google APIs zu autorisieren.

Mit OAuth 2.0 können Nutzer bestimmte Daten für eine Anwendung freigeben, während ihre Nutzernamen, Passwörter und andere Informationen privat bleiben. Eine Anwendung kann beispielsweise OAuth 2.0 verwenden, um von Nutzern die Berechtigung zum Speichern von Dateien in ihrem Google Drive zu erhalten.

Installierte Apps werden auf einzelne Geräte verteilt und es wird davon ausgegangen, dass diese Apps keine Geheimnisse wahren können. Sie können auf Google APIs zugreifen, während der Nutzer in der App ist oder die App im Hintergrund ausgeführt wird.

Dieser Autorisierungsablauf ähnelt dem, der für Webserveranwendungen verwendet wird. Der Hauptunterschied besteht darin, dass installierte Apps den Systembrowser öffnen und einen lokalen Weiterleitungs-URI angeben müssen, um Antworten vom Autorisierungsserver von Google zu verarbeiten.

Alternativen

Für mobile Apps können Sie Google Sign-in für Android oder iOS verwenden. Die Clientbibliotheken für die Google-Anmeldung übernehmen die Authentifizierung und Nutzerautorisierung. Sie sind m��glicherweise einfacher zu implementieren als das hier beschriebene Protokoll auf niedrigerer Ebene.

Informationen zu Apps, die auf Geräten ausgeführt werden, die keinen Systembrowser unterstützen oder nur eingeschränkte Eingabemöglichkeiten haben, z. B. Fernseher, Spielekonsolen, Kameras oder Drucker, finden Sie unter OAuth 2.0 für Fernseher und Geräte oder Anmeldung auf Fernsehern und Geräten mit begrenzter Eingabe.

Bibliotheken und Beispiele

Wir empfehlen die folgenden Bibliotheken und Beispiele, um den in diesem Dokument beschriebenen OAuth 2.0-Ablauf zu implementieren:

• AppAuth for Android-Bibliothek
• AppAuth for iOS-Bibliothek
• OAuth für Apps: Windows-Beispiele

Vorbereitung

Die APIs für Ihr Projekt aktivieren

Jede Anwendung, die Google APIs aufruft, muss diese APIs in der API Consoleaktivieren.

So aktivieren Sie eine API für Ihr Projekt:

1. Open the API Library in der Google API Console.
2. If prompted, select a project, or create a new one.
3. In der API Library finden Sie alle verfügbaren APIs nach Produktfamilie und Beliebtheit gruppiert. Wenn die API, die Sie aktivieren möchten, nicht in der Liste angezeigt wird, können Sie die Suchfunktion verwenden oder in der zugehörigen Produktfamilie auf Alle ansehen klicken.
4. Wählen Sie die gewünschte API aus und klicken Sie dann auf die Schaltfläche Aktivieren.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Anmeldedaten für die Autorisierung erstellen

Alle Anwendungen, die OAuth 2.0 für den Zugriff auf Google APIs verwenden, müssen Autorisierungsdaten haben, die die Anwendung beim OAuth 2.0-Server von Google identifizieren. In den folgenden Schritten wird erläutert, wie Sie Anmeldedaten für Ihr Projekt erstellen. Ihre Anwendungen können dann mit den Anmeldedaten auf APIs zugreifen, die Sie für dieses Projekt aktiviert haben.

1. Go to the Credentials page.
2. Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
3. In den folgenden Abschnitten werden die Clienttypen beschrieben, die vom Autorisierungsserver von Google unterstützt werden. Wählen Sie den für Ihre Anwendung empfohlenen Clienttyp aus, geben Sie einen Namen für Ihren OAuth-Client ein und legen Sie die anderen Felder im Formular entsprechend fest.

Zugriffsbereiche identifizieren

Mithilfe von Bereichen wird ermöglicht, dass eine Anwendung nur für benötigte Ressourcen den Zugriff anfordern kann, während Nutzer wiederum steuern können, wie viel Zugriff sie der Anwendung gewähren. Daher besteht möglicherweise ein umgekehrter Zusammenhang zwischen der Anzahl der angeforderten Bereiche und der Wahrscheinlichkeit, die Nutzereinwilligung einzuholen.

Bevor Sie mit der Implementierung der OAuth 2.0-Autorisierung beginnen, sollten Sie also die Bereiche ermitteln, für die Ihre Anwendung eine Zugriffsberechtigung benötigt.

Das Dokument OAuth 2.0 API Scopes enthält eine vollständige Liste der Bereiche, die Sie für den Zugriff auf Google APIs verwenden können.

OAuth 2.0-Zugriffstokens abrufen

In den folgenden Schritten wird gezeigt, wie Ihre Anwendung mit dem OAuth 2.0-Server von Google interagiert, um die Einwilligung eines Nutzers einzuholen, eine API-Anfrage im Namen des Nutzers auszuführen. Ihre Anwendung benötigt diese Einwilligung, bevor sie eine Google API-Anfrage ausführen kann, für die eine Nutzerautorisierung erforderlich ist.

Schritt 1: Code Verifier und Challenge generieren

Google unterstützt das Proof Key for Code Exchange (PKCE)-Protokoll, um den Ablauf der installierten App sicherer zu machen. Für jede Autorisierungsanfrage wird ein eindeutiger Code Verifier erstellt. Der umgewandelte Wert, „code_challenge“, wird an den Autorisierungsserver gesendet, um den Autorisierungscode abzurufen.

Code Verifier erstellen

Ein code_verifier ist eine kryptografische Zufallszeichenfolge mit hoher Entropie, die die nicht reservierten Zeichen [A-Z] / [a-z] / [0-9] / „-“ / „.“ / „_“ / „~“ mit einer Mindestlänge von 43 Zeichen und einer maximalen Länge von 128 Zeichen verwendet.

Der Code Verifier sollte eine ausreichende Entropie haben, damit es nicht möglich ist, den Wert zu erraten.

Code Challenge erstellen

Es werden zwei Methoden zum Erstellen der Code-Herausforderung unterstützt.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

Schritt 2: Anfrage an den OAuth 2.0-Server von Google senden

Wenn du die Nutzerautorisierung erhalten möchtest, sende eine Anfrage an den Autorisierungsserver von Google unter https://accounts.google.com/o/oauth2/v2/auth. Dieser Endpunkt verarbeitet die Suche nach aktiven Sitzungen, authentifiziert den Nutzer und holt die Nutzereinwilligung ein. Der Endpunkt ist nur über SSL zugänglich und HTTP-Verbindungen (ohne SSL) werden abgelehnt.

Der Autorisierungsserver unterstützt die folgenden Suchstringparameter für installierte Anwendungen:

Beispiel-Autorisierungs-URLs

Auf den folgenden Tabs finden Sie Beispielautorisierungs-URLs für die verschiedenen Weiterleitungs-URI-Optionen.

Die URLs sind bis auf den Wert des Parameters redirect_uri identisch. Die URLs enthalten außerdem die erforderlichen Parameter response_type und client_id sowie den optionalen Parameter state. Jede URL enthält Zeilenumbrüche und Leerzeichen für eine bessere Lesbarkeit.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Schritt 3: Google fordert den Nutzer zur Einwilligung auf

In diesem Schritt entscheidet der Nutzer, ob er Ihrer Anwendung den angeforderten Zugriff gewährt. In dieser Phase zeigt Google ein Zustimmungsfenster an, in dem der Name Ihrer Anwendung und die Google API-Dienste angezeigt werden, für die mit den Autorisierungsanmeldedaten des Nutzers eine Berechtigung angefordert wird. Außerdem wird eine Zusammenfassung der zu gewährenden Zugriffsbereiche angezeigt. Der Nutzer kann dann zustimmen, Zugriff auf einen oder mehrere von Ihrer Anwendung angeforderte Bereiche zu gewähren, oder die Anfrage ablehnen.

Ihre Anwendung muss in dieser Phase nichts tun, da sie auf die Antwort vom OAuth 2.0-Server von Google wartet, die angibt, ob Zugriff gewährt wurde. Diese Antwort wird im nächsten Schritt erläutert.

Schritt 4: OAuth 2.0-Serverantwort verarbeiten

Wie Ihre Anwendung die Autorisierungsantwort empfängt, hängt vom verwendeten Weiterleitungs-URI-Schema ab. Unabhängig vom Schema enthält die Antwort entweder einen Autorisierungscode (code) oder einen Fehler (error). error=access_denied gibt beispielsweise an, dass der Nutzer die Anfrage abgelehnt hat.

Wenn der Nutzer Zugriff auf Ihre Anwendung gewährt, können Sie den Autorisierungscode wie im nächsten Schritt beschrieben gegen ein Zugriffstoken und ein Aktualisierungstoken eintauschen.

Schritt 5: Autorisierungscode gegen Aktualisierungs- und Zugriffstoken austauschen

Wenn du einen Autorisierungscode gegen ein Zugriffstoken eintauschen möchtest, rufe den Endpunkt https://oauth2.googleapis.com/token auf und lege die folgenden Parameter fest:

Das folgende Snippet zeigt eine Beispielanfrage:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Google antwortet auf diese Anfrage mit einem JSON-Objekt, das ein kurzlebiges Zugriffstoken und ein Aktualisierungstoken enthält.

Die Antwort umfasst die folgenden Felder:

Das folgende Snippet zeigt eine Beispielantwort:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Schritt 6: Prüfen, welche Berechtigungen Nutzer gewährt haben

Wenn Sie mehrere Bereiche gleichzeitig anfordern, gewähren Nutzer möglicherweise nicht alle Bereiche, die Ihre App anfordert. Ihre App sollte immer prüfen, welche Bereiche vom Nutzer gewährt wurden, und bei einer Ablehnung von Bereichen die entsprechenden Funktionen deaktivieren. Weitere Informationen finden Sie unter Detaillierte Berechtigungen verwalten.

Ob der Nutzer Ihrer Anwendung Zugriff auf einen bestimmten Bereich gewährt hat, sehen Sie im Feld scope in der Antwort des Zugriffstokens. Die Zugriffsbereiche, die durch das access_token gewährt werden, als Liste von durch Leerzeichen getrennten Strings, die zwischen Groß- und Kleinschreibung unterscheiden.

In der folgenden Beispielantwort für ein Zugriffstoken ist beispielsweise zu sehen, dass der Nutzer Ihrer Anwendung Lesezugriff auf Drive-Aktivitäten und Kalendertermine gewährt hat:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Google APIs aufrufen

Nachdem Ihre Anwendung ein Zugriffstoken erhalten hat, können Sie damit im Namen eines bestimmten Nutzerkontos eine Google API aufrufen, sofern die von der API erforderlichen Zugriffsbereiche gewährt wurden. Dazu fügen Sie das Zugriffstoken in eine Anfrage an die API ein, indem Sie entweder einen access_token-Abfrageparameter oder einen Authorization-HTTP-Header-Bearer-Wert angeben. Wenn möglich, ist der HTTP-Header vorzuziehen, da Suchstrings in Serverprotokollen in der Regel sichtbar sind. In den meisten Fällen können Sie mit einer Clientbibliothek Aufrufe von Google APIs einrichten, z. B. beim Aufrufen der Drive Files API.

Im OAuth 2.0 Playground können Sie alle Google APIs ausprobieren und sich ihre Bereiche ansehen.

Beispiele für HTTP-GET

Ein Aufruf des Endpunkts drive.files (Drive Files API) mit dem HTTP-Header Authorization: Bearer könnte so aussehen: Sie müssen Ihr eigenes Zugriffstoken angeben:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Hier ist ein Aufruf derselben API für den authentifizierten Nutzer mit dem Abfragestringparameter access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Beispiele für curl

Sie können diese Befehle mit der Befehlszeilenanwendung curl testen. Hier ein Beispiel, in dem die HTTP-Header-Option verwendet wird (bevorzugt):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Alternativ können Sie auch die Option „Abfragestringparameter“ verwenden:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Zugriffstokens aktualisieren

Zugriffstokens laufen regelmäßig ab und werden zu ungültigen Anmeldedaten für eine zugehörige API-Anfrage. Sie können ein Zugriffstoken aktualisieren, ohne den Nutzer um eine Berechtigung zu bitten, auch wenn der Nutzer nicht anwesend ist, wenn Sie den Offlinezugriff auf die mit dem Token verknüpften Bereiche angefordert haben.

Um ein Zugriffstoken zu aktualisieren, sendet Ihre Anwendung eine HTTPS-POST-Anfrage an den Autorisierungsserver (https://oauth2.googleapis.com/token) von Google, die die folgenden Parameter enthält:

Das folgende Snippet zeigt eine Beispielanfrage:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Solange der Nutzer den der Anwendung gewährten Zugriff nicht widerrufen hat, gibt der Tokenserver ein JSON-Objekt mit einem neuen Zugriffstoken zurück. Das folgende Snippet zeigt eine Beispielantwort:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

Die Anzahl der ausgestellten Aktualisierungstokens ist begrenzt. Es gibt ein Limit pro Kombination aus Kunde und Nutzer sowie ein Limit pro Nutzer für alle Kunden. Sie sollten Aktualisierungstokens im Langzeitspeicher speichern und so lange verwenden, wie sie gültig sind. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, kann es zu diesen Limits kommen. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.

Token widerrufen

In einigen Fällen möchte ein Nutzer den einer Anwendung erteilten Zugriff widerrufen. Nutzer können den Zugriff in den Kontoeinstellungen widerrufen. Weitere Informationen finden Sie im Hilfeartikel Websites und Apps von Drittanbietern mit Zugriff auf Ihr Konto im Abschnitt Zugriff auf Websites oder Apps entfernen.

Es ist auch möglich, dass eine Anwendung den ihr gewährten Zugriff programmatisch widerruft. Der programmatische Widerruf ist wichtig, wenn ein Nutzer sein Abo kündigt, eine App entfernt oder sich die von einer App benötigten API-Ressourcen erheblich geändert haben. Mit anderen Worten: Ein Teil des Entfernungsvorgangs kann eine API-Anfrage umfassen, um sicherzustellen, dass die zuvor der Anwendung erteilten Berechtigungen entfernt werden.

Wenn Sie ein Token programmatisch widerrufen möchten, sendet Ihre Anwendung eine Anfrage an https://oauth2.googleapis.com/revoke und fügt das Token als Parameter hinzu:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Das Token kann ein Zugriffs- oder Aktualisierungstoken sein. Wenn es sich bei dem Token um ein Zugriffstoken handelt und es ein entsprechendes Aktualisierungstoken hat, wird auch das Aktualisierungstoken widerrufen.

Wenn der Widerruf erfolgreich verarbeitet wurde, lautet der HTTP-Statuscode der Antwort 200. Bei Fehlerbedingungen wird der HTTP-Statuscode 400 zusammen mit einem Fehlercode zurückgegeben.

Methoden für App-Weiterleitungen