Die OAuth 2.0 APIs von Google können zur Authentifizierung und Autorisierung verwendet werden. In diesem Dokument wird die OAuth 2.0-Implementierung für die Authentifizierung beschrieben, die der OpenID Connect-Spezifikation entspricht und OpenID-zertifiziert ist. Die Dokumentation unter OAuth 2.0 für den Zugriff auf Google APIs verwenden gilt auch für diesen Dienst. Wenn Sie sich dieses Protokoll interaktiv ansehen möchten, empfehlen wir den Google OAuth 2.0 Playground. Wenn Sie Hilfe bei 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 im Google API Console einrichten, um OAuth 2.0-Anmeldedaten abzurufen, einen Weiterleitungs-URI festzulegen und (optional) die Branding-Informationen anzupassen, die Ihre Nutzer auf dem Bildschirm zur Nutzereinwilligung sehen. Sie können API Console auch verwenden, um ein Dienstkonto zu erstellen, die Abrechnung zu aktivieren, die Filterung einzurichten und andere Aufgaben zu erledigen. Weitere Informationen finden Sie in der Google API Console-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 du in der API Console festgelegt hast, bestimmt, wohin Google Antworten auf deine 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 für Nutzer anpassen
Für Ihre Nutzer umfasst die OAuth 2.0-Authentifizierung einen Zustimmungsbildschirm, auf dem die von dem Nutzer freigegebenen Informationen und die geltenden Bedingungen beschrieben werden. Wenn sich ein Nutzer anmeldet, wird er beispielsweise aufgefordert, Ihrer App Zugriff auf seine E-Mail-Adresse und grundlegende Kontoinformationen zu geben. Mit dem Parameter scope
fordern Sie Zugriff auf diese Informationen an. Er wird in die Authentifizierungsanfrage Ihrer Anwendung aufgenommen. Sie können Bereiche auch verwenden, um den Zugriff auf andere Google APIs anzufordern.
Der Bildschirm zur Nutzereinwilligung enthält auch Markeninformationen wie deinen Produktnamen, dein Logo und eine Startseiten-URL. Die Markeninformationen werden über die API Consoleverwaltet.
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 Dialog zur Einholung von Einwilligungen wird angezeigt, was der Nutzer sehen würde, wenn eine Kombination aus OAuth 2.0- und Google Drive-Bereichen in der Anfrage vorhanden ist. (Dieses generische Dialogfeld wurde mit Google OAuth 2.0 Playground erstellt und enthält daher keine Branding-Informationen, die in API Consolefestgelegt würden.)

Auf den Dienst zugreifen
Google und Drittanbieter stellen Bibliotheken zur Verfügung, mit denen Sie viele der Implementierungsdetails zum Authentifizieren von Nutzern und zum Zugriff auf Google APIs verwalten können. Beispiele hierfür sind Google Identity Services und die Google-Clientbibliotheken, die auf einer Vielzahl von Plattformen verfügbar sind.
Wenn Sie keine Bibliothek verwenden, folgen Sie der Anleitung im restlichen Dokument, in der die HTTP-Anfrageflüsse beschrieben werden, die den verfügbaren Bibliotheken zugrunde liegen.
Nutzer authentifizieren
Zum Authentifizieren des Nutzers müssen Sie ein ID-Token abrufen und validieren. ID-Tokens sind eine standardisierte Funktion von OpenID Connect, die für die Freigabe von Identitätsbestätigungen im Internet entwickelt wurde.
Die am häufigsten verwendeten Ansätze zur Authentifizierung eines Nutzers und zum Abrufen eines ID-Tokens werden als Server- und impliziter Ablauf bezeichnet. Über den Serverfluss kann der Back-End-Server einer Anwendung die Identität der Person mithilfe eines Browsers oder eines Mobilgeräts überprüfen. Der implizite Ablauf wird verwendet, wenn eine clientseitige Anwendung (normalerweise eine im Browser ausgeführte JavaScript-Anwendung) direkt auf APIs und nicht über ihren Back-End-Server zugreifen muss.
In diesem Dokument wird beschrieben, wie Sie den Serverfluss zur Authentifizierung des Nutzers ausführen. Der implizite Ablauf ist aufgrund von Sicherheitsrisiken bei der Verarbeitung und Verwendung von Tokens auf der Clientseite erheblich komplizierter. Wenn Sie einen impliziten Vorgang implementieren müssen, empfehlen wir dringend die Verwendung von Google Identity Services.
Serverfluss
Richten Sie Ihre Anwendung in der API Consoleein, damit diese Protokolle verwendet und Ihre Nutzer authentifiziert werden können. Wenn ein Nutzer versucht, sich über Google anzumelden, müssen Sie Folgendes tun:
- Anti-Fälschungs-Statustoken erstellen
- Authentifizierungsanfrage an Google senden
- Token zur Bestätigung der Fälschungsstatus bestätigen
- Exchange
code
für Zugriffstoken und ID-Token austauschen - Nutzerinformationen aus dem ID-Token abrufen
- Nutzer authentifizieren
1. Fälschungsschutztoken erstellen
Sie müssen die Sicherheit Ihrer Nutzer schützen, indem Sie Fälschungsangriffe verhindern. Im ersten Schritt wird ein eindeutiges Sitzungstoken erstellt, das den Status zwischen der Anwendung und dem Client des Nutzers enthält. Später stimmen Sie dieses eindeutige Sitzungstoken mit der Authentifizierungsantwort ab, die vom Google OAuth-Anmeldedienst zurückgegeben wird, um zu bestätigen, dass der Nutzer die Anfrage stellt und kein böswilliger Angreifer. Diese Tokens werden häufig als CSRF-Tokens (Cross-Site Request Forgery) bezeichnet.
Eine gute Wahl für ein Zustandstoken ist ein String mit etwa 30 Zeichen, der mit einem hochwertigen Zufallszahlgenerator erstellt wird. Ein weiterer Hash wird generiert, indem einige Ihrer Sitzungsstatusvariablen mit einem Schlüssel signiert werden, der im Back-End 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 Vorgangs HTTPS anstelle von HTTP verwendet wird. HTTP-Verbindungen werden abgelehnt. Sie sollten den Basis-URI aus dem Discovery-Dokument mithilfe des Metadatenwerts authorization_endpoint
abrufen. In der folgenden Diskussion wird davon ausgegangen, dass der Basis-URI https://accounts.google.com/o/oauth2/v2/auth
lautet.
Geben Sie für eine einfache Anfrage die folgenden Parameter an:
client_id
, die Sie über API ConsoleCredentials pageabrufen.response_type
, die in einer grundlegenden Anfrage für einen Autorisierungscodecode
sein sollte. Weitere Informationen finden Sie unterresponse_type
.scope
, die in einer einfachen Anfrageopenid email
sein sollte. Weitere Informationen finden Sie unterscope
.redirect_uri
sollte 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 API ConsoleCredentials pagekonfiguriert haben. Wenn dieser Wert nicht mit einem autorisierten URI übereinstimmt, schlägt die Anfrage mit dem Fehlerredirect_uri_mismatch
fehl.state
sollte den Wert des eindeutigen Fälschungssicherungstokens sowie alle anderen Informationen enthalten, die zum Wiederherstellen des Kontextes erforderlich sind, wenn der Nutzer zu Ihrer Anwendung zurückkehrt, z.B. die Start-URL. Weitere Informationen finden Sie unterstate
.nonce
ist ein zufälliger Wert, der von Ihrer App generiert wird und den Wiederholungsschutz aktiviert, falls vorhanden.login_hint
kann die E-Mail-Adresse des Nutzers oder der Stringsub
sein, der der Google-ID des Nutzers entspricht. Wenn du keinlogin_hint
angibst und der Nutzer aktuell angemeldet ist, enthält der Zustimmungsbildschirm eine Genehmigungsanfrage, damit die E-Mail-Adresse des Nutzers für deine App freigegeben werden kann. Weitere Informationen findest du unterlogin_hint
.- Verwenden Sie den Parameter
hd
, um den OpenID Connect-Ablauf für Nutzer einer bestimmten Domain zu optimieren, die einer Google Cloud-Organisation zugeordnet ist. Weitere Informationen finden Sie unterhd
.
Hier ein Beispiel für einen vollständigen OpenID Connect-Authentifizierungs-URI mit Zeilenumbrüchen und Leerzeichen:
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 Kontozugriff anfordert, den sie noch nicht genehmigt haben.
3. Bestätigung der Fälschungsstatus
Die Antwort wird an die redirect_uri
gesendet, die Sie in der Anfrage angegeben haben. Alle Antworten werden wie im folgenden Beispiel 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 prüfen, ob state
von Google mit dem Sitzungstoken übereinstimmt, das Sie in Schritt 1 erstellt haben. Mit dieser Umlaufbestätigung wird sichergestellt, dass der Nutzer kein schädliches Skript sendet.
Der folgende Code zeigt die Bestätigung der Sitzungstokens, die Sie in Schritt 1 erstellt haben:
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 austauschen
Die Antwort enthält einen code
-Parameter, einen einmaligen Autorisierungscode, den Ihr Server gegen ein Zugriffstoken und ein ID-Token austauschen kann. Ihr Server führt diesen Austausch durch, indem er eine HTTPS-POST
-Anfrage sendet. Die POST
-Anfrage wird an den Tokenendpunkt gesendet, den Sie mithilfe des Metadatenwerts token_endpoint
aus dem Discovery-Dokument 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 Text POST
enthalten:
Felder | |
---|---|
code |
Der Autorisierungscode, der von der ursprünglichen Anfrage zurückgegeben wurde. |
client_id |
Die Client-ID, die du von API ConsoleCredentials pageerhältst, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben. |
client_secret |
Den Clientschlüssel, den du aus API ConsoleCredentials pageerhältst, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben. |
redirect_uri |
Ein autorisierter Weiterleitungs-URI für die angegebene client_id im Credentials pageder API Console, wie unter Weiterleitungs-URI festlegen beschrieben. |
grant_type |
Dieses Feld muss den Wert 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 mit Identitätsinformationen zum Nutzer, die von Google digital signiert sind. |
scope |
Der von access_token gewährte Zugriffsbereich, ausgedrückt als Liste von Strings, bei denen die Leerzeichen durch Leerzeichen getrennt sind. |
token_type |
Gibt den zurückgegebenen Tokentyp 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-Webtoken), also ein kryptografisch signiertes Base64-codiertes JSON-Objekt. Normalerweise ist es wichtig, dass Sie ein ID-Token vor der Verwendung validieren. Da Sie jedoch direkt über einen zwischengeschalteten HTTPS-Kanal mit Google kommunizieren und sich mit Ihrem Clientschlüssel bei Google authentifizieren, können Sie sicher sein, dass das Token, das Sie erhalten, tatsächlich von Google stammt und gültig ist. Wenn Ihr Server das ID-Token an andere Komponenten Ihrer Anwendung weitergibt, ist es sehr wichtig, dass die anderen Komponenten das Token validieren, bevor Sie es verwenden.
Da die meisten API-Bibliotheken die Validierung mit der Decodierung der base64url-codierten Werte und der darin enthaltenen JSON-Datei kombinieren, werden Sie wahrscheinlich das Token validieren, wenn Sie die Anforderungen im ID-Token aufrufen.
Nutzlast eines ID-Tokens
Ein ID-Token ist ein JSON-Objekt mit einer Reihe von Name/Wert-Paaren. Hier ein Beispiel zur besseren Lesbarkeit:
{ "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 enthalten (sogenannte claims):
Anspruch erheben | Bereitgestellt | Beschreibung |
---|---|---|
aud |
immer | Die Zielgruppe, für die dieses ID-Token bestimmt ist. Dies muss eine der OAuth 2.0-Client-IDs Ihrer Anwendung sein. |
exp |
immer | Ablaufzeit, ab dem das ID-Token nicht akzeptiert werden darf. Wird in Unix-Zeit (ganzzahlige Sekunden) dargestellt. |
iat |
immer | Der Zeitpunkt, zu dem das ID-Token ausgestellt wurde. Wird in Unix-Zeit (ganzzahlige Sekunden) dargestellt. |
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 unter allen Google-Konten eindeutig ist und nie wiederverwendet wird. Ein Google-Konto kann mehrere E-Mail-Adressen zu verschiedenen Zeitpunkten haben. Der sub -Wert bleibt jedoch unverändert. Verwende sub in deiner Anwendung als eindeutige Kennung für den Nutzer. Maximale Länge von 255 ASCII-Zeichen, bei denen Groß- und Kleinschreibung berücksichtigt wird. |
at_hash |
Zugriffstoken-Hash. Validierung, dass das Zugriffstoken an das Identitätstoken gebunden ist. Wenn das ID-Token im Serverablauf mit einem access_token -Wert ausgegeben wird, ist diese Anforderung immer enthalten. Diese Anforderung kann als alternativer Mechanismus zum Schutz vor websiteübergreifenden Anfragefälschungsangriffen verwendet werden. Wenn Sie jedoch Schritt 1 und Schritt 3 ausführen, ist es nicht erforderlich, das Zugriffstoken zu überprüfen. |
|
azp |
Die client_id des autorisierten Moderators. Diese Anforderung ist nur erforderlich, wenn die Partei, die das ID-Token anfordert, nicht mit der Zielgruppe des ID-Tokens übereinstimmt. Dies ist beispielsweise bei Hybrid-Apps der Fall, wenn eine Webanwendung und eine Android-App ein anderes OAuth 2.0-client_id haben, aber dasselbe Google APIs-Projekt nutzen. |
|
email |
Die E-Mail-Adresse des Nutzers. Dieser Wert ist möglicherweise nicht eindeutig für diesen Nutzer und kann nicht als Primärschlüssel verwendet werden. Nur angegeben, wenn Ihr Bereich den Bereichswert email enthält. |
|
email_verified |
Dieser Wert ist „True“, wenn die E-Mail-Adresse des Nutzers bestätigt wurde, andernfalls „False“. | |
family_name |
Nachname(n) des Nutzers Kann angegeben werden, wenn ein name -Anspruch vorhanden ist. |
|
given_name |
Der Vorname oder der Vorname des Nutzers. Kann angegeben werden, wenn ein name -Anspruch vorhanden ist. |
|
hd |
Die mit der Google Cloud-Organisation des Nutzers verknüpfte Domain. Nur angegeben, wenn der Nutzer einer Google Cloud-Organisation gehört. | |
locale |
Die Sprache des Nutzers, dargestellt durch ein BCP 47-Sprachtag.
Kann angegeben werden, wenn ein name -Anspruch vorhanden ist. |
|
name |
Der vollständige Name des Nutzers in einem Format, das angezeigt werden kann. Kann angegeben werden, wenn:
Wenn |
|
nonce |
Der Wert von nonce , der von Ihrer App in der Authentifizierungsanfrage angegeben wurde.
Sie sollten den Schutz vor Wiederholungsangriffen durchsetzen, indem Sie sicherstellen, dass er nur einmal präsentiert wird. |
|
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, wenn alle Anmeldeanforderungen von der Google API-Antwort erfüllt werden.
Wenn der Nutzer nicht in Ihrer Nutzerdatenbank vorhanden ist, sollten Sie den Nutzer zu Ihrem Registrierungsvorgang für neue Nutzer weiterleiten. Möglicherweise können Sie den Nutzer anhand der Informationen, die Sie von Google erhalten, automatisch registrieren. Es ist aber auch möglich, dass Sie viele der Felder, die Sie für Ihr Anmeldeformular benötigen, vorab ausfüllen. Zusätzlich zu den Informationen im ID-Token können Sie an unseren Endpunkten weitere Nutzerprofilinformationen abrufen.
Themen für Fortgeschrittene
In den folgenden Abschnitten wird die Google OAuth 2.0 API ausführlicher beschrieben. Diese Informationen richten sich an Entwickler mit erweiterten Anforderungen an Authentifizierung und Autorisierung.
Zugriff auf andere Google APIs
Einer der Vorteile von OAuth 2.0 für die Authentifizierung besteht darin, dass deine Anwendung während der Authentifizierung des Nutzers die Berechtigung erhält, andere Google APIs im Namen des Nutzers (z. B. YouTube, Google Drive, Google Kalender oder Kontakte) gleichzeitig zu verwenden. Fügen Sie dazu die anderen benötigten Bereiche in die Authentifizierungsanfrage ein, die Sie an Google senden. Wenn Sie der Authentifizierungsanfrage beispielsweise die Altersgruppe des Nutzers hinzufügen 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 zurückerhalten, können Sie auf alle APIs zugreifen, die mit den angeforderten und den erteilten Zugriffsbereichen in Zusammenhang stehen.
Aktualisierungstokens
In Ihrer Anfrage für den API-Zugriff können Sie ein Aktualisierungstoken anfordern, das während des code
-Austauschs zurückgegeben wird. Ein Aktualisierungstoken bietet Ihrer Anwendung dauerhaft Zugriff auf Google APIs, während der Nutzer nicht in Ihrer Anwendung vorhanden ist. Wenn Sie ein Aktualisierungstoken anfordern möchten, fügen Sie den Parameter access_type
in der Authentifizierungsanfrage auf offline
ein.
Wichtige Hinweise:
- Bewahren Sie das Aktualisierungstoken sicher und dauerhaft auf, da Sie ein Aktualisierungstoken nur beim ersten Ausführen des Codeaustauschs erhalten können.
- Die Anzahl der ausgegebenen Aktualisierungstokens ist begrenzt: ein Limit pro Client/Nutzer-Kombination und ein weiteres pro Nutzer für alle Clients. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, können diese Limits erreicht werden. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.
Weitere Informationen finden Sie unter Zugriffstoken aktualisieren (Offlinezugriff).
Aufforderung zur erneuten Einwilligung
Sie können den Nutzer auffordern, Ihre Anwendung noch einmal zu autorisieren. Dazu setzen Sie den Parameter prompt
in Ihrer Authentifizierungsanfrage auf consent
. Wenn prompt=consent
enthalten ist, wird der Zustimmungsbildschirm jedes Mal angezeigt, wenn Ihre Anwendung die Autorisierung von Zugriffsbereichen anfordert, auch wenn alle Bereiche zuvor Ihrem Google APIs-Projekt gewährt wurden. Füge daher nur bei Bedarf prompt=consent
ein.
Weitere Informationen zum Parameter prompt
finden Sie in der Tabelle Authentifizierungs-URI-Parameter unter prompt
.
Authentifizierungs-URI-Parameter
Die folgende Tabelle enthält ausführlichere Beschreibungen der Parameter, die von der OAuth 2.0 Authentication API von Google akzeptiert werden.
Parameter | Erforderlich | Beschreibung |
---|---|---|
client_id |
(Erforderlich) | Der Client-ID-String, den du aus API ConsoleCredentials pageerhältst, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben. |
nonce |
(Erforderlich) | Ein zufälliger Wert, der von Ihrer App generiert wird und den Replay-Schutz aktiviert. |
response_type |
(Erforderlich) | Wenn der Wert code ist, wird ein Ablauf mit grundlegendem Autorisierungscode gestartet. Dabei muss POST an den Tokenendpunkt gesendet werden, um die Tokens zu erhalten. Wenn der Wert token id_token oder id_token token ist, wird ein Impliziter Ablauf gestartet. Dabei muss JavaScript beim Weiterleitungs-URI verwendet werden, um Tokens aus der URI #fragment -Kennung 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 im API Console- Credentials page festgelegt haben (einschließlich HTTP- oder HTTPS-Schema, Fall und nachgestelltem „/“, falls vorhanden). |
scope |
(Erforderlich) | Der Umfangsparameter muss mit dem Wert Wenn der Bereichswert Wenn der Bereichswert Neben diesen OpenID-spezifischen Bereichen kann Ihr Bereichsargument auch andere Bereichswerte enthalten. Alle Bereichswerte müssen durch Leerzeichen getrennt sein. Wenn Sie beispielsweise pro Dateizugriff auf das Google Drive-Konto eines Nutzers zugreifen möchten, könnte der Bereichsparameter Informationen zu verfügbaren Bereichen finden Sie unter OAuth 2.0-Bereiche für Google APIs oder in der Dokumentation für die Google API, die Sie verwenden möchten. |
state |
(Optional, aber sehr empfehlenswert) | Ein intransparenter String, der im Protokoll einen Round-Trip enthält, d. h., er wird als URI-Parameter im einfachen Ablauf und in der URI-ID Die |
access_type |
(Optional) | Zulässige Werte sind offline und online . Der Effekt ist unter Offlinezugriff dokumentiert. Wenn ein Zugriffstoken angefordert wird, erhält der Client nur dann ein Aktualisierungstoken, wenn der Wert offline angegeben ist. |
display |
(Optional) | Ein ASCII-Stringwert, der angibt, wie der Autorisierungsserver die Authentifizierungs- und Einwilligungsseiten anzeigt. Die folgenden Werte werden von den Google-Servern angegeben und akzeptiert, haben aber keinen Einfluss auf ihr Verhalten: page , popup , touch und wap . |
hd |
(Optional) | Die Anmeldung von Konten einer Google Cloud-Organisation optimieren. Durch das Einbinden der Google Cloud-Organisationsdomain (z. B. mycollege.edu) können Sie angeben, dass die UI für die Kontoauswahl für Konten in dieser Domain optimiert werden soll. Wenn Sie die Optimierung für Google Cloud-Organisationskonten statt nur einer Google Cloud-Organisationsdomain vornehmen möchten, legen Sie einen Sternchenwert ( Verlassen Sie sich nicht auf diese UI-Optimierung, um zu steuern, wer auf Ihre Anwendung zugreifen kann, da clientseitige Anfragen geändert werden können. Prüfen Sie unbedingt, ob das zurückgegebene ID-Token einen |
include_granted_scopes |
(Optional) | Wenn für diesen Parameter der Wert true angegeben ist und die Autorisierungsanfrage genehmigt wurde, umfasst die Autorisierung alle vorherigen Autorisierungen, die dieser Kombination aus Nutzer und Anwendung für andere Bereiche zugewiesen wurden. Weitere Informationen finden Sie unter Inkrementelle Autorisierung.
Beachten Sie, dass Sie mit dem Ablauf für installierte Anwendungen keine inkrementelle Autorisierung durchführen können. |
login_hint |
(Optional) | Wenn die Anwendung weiß, welchen Nutzer sie authentifizieren möchte, kann sie den Parameter als Hinweis für den Authentifizierungsserver bereitstellen. Wenn Sie diesen Hinweis weitergeben, wird die Kontoauswahl unterdrückt und das E-Mail-Feld auf dem Anmeldeformular vorausgefüllt oder die richtige Sitzung ausgewählt (wenn der Nutzer die Mehrfachanmeldung verwendet). So können Sie Probleme vermeiden, die auftreten, wenn Ihre Anwendung im falschen Nutzerkonto angemeldet ist.
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 zur Einwilligung auffordert. Mögliche Werte sind:
Wenn kein Wert angegeben ist und der Nutzer zuvor keinen autorisierten Zugriff hat, wird dem Nutzer ein Zustimmungsbildschirm angezeigt. |
ID-Token prüfen
Du musst alle ID-Tokens auf deinem Server validieren, es sei denn, du weißt, dass sie direkt von Google stammen. Beispielsweise muss Ihr Server alle von Ihren Clientanwendungen empfangenen ID-Tokens als echt bestätigen.
In den folgenden Fällen senden Sie ID-Tokens häufig an Ihren Server:
- ID-Tokens mit Anfragen senden, die authentifiziert werden müssen Die ID-Tokens teilen Ihnen mit, welcher Nutzer die Anfrage gesendet hat und welchem Client dieses ID-Token zugewiesen wurde.
ID-Tokens sind vertraulich und können missbraucht werden, wenn sie abgefangen werden. Sie müssen für eine sichere Verarbeitung dieser Tokens sorgen, indem Sie sie nur über HTTPS und nur über POST-Daten oder in Anfrageheadern übertragen. Wenn Sie ID-Tokens auf Ihrem Server speichern, müssen Sie sie ebenfalls sicher speichern.
Hilfreiche ID-Tokens sind unter anderem, dass sie an verschiedene Komponenten Ihrer Anwendung weitergegeben werden können. Diese Komponenten können ein ID-Token als einfachen Authentifizierungsmechanismus verwenden, mit dem die Anwendung und der Nutzer authentifiziert werden. Bevor Sie die Informationen im ID-Token verwenden oder sich darauf verlassen können, dass der Nutzer authentifiziert wurde, müssen Sie ihn validieren.
Die Validierung eines ID-Tokens erfordert mehrere Schritte:
- Prüfen Sie, ob das ID-Token vom Aussteller ordnungsgemäß signiert ist. Von Google ausgestellte Tokens werden mit einem der Zertifikate signiert, die unter dem im
jwks_uri
-Metadatenwert des Discovery-Dokuments angegebenen URI gefunden werden. - Prüfe, ob der Wert der
iss
-Anforderung im ID-Token dem Werthttps://accounts.google.com
oderaccounts.google.com
entspricht. - Prüfe, ob der Wert der
aud
-Anforderung im ID-Token mit der Client-ID deiner App übereinstimmt. - Achten Sie darauf, dass die Ablaufzeit (
exp
-Anforderung) des ID-Tokens nicht abgelaufen ist. - Wenn Sie in der Anfrage einen hd-Parameterwert angegeben haben, prüfen Sie, ob das ID-Token eine
hd
-Anforderung hat, die einer akzeptierten Domain entspricht, die mit einer Google Cloud-Organisation verknüpft ist.
In den Schritten 2 bis 5 werden nur String- und Datumsvergleiche vorgenommen, die ziemlich einfach sind. Daher werden sie hier nicht beschrieben.
Der erste Schritt ist komplexer und umfasst eine kryptografische Signaturprüfung. Zum Debugging können Sie den tokeninfo
-Endpunkt von Google verwenden, um einen Vergleich mit der lokalen Verarbeitung durchzuführen, die auf Ihrem Server oder Gerät implementiert ist. Angenommen, der Wert des ID-Tokens lautet XYZ123
. Dann entfernen Sie den URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123
. Wenn die Tokensignatur gültig ist, ist die Antwort die JWT-Nutzlast in ihrer decodierten JSON-Objektform.
Der Endpunkt tokeninfo
ist nützlich für die Fehlerbehebung. Für Produktionszwecke sollten Sie jedoch die öffentlichen Schlüssel von Google aus dem Schlüsselendpunkt abrufen und die Validierung lokal ausführen. Sie sollten den Schlüssel-URI aus dem Discovery-Dokument mithilfe des Metadatenwerts jwks_uri
abrufen. Anfragen an den Debugging-Endpunkt können gedrosselt werden oder auf andere Weise zeitweise Fehler verursachen.
Da Google seine öffentlichen Schlüssel nur selten ändert, können Sie diese mit den Cache-Anweisungen der HTTP-Antwort im Cache speichern. In den meisten Fällen ist eine lokale Validierung viel effizienter als mit dem Endpunkt tokeninfo
. Diese Validierung erfordert das Abrufen und Parsen von Zertifikaten und das Ausführen der entsprechenden kryptografischen Aufrufe zum Prüfen der Signatur. Glücklicherweise stehen in diesem Zusammenhang Bibliotheken mit vielen Fehlern und verschiedenen Sprachen zur Verfügung. Weitere Informationen finden Sie unter jwt.io.
Nutzerprofilinformationen abrufen
Sie können das Zugriffstoken (das Ihre Anwendung während des Authentifizierungsvorgangs) und den OpenID Connect-Standard verwendet, um zusätzliche Profilinformationen zum Nutzer zu erhalten:
Damit die OpenID-konform ist, müssen Sie die
openid profile
-Bereichswerte in Ihre Authentifizierungsanfrage aufnehmen.Wenn die E-Mail-Adresse des Nutzers enthalten sein soll, können Sie einen zusätzlichen Bereichswert von
email
angeben. Wenn Sie sowohlprofile
als auchemail
angeben möchten, können Sie den folgenden Parameter in den URI für die Authentifizierungsanfrage einfügen:scope=openid%20profile%20email
- Fügen Sie dem Autorisierungsheader Ihr Zugriffstoken hinzu und stellen Sie eine HTTPS-
GET
-Anfrage an den Endpunkt „userinfo“. Diesen sollten Sie mit dem Metadatenwertuserinfo_endpoint
aus dem Discovery-Dokument abrufen. Die Nutzerinfo-Antwort enthält Informationen über den Nutzer, wie inOpenID Connect Standard Claims
und imclaims_supported
-Metadatenwert des Discovery-Dokuments beschrieben. Nutzer oder ihre Organisationen können bestimmte Felder angeben oder zurückhalten, sodass Sie möglicherweise nicht für jedes Feld Informationen zu Ihren autorisierten Zugriffsbereichen erhalten.
Das Discovery-Dokument
Für das OpenID Connect-Protokoll müssen mehrere Endpunkte zur Authentifizierung von Nutzern und zum Anfordern von Ressourcen wie Tokens, Nutzerinformationen und öffentlichen Schlüsseln verwendet werden.
Um die Implementierung zu vereinfachen und die Flexibilität zu erhöhen, ermöglicht OpenID Connect die Verwendung eines „Discovery-Dokuments“, eines JSON-Dokuments an einem bekannten Speicherort mit Schlüssel/Wert-Paaren, das Details zur Konfiguration des OpenID Connect-Anbieters enthält, einschließlich der URIs der Endpunkte für Autorisierung, Token, Widerruf, Nutzerinformationen und öffentliche Schlüssel. Das Discovery-Dokument für den OpenID Connect-Dienst von Google kann hier abgerufen werden:
https://accounts.google.com/.well-known/openid-configuration
Wenn Sie die OpenID Connect-Dienste von Google verwenden möchten, sollten Sie den Discovery-Dokument-URI (https://accounts.google.com/.well-known/openid-configuration
) in Ihrer Anwendung hartcodieren.
Ihre Anwendung ruft das Dokument ab, wendet Caching-Regeln in der Antwort an und ruft dann nach Bedarf Endpunkt-URIs ab. Zum Beispiel würde der Code zum Authentifizieren eines Nutzers den Metadatenwert authorization_endpoint
(im Beispiel unten https://accounts.google.com/o/oauth2/v2/auth
) als Basis-URI für Authentifizierungsanfragen abrufen, die an Google gesendet werden.
Hier ein Beispiel für ein solches Dokument. Die Feldnamen sind in OpenID Connect Discovery 1.0 angegeben. Die Werte dienen nur der Veranschaulichung und können sich ändern, obwohl sie aus einer aktuellen Version des aktuellen Google Discovery-Dokuments kopiert wurden:
{ "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" ] }
Möglicherweise können Sie einen HTTP-Roundtrip vermeiden, indem Sie die Werte aus dem Discovery-Dokument im Cache speichern. Standard-HTTP-Caching-Header werden verwendet und sollten beachtet werden.
Clientbibliotheken
Die folgenden Clientbibliotheken vereinfachen die Implementierung von OAuth 2.0 durch die Einbindung in gängige Frameworks:
OpenID Connect-Compliance
Das OAuth 2.0-Authentifizierungssystem von Google unterstützt die erforderlichen Funktionen der Spezifikation OpenID Connect Core. Jeder Client, der für die Verwendung mit OpenID Connect entwickelt wurde, sollte mit diesem Dienst kompatibel sein (mit Ausnahme des OpenID-Anfrageobjekts).