Die OAuth 2.0 APIs von Google können sowohl für die Authentifizierung als auch für die Autorisierung verwendet werden. In diesem Dokument wird unsere OAuth 2.0-Implementierung für die Authentifizierung beschrieben, die der OpenID Connect-Spezifikation entspricht und OpenID-zertifiziert ist. Die Dokumentation unter Using OAuth 2.0 to Access Google APIs gilt auch für diesen Dienst. Wenn Sie dieses Protokoll interaktiv ausprobieren möchten, empfehlen wir den Google OAuth 2.0 Playground. Wenn Sie Hilfe auf Stack Overflow benötigen, taggen Sie Ihre Fragen mit „google-oauth“.
OAuth 2.0 einrichten
Bevor Ihre Anwendung das OAuth 2.0-Authentifizierungssystem von Google für die Nutzeranmeldung verwenden kann, müssen Sie ein Projekt in der einrichten, um OAuth 2.0-Anmeldedaten zu erhalten, einen Weiterleitungs-URI festlegen und (optional) die Branding-Informationen anpassen, die Ihre Nutzer auf dem Zustimmungsbildschirm sehen. Sie können auch verwenden, um ein Dienstkonto zu erstellen, die Abrechnung zu aktivieren, Filter einzurichten und andere Aufgaben auszuführen. Weitere Informationen finden Sie in der -Hilfe.
OAuth 2.0-Anmeldedaten abrufen
Sie benötigen OAuth 2.0-Anmeldedaten, einschließlich einer Client-ID und eines Clientschlüssels, um Nutzer zu authentifizieren und Zugriff auf die APIs von Google zu erhalten.
Klicken Sie auf den folgenden Text, um die Client-ID und das Client-Geheimnis für einen bestimmten OAuth 2.0-Berechtigungsnachweis anzuzeigen: Wählen Sie den Berechtigungsnachweis aus . Wählen Sie im folgenden Fenster Ihr Projekt und die gewünschten Anmeldeinformationen aus und klicken Sie dann auf Anzeigen .
Oder zeigen Sie Ihre Client-ID und Ihr Client-Geheimnis auf der Seite Anmeldeinformationen in API Console :
- Go to the Credentials page.
- Klicken Sie auf den Namen Ihres Berechtigungsnachweises oder auf das Stiftsymbol ( create ). Ihre Kunden-ID und Ihr Geheimnis befinden sich oben auf der Seite.
Weiterleitungs-URI festlegen
Der Weiterleitungs-URI, den Sie in der festlegen, bestimmt, wohin Google Antworten auf Ihre Authentifizierungsanfragen sendet.
Gehen Sie wie folgt vor, um die Umleitungs-URIs für einen bestimmten OAuth 2.0-Berechtigungsnachweis zu erstellen, anzuzeigen oder zu bearbeiten:
- Go to the Credentials page.
- Klicken Sie im Abschnitt OAuth 2.0-Client-IDs der Seite auf einen Berechtigungsnachweis.
- Anzeigen oder Bearbeiten der Umleitungs-URIs.
Wenn auf der Seite Anmeldeinformationen kein Abschnitt zu OAuth 2.0-Client-IDs vorhanden ist, verfügt Ihr Projekt über keine OAuth-Anmeldeinformationen. Um einen zu erstellen, klicken Sie auf Anmeldeinformationen erstellen .
Zustimmungsbildschirm anpassen
Für Ihre Nutzer umfasst die OAuth 2.0-Authentifizierung einen Zustimmungsbildschirm, auf dem die Informationen beschrieben werden, die der Nutzer freigibt, und die geltenden Nutzungsbedingungen. Wenn sich der Nutzer beispielsweise anmeldet, wird er möglicherweise aufgefordert, Ihrer App Zugriff auf seine E-Mail-Adresse und grundlegende Kontoinformationen zu gewähren. Sie fordern Zugriff auf diese Informationen mit dem Parameter scope an, den Ihre App in ihre Authentifizierungsanfrage einfügt. Sie können auch Bereiche verwenden, um Zugriff auf andere Google-APIs anzufordern.
Auf dem Bildschirm für die Nutzereinwilligung werden auch Markeninformationen wie Ihr Produktname, Ihr Logo und eine Homepage-URL angezeigt. Sie haben die Kontrolle über die Branding-Informationen in der .
So aktivieren Sie den Zustimmungsbildschirm Ihres Projekts:
- Öffnen Sie das Consent Screen page im Google API Console .
- If prompted, select a project, or create a new one.
- Füllen Sie das Formular aus und klicken Sie auf Speichern .
Im folgenden Zustimmungsdialogfeld sehen Sie, was ein Nutzer sieht, wenn eine Kombination aus OAuth 2.0- und Google Drive-Bereichen in der Anfrage vorhanden ist. Dieses generische Dialogfeld wurde mit dem Google OAuth 2.0 Playground generiert und enthält daher keine Branding-Informationen, die in festgelegt wären.
Auf den Dienst zugreifen
Google und Drittanbieter stellen Bibliotheken zur Verfügung, mit denen Sie viele der Implementierungsdetails für die Authentifizierung von Nutzern und den Zugriff auf Google APIs erledigen können. Beispiele hierfür sind die Google Identity Services und die Google-Clientbibliotheken, die für eine Vielzahl von Plattformen verfügbar sind.
Wenn Sie keine Bibliothek verwenden möchten, folgen Sie der Anleitung im Rest dieses Dokuments. Dort werden die HTTP-Anfrageabläufe beschrieben, die den verfügbaren Bibliotheken zugrunde liegen.
Nutzer authentifizieren
Bei der Authentifizierung des Nutzers wird ein ID-Token abgerufen und validiert. ID-Tokens sind eine standardisierte Funktion von OpenID Connect, die für die Weitergabe von Identitätszusicherungen im Internet entwickelt wurde.
Die am häufigsten verwendeten Methoden zum Authentifizieren eines Nutzers und zum Abrufen eines ID-Tokens sind der „Server“-Ablauf und der „implizite“ Ablauf. Mit dem Serverablauf kann der Backend-Server einer Anwendung die Identität der Person überprüfen, die einen Browser oder ein Mobilgerät verwendet. Der implizite Ablauf wird verwendet, wenn eine clientseitige Anwendung (in der Regel eine JavaScript-App, die im Browser ausgeführt wird) direkt auf APIs zugreifen muss, anstatt den Back-End-Server zu verwenden.
In diesem Dokument wird beschrieben, wie Sie den Serverablauf zur Authentifizierung des Nutzers ausführen. Der implizite Ablauf ist aufgrund von Sicherheitsrisiken bei der Verarbeitung und Verwendung von Tokens auf der Clientseite deutlich komplizierter. Wenn Sie einen impliziten Ablauf implementieren müssen, empfehlen wir dringend die Verwendung von Google Identity Services.
Serverablauf
Sie müssen Ihre App in der einrichten, damit sie diese Protokolle verwenden und Ihre Nutzer authentifizieren kann. Wenn ein Nutzer versucht, sich mit Google anzumelden, müssen Sie Folgendes tun:
- Token für den Anti-Fälschungsstatus erstellen
- Authentifizierungsanfrage an Google senden
- Anti-Fälschungs-Status-Token bestätigen
codegegen Zugriffstoken und ID-Token eintauschen- Nutzerinformationen aus dem ID-Token abrufen
- Nutzer authentifizieren
1. Anti-Forgery-Status-Token erstellen
Sie müssen die Sicherheit Ihrer Nutzer schützen, indem Sie Request-Forgery-Angriffe verhindern. Im ersten Schritt wird ein eindeutiges Sitzungstoken erstellt, das den Status zwischen Ihrer App und dem Client des Nutzers enthält. Sie gleichen dieses eindeutige Sitzungstoken später mit der Authentifizierungsantwort ab, die vom Google OAuth-Anmeldedienst zurückgegeben wird, um zu prüfen, ob die Anfrage vom Nutzer und nicht von einem böswilligen Angreifer stammt. Diese Tokens werden oft als CSRF-Tokens (Cross-Site Request Forgery) bezeichnet.
Eine gute Wahl für ein Status-Token ist ein String mit etwa 30 Zeichen, der mit einem hochwertigen Zufallszahlengenerator erstellt wird. Eine andere ist ein Hash, der durch Signieren einiger Ihrer Sitzungsstatusvariablen mit einem Schlüssel generiert wird, der in Ihrem Backend geheim gehalten wird.
Der folgende Code zeigt, wie eindeutige Sitzungstokens generiert werden.
PHP
Sie müssen die Google APIs-Clientbibliothek für PHP herunterladen, um dieses Beispiel verwenden zu können.
// Create a state token to prevent request forgery. // Store it in the session for later validation. $state = bin2hex(random_bytes(128/8)); $app['session']->set('state', $state); // Set the client ID, token state, and application name in the HTML while // serving it. return $app['twig']->render('index.html', array( 'CLIENT_ID' => CLIENT_ID, 'STATE' => $state, 'APPLICATION_NAME' => APPLICATION_NAME ));
Java
Sie müssen die Google APIs-Clientbibliothek für Java herunterladen, um dieses Beispiel verwenden zu können.
// Create a state token to prevent request forgery. // Store it in the session for later validation. String state = new BigInteger(130, new SecureRandom()).toString(32); request.session().attribute("state", state); // Read index.html into memory, and set the client ID, // token state, and application name in the HTML before serving it. return new Scanner(new File("index.html"), "UTF-8") .useDelimiter("\\A").next() .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID) .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state) .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}", APPLICATION_NAME);
Python
Sie müssen die Google APIs-Clientbibliothek für Python herunterladen, um dieses Beispiel verwenden zu können.
# Create a state token to prevent request forgery. # Store it in the session for later validation. state = hashlib.sha256(os.urandom(1024)).hexdigest() session['state'] = state # Set the client ID, token state, and application name in the HTML while # serving it. response = make_response( render_template('index.html', CLIENT_ID=CLIENT_ID, STATE=state, APPLICATION_NAME=APPLICATION_NAME))
2. Authentifizierungsanfrage an Google senden
Im nächsten Schritt wird eine HTTPS-GET-Anfrage mit den entsprechenden URI-Parametern erstellt.
Beachten Sie, dass in allen Schritten dieses Prozesses HTTPS anstelle von HTTP verwendet wird. HTTP-Verbindungen werden abgelehnt. Sie sollten den Basis-URI aus dem Discovery-Dokument mit dem Metadatenwert authorization_endpoint abrufen. In der folgenden Diskussion wird davon ausgegangen, dass der Basis-URI https://accounts.google.com/o/oauth2/v2/auth ist.
Geben Sie für eine einfache Anfrage die folgenden Parameter an:
client_id, die Sie über die erhalten.response_type, das in einer einfachen Anfrage für den Autorisierungscode-Vorgangcodesein sollte. Weitere Informationen finden Sie unterresponse_type.scope, was in einer einfachen Anfrageopenid emailsein sollte.scoperedirect_urisollte der HTTP-Endpunkt auf Ihrem Server sein, der die Antwort von Google empfängt. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie in der Credentials pagekonfiguriert haben. Wenn dieser Wert nicht mit einem autorisierten URI übereinstimmt, schlägt die Anfrage mit einemredirect_uri_mismatch-Fehler fehl.statesollte den Wert des eindeutigen Sitzungstokens zum Schutz vor Fälschungen sowie alle anderen Informationen enthalten, die zum Wiederherstellen des Kontexts erforderlich sind, wenn der Nutzer zu Ihrer Anwendung zurückkehrt, z.B. die Start-URL.statenonceist ein zufälliger Wert, der von Ihrer App generiert wird und bei Vorhandensein einen Schutz vor Replay-Angriffen ermöglicht.login_hintkann die E-Mail-Adresse des Nutzers oder der Stringsubsein, der der Google-ID des Nutzers entspricht. Wenn Sie keinelogin_hintangeben und der Nutzer angemeldet ist, enthält der Zustimmungsbildschirm eine Anfrage zur Genehmigung der Weitergabe der E‑Mail-Adresse des Nutzers an Ihre App. Weitere Informationenlogin_hint- Verwenden Sie den Parameter
hd, um den OpenID Connect-Ablauf für Nutzer einer bestimmten Domain zu optimieren, die mit einer Google Workspace- oder Cloud-Organisation verknüpft ist (hd).
Hier ist ein Beispiel für einen vollständigen OpenID Connect-Authentifizierungs-URI mit Zeilenumbrüchen und Leerzeichen für eine bessere Lesbarkeit:
https://accounts.google.com/o/oauth2/v2/auth? response_type=code& client_id=424911365001.apps.googleusercontent.com& scope=openid%20email& redirect_uri=https%3A//oauth2.example.com/code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome& login_hint=jsmith@example.com& nonce=0394852-3190485-2490358& hd=example.com
Nutzer müssen ihre Einwilligung geben, wenn Ihre App neue Informationen über sie anfordert oder wenn Ihre App auf Konten zugreifen möchte, für die sie noch keine Genehmigung erhalten hat.
3. Anti-Forgery-Status-Token bestätigen
Die Antwort wird an die redirect_uri gesendet, die Sie in der Anfrage angegeben haben. Alle Antworten werden im Abfragestring zurückgegeben:
https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email
Auf dem Server müssen Sie bestätigen, dass die von Google empfangene state mit dem Sitzungstoken übereinstimmt, das Sie in Schritt 1 erstellt haben. Diese Roundtrip-Überprüfung trägt dazu bei, zu bestätigen, dass die Anfrage vom Nutzer und nicht von einem schädlichen Skript stammt.
Der folgende Code zeigt, wie Sie die in Schritt 1 erstellten Sitzungstokens bestätigen:
PHP
Sie müssen die Google APIs-Clientbibliothek für PHP herunterladen, um dieses Beispiel verwenden zu können.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if ($request->get('state') != ($app['session']->get('state'))) { return new Response('Invalid state parameter', 401); }
Java
Sie müssen die Google APIs-Clientbibliothek für Java herunterladen, um dieses Beispiel verwenden zu können.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if (!request.queryParams("state").equals( request.session().attribute("state"))) { response.status(401); return GSON.toJson("Invalid state parameter."); }
Python
Sie müssen die Google APIs-Clientbibliothek für Python herunterladen, um dieses Beispiel verwenden zu können.
# Ensure that the request is not a forgery and that the user sending # this connect request is the expected user. if request.args.get('state', '') != session['state']: response = make_response(json.dumps('Invalid state parameter.'), 401) response.headers['Content-Type'] = 'application/json' return response
4. code gegen Zugriffstoken und ID-Token tauschen
Die Antwort enthält einen code-Parameter, einen Einmalautorisierungscode, den Ihr Server gegen ein Zugriffs- und ein ID-Token eintauschen kann. Ihr Server führt diesen Austausch durch, indem er eine HTTPS-POST-Anfrage sendet. Die POST-Anfrage wird an den Token-Endpunkt gesendet, den Sie aus dem Discovery-Dokument mit dem Metadatenwert token_endpoint abrufen sollten. In der folgenden Diskussion wird davon ausgegangen, dass der Endpunkt https://oauth2.googleapis.com/token ist. Die Anfrage muss die folgenden Parameter im POST-Body enthalten:
| Felder | |
|---|---|
code |
Der Autorisierungscode, der von der ersten Anfrage zurückgegeben wird. |
client_id |
Die Client-ID, die Sie von der erhalten, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben. |
client_secret |
Der Clientschlüssel, den Sie von der erhalten, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben. |
redirect_uri |
Ein autorisierter Weiterleitungs-URI für den angegebenen client_id, der in der
angegeben ist, wie unter Weiterleitungs-URI festlegen beschrieben. |
grant_type |
Dieses Feld muss einen Wert von authorization_code enthalten,
wie in der OAuth 2.0-Spezifikation definiert. |
Die tatsächliche Anfrage könnte so aussehen:
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=https%3A//oauth2.example.com/code& grant_type=authorization_code
Eine erfolgreiche Antwort auf diese Anfrage enthält die folgenden Felder in einem JSON-Array:
| Felder | |
|---|---|
access_token |
Ein Token, das an eine Google API gesendet werden kann. |
expires_in |
Die verbleibende Lebensdauer des Zugriffstokens in Sekunden. |
id_token |
Ein JWT, das Identitätsinformationen über den Nutzer enthält, die von Google digital signiert wurden. |
scope |
Die von access_token gewährten Zugriffsbereiche, ausgedrückt als Liste von durch Leerzeichen getrennten, groß- und kleinschreibungsabhängigen Strings. |
token_type |
Gibt den Typ des zurückgegebenen Tokens an. Derzeit hat dieses Feld immer den Wert Bearer.
|
refresh_token |
(optional)
Dieses Feld ist nur vorhanden, wenn der Parameter |
5. Nutzerinformationen aus dem ID-Token abrufen
Ein ID-Token ist ein JWT (JSON Web Token), d. h. ein kryptografisch signiertes, Base64-codiertes JSON-Objekt. Normalerweise ist es wichtig, dass Sie ein ID-Token validieren, bevor Sie es verwenden. Da Sie jedoch direkt über einen HTTPS-Kanal ohne Vermittler mit Google kommunizieren und Ihr Clientgeheimnis verwenden, um sich bei Google zu authentifizieren, können Sie sicher sein, dass das empfangene Token tatsächlich von Google stammt und gültig ist. Wenn Ihr Server das ID-Token an andere Komponenten Ihrer App übergibt, ist es äußerst wichtig, dass die anderen Komponenten das Token validieren, bevor sie es verwenden.
Da bei den meisten API-Bibliotheken die Validierung mit der Decodierung der base64url-codierten Werte und dem Parsen des JSON-Inhalts kombiniert wird, validieren Sie das Token wahrscheinlich ohnehin, wenn Sie auf die Ansprüche im ID-Token zugreifen.
Nutzlast eines ID-Tokens
Ein ID-Token ist ein JSON-Objekt, das eine Reihe von Name/Wert-Paaren enthält. Hier ein Beispiel, das zur besseren Lesbarkeit formatiert wurde:
{ "iss": "https://accounts.google.com", "azp": "1234987819200.apps.googleusercontent.com", "aud": "1234987819200.apps.googleusercontent.com", "sub": "10769150350006150715113082367", "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q", "hd": "example.com", "email": "jsmith@example.com", "email_verified": "true", "iat": 1353601026, "exp": 1353604926, "nonce": "0394852-3190485-2490358" }
Google-ID-Tokens können die folgenden Felder (als Claims bezeichnet) enthalten:
| Anspruch | Bereitgestellt | Beschreibung |
|---|---|---|
aud |
immer | Die Zielgruppe, für die dieses ID-Token bestimmt ist. Es muss sich um eine der OAuth 2.0-Client-IDs Ihrer Anwendung handeln. |
exp |
immer | Ablaufzeit, nach der das ID-Token nicht mehr akzeptiert werden darf. Dargestellt in Unix-Epochenzeit (Ganzzahl in Sekunden). |
iat |
immer | Der Zeitpunkt, zu dem das ID-Token ausgestellt wurde. Dargestellt in Unix-Epochenzeit (Ganzzahl in Sekunden). |
iss |
immer | Die Aussteller-ID für den Aussteller der Antwort. Immer https://accounts.google.com oder accounts.google.com für Google-ID-Tokens. |
sub |
immer | Eine Kennung für den Nutzer, die für alle Google-Konten eindeutig ist und nie wiederverwendet wird. Ein Google-Konto kann zu verschiedenen Zeitpunkten mehrere E-Mail-Adressen haben, der Wert sub wird jedoch nie geändert. Verwenden Sie sub in Ihrer Anwendung als eindeutigen Kennungsschlüssel für den Nutzer. Maximale Länge: 255 ASCII-Zeichen (Groß-/Kleinschreibung wird berücksichtigt). |
at_hash |
Hash des Zugriffstokens. Bietet eine Validierung, dass das Zugriffstoken mit dem Identitätstoken verknüpft ist. Wenn das ID-Token mit einem access_token-Wert im Serverablauf ausgestellt wird, ist dieser Anspruch immer enthalten. Dieser Anspruch kann als alternativer Mechanismus zum Schutz vor Cross-Site-Request-Forgery-Angriffen verwendet werden. Wenn Sie jedoch Schritt 1 und Schritt 3 ausführen, ist es nicht erforderlich, das Zugriffstoken zu bestätigen. |
|
azp |
Die client_id des autorisierten Moderators. Dieser Anspruch ist nur erforderlich, wenn die Partei, die das ID-Token anfordert, nicht mit der Zielgruppe des ID-Tokens identisch ist. Das kann bei Google bei Hybrid-Apps der Fall sein, bei denen eine Webanwendung und eine Android-App ein anderes OAuth 2.0-client_id haben, aber dasselbe Google APIs-Projekt verwenden. |
|
email |
Die E-Mail-Adresse des Nutzers. Wird nur bereitgestellt, wenn Sie den Bereich email in Ihre Anfrage aufgenommen haben. Der Wert dieses Anspruchs ist möglicherweise nicht eindeutig für dieses Konto und kann sich im Laufe der Zeit ändern. Verwenden Sie ihn daher nicht als primäre Kennung, um eine Verknüpfung zu Ihrem Nutzerdatensatz herzustellen. Sie können sich auch nicht auf die Domain des email-Anspruchs verlassen, um Nutzer von Google Workspace- oder Cloud-Organisationen zu identifizieren. Verwenden Sie stattdessen den hd-Anspruch.
|
|
email_verified |
„True“, wenn die E-Mail-Adresse des Nutzers bestätigt wurde, andernfalls „false“. | |
family_name |
Der/die Nachname(n) des Nutzers. Kann angegeben werden, wenn ein Anspruch vom Typ name vorhanden ist. |
|
given_name |
Der oder die Vornamen des Nutzers. Kann angegeben werden, wenn ein Anspruch vom Typ name vorhanden ist. |
|
hd |
Die Domain, die mit der Google Workspace- oder Cloud-Organisation des Nutzers verknüpft ist. Wird nur bereitgestellt, wenn der Nutzer zu einer Google Cloud-Organisation gehört. Sie müssen diesen Anspruch prüfen, wenn Sie den Zugriff auf eine Ressource auf Mitglieder bestimmter Domains beschränken. Das Fehlen dieser Behauptung weist darauf hin, dass das Konto nicht zu einer von Google gehosteten Domain gehört. | |
locale |
Die Sprache des Nutzers, dargestellt durch ein BCP 47-Sprachentag.
Kann angegeben werden, wenn ein name-Anspruch vorhanden ist. |
|
name |
Der vollständige Name des Nutzers in einer anzeigbaren Form. Kann angegeben werden, wenn:
Wenn |
|
nonce |
Der Wert von nonce, der von Ihrer App in der Authentifizierungsanfrage angegeben wird.
Sie sollten sich vor Replay-Angriffen schützen, indem Sie diesen Wert nur einmal präsentieren. |
|
picture |
Die URL des Profilbilds des Nutzers. Kann angegeben werden, wenn:
Wenn |
|
profile |
Die URL der Profilseite des Nutzers. Kann angegeben werden, wenn:
Wenn |
6. Nutzer authentifizieren
Nachdem Sie Nutzerinformationen aus dem ID-Token abgerufen haben, sollten Sie die Nutzerdatenbank Ihrer App abfragen. Wenn der Nutzer bereits in Ihrer Datenbank vorhanden ist, sollten Sie eine Anwendungssitzung für diesen Nutzer starten, sofern alle Anmeldeanforderungen durch die Google API-Antwort erfüllt werden.
Wenn der Nutzer nicht in Ihrer Nutzerdatenbank vorhanden ist, sollten Sie ihn zum Registrierungsvorgang für neue Nutzer weiterleiten. Möglicherweise können Sie den Nutzer anhand der Informationen, die Sie von Google erhalten, automatisch registrieren oder zumindest viele der Felder in Ihrem Registrierungsformular vorab ausfüllen. Zusätzlich zu den Informationen im ID-Token können Sie an unseren Endpunkten für Nutzerprofile weitere Informationen zum Nutzerprofil abrufen.
Themen für Fortgeschrittene
In den folgenden Abschnitten wird die Google OAuth 2.0 API genauer beschrieben. Diese Informationen richten sich an Entwickler mit besonderen Anforderungen an die Authentifizierung und Autorisierung.
Zugriff auf andere Google APIs
Einer der Vorteile der Verwendung von OAuth 2.0 für die Authentifizierung besteht darin, dass Ihre Anwendung gleichzeitig mit der Authentifizierung des Nutzers die Berechtigung zur Verwendung anderer Google-APIs im Namen des Nutzers (z. B. YouTube, Google Drive, Kalender oder Kontakte) erhalten kann. Fügen Sie dazu die anderen erforderlichen Bereiche in die Authentifizierungsanfrage ein, die Sie an Google senden. Wenn Sie beispielsweise die Altersgruppe des Nutzers in Ihre Authentifizierungsanfrage aufnehmen möchten, übergeben Sie den Bereichsparameter openid email https://www.googleapis.com/auth/profile.agerange.read. Der Nutzer wird auf dem Zustimmungsbildschirm entsprechend aufgefordert. Mit dem Zugriffstoken, das Sie von Google erhalten, kann Ihre Anwendung auf alle APIs zugreifen, die mit den von Ihnen angeforderten und gewährten Zugriffsbereichen verknüpft sind.
Aktualisierungstokens
In Ihrer Anfrage für API-Zugriff können Sie anfordern, dass während des code-Austauschs ein Aktualisierungstoken zurückgegeben wird. Ein Aktualisierungstoken ermöglicht Ihrer App den kontinuierlichen Zugriff auf Google APIs, auch wenn der Nutzer nicht in Ihrer Anwendung angemeldet ist. Wenn Sie ein Aktualisierungstoken anfordern möchten, setzen Sie den Parameter access_type in Ihrer Authentifizierungsanfrage auf offline.
Wichtige Hinweise:
- Speichern Sie das Aktualisierungstoken sicher und dauerhaft, da Sie es nur beim ersten Ausführen des Code-Austausch-Ablaufs erhalten.
- Die Anzahl der ausgegebenen Aktualisierungstokens ist begrenzt: einmal pro Client-/Nutzerkombination und einmal pro Nutzer für alle Clients. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, kann es sein, dass diese Limits erreicht werden. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.
Weitere Informationen finden Sie unter Zugriffstoken aktualisieren (Offlinezugriff).
Erneute Einwilligung einholen
Sie können den Nutzer auffordern, Ihre App noch einmal zu autorisieren, indem Sie den Parameter prompt in Ihrer Authentifizierungsanfrage auf consent setzen. Wenn prompt=consent enthalten ist, wird der Zustimmungsbildschirm jedes Mal angezeigt, wenn Ihre App die Autorisierung von Zugriffsbereichen anfordert, auch wenn alle Bereiche zuvor für Ihr Google APIs-Projekt gewährt wurden. Fügen Sie prompt=consent daher nur bei Bedarf ein.
Weitere Informationen zum Parameter prompt finden Sie in der Tabelle Authentifizierungs-URI-Parameter unter prompt.
Authentifizierungs-URI-Parameter
In der folgenden Tabelle finden Sie genauere Beschreibungen der Parameter, die von der OAuth 2.0-Authentifizierungs-API von Google akzeptiert werden.
| Parameter | Erforderlich | Beschreibung |
|---|---|---|
client_id |
(Erforderlich) | Der Client-ID-String, den Sie von abrufen, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben. |
nonce |
(Erforderlich) | Ein zufälliger Wert, der von Ihrer App generiert wird und den Replay-Schutz ermöglicht. |
response_type |
(Erforderlich) | Wenn der Wert code ist, wird ein einfacher Autorisierungscode-Vorgang gestartet, für den ein POST an den Token-Endpunkt erforderlich ist, um die Tokens zu erhalten. Wenn der Wert token id_token oder id_token token ist, wird ein impliziter Ablauf gestartet. Dazu muss JavaScript im Redirect-URI verwendet werden, um Tokens aus dem URI-Fragmentbezeichner #fragment abzurufen. |
redirect_uri |
(Erforderlich) | Legt fest, wohin die Antwort gesendet wird. Der Wert dieses Parameters muss genau mit einem der autorisierten Weiterleitungswerte übereinstimmen, die Sie in festgelegt haben(einschließlich des HTTP- oder HTTPS-Schemas, der Groß-/Kleinschreibung und des abschließenden „/“, falls vorhanden). |
scope |
(Erforderlich) | Der Parameter „scope“ muss mit dem Wert Wenn der Bereichswert Wenn der Bereichswert Zusätzlich zu diesen OpenID-spezifischen Bereichen kann Ihr Bereichsargument auch andere Bereichswerte enthalten. Alle Bereichswerte müssen durch Leerzeichen getrennt werden. Wenn Sie beispielsweise dateibezogenen Zugriff auf Google Drive eines Nutzers benötigen, könnte Ihr Bereichsparameter Informationen zu den verfügbaren Bereichen finden Sie unter OAuth 2.0-Bereiche für Google APIs oder in der Dokumentation der Google API, die Sie verwenden möchten. |
state |
(Optional, aber dringend empfohlen) | Ein nicht transparenter String, der im Protokoll hin und her gesendet wird. Das heißt, er wird im Basic-Ablauf als URI-Parameter und im Implicit-Ablauf als Die |
access_type |
(Optional) | Die zulässigen Werte sind offline und online. Die Auswirkungen sind unter Offlinezugriff dokumentiert. Wenn ein Zugriffstoken angefordert wird, erhält der Client kein Aktualisierungstoken, sofern kein Wert von offline angegeben ist. |
display |
(Optional) | Ein ASCII-Stringwert, der angibt, wie der Autorisierungsserver die Seiten der Benutzeroberfläche für die Authentifizierung und Einwilligung anzeigt. Die folgenden Werte werden angegeben und von den Google-Servern akzeptiert, haben aber keine Auswirkungen auf das Verhalten des Protokollflusses: page, popup, touch und wap. |
hd |
(Optional) | Den Anmeldevorgang für Konten, die einer Google Cloud-Organisation gehören, optimieren. Wenn Sie die Domain der Google Cloud-Organisation (z. B. mycollege.edu) angeben, können Sie festlegen, dass die Benutzeroberfläche zur Kontoauswahl für Konten in dieser Domain optimiert werden soll. Wenn Sie die Optimierung für Google Cloud-Organisationskonten im Allgemeinen anstelle nur einer Google Cloud-Organisationsdomain vornehmen möchten, legen Sie den Wert auf ein Sternchen ( Verlassen Sie sich nicht auf diese UI-Optimierung, um zu steuern, wer auf Ihre App zugreifen kann, da clientseitige Anfragen geändert werden können. Prüfen Sie, ob das zurückgegebene ID-Token einen |
include_granted_scopes |
(Optional) | Wenn dieser Parameter mit dem Wert true angegeben wird und die Autorisierungsanfrage gewährt wird, umfasst die Autorisierung alle vorherigen Autorisierungen, die dieser Kombination aus Nutzer und Anwendung für andere Bereiche gewährt wurden. Weitere Informationen finden Sie unter Inkrementelle Autorisierung.
Hinweis: Mit dem Ablauf für installierte Apps ist keine inkrementelle Autorisierung möglich. |
login_hint |
(Optional) | Wenn Ihre App weiß, welcher Nutzer authentifiziert werden soll, kann sie diesen Parameter als Hinweis an den Authentifizierungsserver senden. Wenn Sie diesen Hinweis übergeben, wird die Kontoauswahl unterdrückt und entweder das E-Mail-Feld im Anmeldeformular wird vorausgefüllt oder die richtige Sitzung wird ausgewählt (wenn der Nutzer mehrfache Anmeldung verwendet). So können Sie Probleme vermeiden, die auftreten, wenn sich Ihre App mit dem falschen Nutzerkonto anmeldet.
Der Wert kann entweder eine E-Mail-Adresse oder der String sub sein, der der Google-ID des Nutzers entspricht. |
prompt |
(Optional) | Eine durch Leerzeichen getrennte Liste von Stringwerten, die angibt, ob der Autorisierungsserver den Nutzer zur erneuten Authentifizierung und Einwilligung auffordert. Die möglichen Werte sind:
Wenn kein Wert angegeben ist und der Nutzer den Zugriff noch nicht autorisiert hat, wird ihm ein Zustimmungsbildschirm angezeigt. |
ID-Token validieren
Sie müssen alle ID-Tokens auf Ihrem Server validieren, sofern Sie nicht wissen, dass sie direkt von Google stammen. Ihr Server muss beispielsweise alle ID-Tokens, die er von Ihren Client-Apps erhält, als authentisch bestätigen.
Im Folgenden finden Sie einige gängige Situationen, in denen Sie ID-Tokens an Ihren Server senden:
- ID-Tokens mit Anfragen senden, die authentifiziert werden müssen. Die ID-Tokens geben an, welcher Nutzer die Anfrage stellt und für welchen Client das ID-Token gewährt wurde.
ID-Tokens sind vertraulich und können missbraucht werden, wenn sie abgefangen werden. Sie müssen dafür sorgen, dass diese Tokens sicher verarbeitet werden, indem Sie sie nur über HTTPS und nur mit POST-Daten oder in Anfrageheadern übertragen. Wenn Sie ID-Tokens auf Ihrem Server speichern, müssen Sie sie auch sicher speichern.
ID-Tokens sind unter anderem deshalb nützlich, weil Sie sie an verschiedene Komponenten Ihrer App weitergeben können. Diese Komponenten können ein ID-Token als einfachen Authentifizierungsmechanismus verwenden, um die App und den Nutzer zu authentifizieren. Bevor Sie die Informationen im ID-Token verwenden oder sich darauf verlassen können, dass der Nutzer authentifiziert wurde, müssen Sie es validieren.
Die Validierung eines ID-Tokens erfordert mehrere Schritte:
- Prüfen Sie, ob das ID-Token vom Aussteller ordnungsgemäß signiert wurde. Von Google ausgestellte Tokens werden mit einem der Zertifikate signiert, die unter dem URI zu finden sind, der im
jwks_uri-Metadatenwert des Discovery-Dokuments angegeben ist. - Prüfen Sie, ob der Wert des Anspruchs
issim ID-Token gleichhttps://accounts.google.comoderaccounts.google.comist. - Prüfen Sie, ob der Wert der Anforderung
audim ID-Token mit der Client-ID Ihrer App übereinstimmt. - Prüfen Sie, ob die Ablaufzeit (
exp-Anspruch) des ID-Tokens abgelaufen ist. - Wenn Sie in der Anfrage einen Wert für den hd-Parameter angegeben haben, prüfen Sie, ob das ID-Token einen
hd-Anspruch enthält, der mit einer akzeptierten Domain übereinstimmt, die mit einer Google Cloud-Organisation verknüpft ist.
Die Schritte 2 bis 5 umfassen nur String- und Datumsvergleiche, die recht einfach sind, daher werden sie hier nicht im Detail beschrieben.
Der erste Schritt ist komplexer und umfasst die Prüfung der kryptografischen Signatur. Zur Fehlerbehebung können Sie den tokeninfo-Endpunkt von Google verwenden, um ihn mit der lokalen Verarbeitung auf Ihrem Server oder Gerät zu vergleichen. Angenommen, der Wert Ihres ID-Tokens ist XYZ123. Anschließend würden Sie den URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123 dereferenzieren. Wenn die Tokensignatur gültig ist, ist die Antwort die JWT-Nutzlast in ihrer decodierten JSON-Objektform.
Der tokeninfo-Endpunkt ist nützlich für das Debugging. Für Produktionszwecke sollten Sie jedoch die öffentlichen Schlüssel von Google über den Schlüsselendpunkt abrufen und die Validierung lokal durchführen. Sie sollten den URI der Schlüssel aus dem Discovery-Dokument mit dem Metadatenwert jwks_uri abrufen. Anfragen an den Debugging-Endpunkt können gedrosselt werden oder anderweitig vorübergehende Fehler verursachen.
Da Google seine öffentlichen Schlüssel nur selten ändert, können Sie sie mit den Cache-Anweisungen der HTTP-Antwort im Cache speichern und in den meisten Fällen die lokale Validierung viel effizienter durchführen als über den tokeninfo-Endpunkt. Für diese Validierung müssen Zertifikate abgerufen und geparst werden. Außerdem müssen die entsprechenden kryptografischen Aufrufe erfolgen, um die Signatur zu prüfen. Glücklicherweise sind für diesen Zweck gut debuggte Bibliotheken in einer Vielzahl von Sprachen verfügbar (siehe jwt.io).
Nutzerprofilinformationen abrufen
Wenn Sie zusätzliche Profilinformationen zum Nutzer abrufen möchten, können Sie das Zugriffstoken (das Ihre Anwendung während des Authentifizierungsablaufs erhält) und den OpenID Connect-Standard verwenden:
Damit Sie OpenID-konform sind, müssen Sie die Bereichswerte
openid profilein Ihre Authentifizierungsanfrage aufnehmen.Wenn Sie die E-Mail-Adresse des Nutzers einbeziehen möchten, können Sie einen zusätzlichen Bereichswert von
emailangeben. Wenn Sie sowohlprofileals auchemailangeben möchten, können Sie den folgenden Parameter in den Authentifizierungsanfrage-URI aufnehmen:scope=openid%20profile%20email
- Fügen Sie Ihr Zugriffstoken dem Autorisierungsheader hinzu und senden Sie eine HTTPS-
GET-Anfrage an den userinfo-Endpunkt. Sie sollten ihn aus dem Discovery-Dokument mit dem Metadatenwertuserinfo_endpointabrufen. Die userinfo-Antwort enthält Informationen zum Nutzer, wie inOpenID Connect Standard Claimsbeschrieben, und denclaims_supported-Metadatenwert des Discovery-Dokuments. Nutzer oder ihre Organisationen können bestimmte Felder angeben oder nicht angeben. Daher erhalten Sie möglicherweise nicht für jedes Feld Informationen für Ihre autorisierten Zugriffsbereiche.
Das Discovery-Dokument
Das OpenID Connect-Protokoll erfordert die Verwendung mehrerer Endpunkte für die Authentifizierung von Nutzern und für das Anfordern von Ressourcen wie Tokens, Nutzerinformationen und öffentlichen Schlüsseln.
Um die Implementierung zu vereinfachen und die Flexibilität zu erhöhen, erlaubt OpenID Connect die Verwendung eines „Discovery-Dokuments“. Dieses JSON-Dokument befindet sich an einem bekannten Ort und enthält Schlüssel/Wert-Paare mit Details zur Konfiguration des OpenID Connect-Anbieters, einschließlich der URIs der Autorisierungs-, Token-, Widerrufs-, Userinfo- und Public-Keys-Endpunkte. Das Discovery-Dokument für den OpenID Connect-Dienst von Google kann unter folgender Adresse abgerufen werden:
https://accounts.google.com/.well-known/openid-configuration
Wenn Sie die OpenID Connect-Dienste von Google verwenden möchten, sollten Sie den URI des Discovery-Dokuments (https://accounts.google.com/.well-known/openid-configuration) in Ihre Anwendung einprogrammieren.
Ihre Anwendung ruft das Dokument ab, wendet Caching-Regeln in der Antwort an und ruft dann bei Bedarf Endpunkt-URIs daraus ab. Wenn Sie beispielsweise einen Nutzer authentifizieren möchten, ruft Ihr Code den Metadatenwert authorization_endpoint (https://accounts.google.com/o/oauth2/v2/auth im Beispiel unten) als Basis-URI für Authentifizierungsanfragen ab, die an Google gesendet werden.
Hier ist ein Beispiel für ein solches Dokument. Die Feldnamen sind die, die in OpenID Connect Discovery 1.0 angegeben sind. Die Bedeutung der einzelnen Felder finden Sie in diesem Dokument. Die Werte sind rein illustrativ und können sich ändern. Sie wurden jedoch aus einer aktuellen Version des tatsächlichen Google Discovery-Dokuments kopiert:
{ "issuer": "https://accounts.google.com", "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth", "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code", "token_endpoint": "https://oauth2.googleapis.com/token", "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo", "revocation_endpoint": "https://oauth2.googleapis.com/revoke", "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs", "response_types_supported": [ "code", "token", "id_token", "code token", "code id_token", "token id_token", "code token id_token", "none" ], "subject_types_supported": [ "public" ], "id_token_signing_alg_values_supported": [ "RS256" ], "scopes_supported": [ "openid", "email", "profile" ], "token_endpoint_auth_methods_supported": [ "client_secret_post", "client_secret_basic" ], "claims_supported": [ "aud", "email", "email_verified", "exp", "family_name", "given_name", "iat", "iss", "locale", "name", "picture", "sub" ], "code_challenge_methods_supported": [ "plain", "S256" ] }
Sie können einen HTTP-Roundtrip vermeiden, indem Sie die Werte aus dem Discovery-Dokument im Cache speichern. Es werden Standard-HTTP-Caching-Header verwendet, die berücksichtigt werden sollten.
Clientbibliotheken
Die folgenden Clientbibliotheken vereinfachen die Implementierung von OAuth 2.0 durch die Integration in beliebte Frameworks:
OpenID Connect-Konformität
Das OAuth 2.0-Authentifizierungssystem von Google unterstützt die erforderlichen Funktionen der OpenID Connect Core-Spezifikation. Jeder Client, der für die Verwendung mit OpenID Connect entwickelt wurde, sollte mit diesem Dienst zusammenarbeiten (mit Ausnahme des OpenID-Anfrageobjekts).