Die OAuth 2.0 APIs von Google können sowohl zur Authentifizierung als auch zur 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 dieses Protokoll interaktiv untersuchen möchten, empfehlen wir den Google OAuth 2.0 Playground. Wenn Sie Hilfe zu Stack Overflow benötigen, taggen Sie Ihre Fragen mit „google-oauth“.
OAuth 2.0 einrichten
Bevor deine Anwendung das OAuth 2.0-Authentifizierungssystem von Google für die Nutzeranmeldung verwenden kann, musst du ein Projekt im Google API Console einrichten, um OAuth 2.0-Anmeldedaten abzurufen, einen Weiterleitungs-URI festzulegen und (optional) die Branding-Informationen anzupassen, die deinen Nutzern auf dem Bildschirm für die Nutzereinwilligung angezeigt werden. Sie können mit dem API Console auch ein Dienstkonto erstellen, die Abrechnung aktivieren, die Filterung einrichten und andere Aufgaben ausführen. 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 den 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
Die OAuth 2.0-Authentifizierung bietet Nutzern einen Zustimmungsbildschirm, in dem die Informationen beschrieben werden, die der Nutzer freigibt, sowie die geltenden Nutzungsbedingungen. Wenn sich der Nutzer anmeldet, wird er beispielsweise aufgefordert, Ihrer App Zugriff auf seine E-Mail-Adresse und grundlegende Kontoinformationen zu gewähren. Mit dem Parameter scope fordern Sie Zugriff auf diese Informationen an. Diesen Parameter nehmen Sie in die Authentifizierungsanfrage Ihrer App auf. Sie können mit Bereichen auch den Zugriff auf andere Google APIs anfordern.
Der Zustimmungsbildschirm für den Nutzer enthält auch Markeninformationen wie deinen Produktnamen, dein Logo und eine Startseiten-URL. Du verwaltest die Branding-Informationen in den API Console.
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 .
Der folgende Dialog zur Einholung von Einwilligungen zeigt, was ein Nutzer sehen würde, wenn in der Anfrage eine Kombination aus OAuth 2.0- und Google Drive-Bereichen vorhanden ist. (Dieses generische Dialogfeld wurde mit Google OAuth 2.0 Playground erstellt. Es enthält also keine Branding-Informationen, die in API Consolefestgelegt werden.)
Auf den Dienst zugreifen
Google und Drittanbieter stellen Bibliotheken zur Verfügung, mit denen Sie viele Implementierungsdetails zur Authentifizierung von Nutzern und zum Zugriff auf Google APIs erledigen können. Beispiele hierfür sind 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 restlichen Dokument, in der die HTTP-Anfrageabläufe 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 Standardfunktion von OpenID Connect, mit der Identitätsprüfungen im Internet geteilt werden können.
Die am häufigsten verwendeten Ansätze zum Authentifizieren eines Nutzers und zum Abrufen eines ID-Tokens werden als „Serverfluss“ und „impliziter“ Ablauf bezeichnet. Über den Serverfluss kann der Back-End-Server einer Anwendung die Identität der Person mit einem Browser oder Mobilgerät überprüfen. Der implizite Vorgang wird verwendet, wenn eine clientseitige Anwendung (in der Regel eine JavaScript-Anwendung, die im Browser ausgeführt wird) direkt auf APIs zugreifen muss, anstatt über den Back-End-Server.
In diesem Dokument wird beschrieben, wie der Serverfluss zur Authentifizierung des Nutzers ausgeführt wird. Der implizite Ablauf ist aufgrund der Sicherheitsrisiken bei der Verwaltung 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
Achten Sie darauf, die Anwendung im API Console einzurichten, damit sie diese Protokolle verwenden und Ihre Nutzer authentifizieren kann. Wenn ein Nutzer versucht, sich über Google anzumelden, müssen Sie Folgendes tun:
- Anti-Fälschung-Token erstellen
- Authentifizierungsanfrage an Google senden
- Token für die Fälschungsstatus bestätigen
- Exchange
codegegen Zugriffstoken und ID-Token - Nutzerinformationen aus dem ID-Token abrufen
- Nutzer authentifizieren
1) Anti-Fälschung-Token erstellen
Schützen Sie die Sicherheit Ihrer Nutzer, indem Sie Fälschungsangriffe verhindern. Im ersten Schritt wird ein eindeutiges Sitzungstoken erstellt, das den Status zwischen der Anwendung und dem Client des Nutzers hält. Sie gleichen dieses eindeutige Sitzungstokens später mit der Authentifizierungsantwort ab, die vom Google OAuth-Anmeldedienst zurückgegeben wird, um zu prüfen, ob 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 Statustoken ist ein String mit je 30 Zeichen, der mit einem hochwertigen Zufallsgenerator erstellt wird. Ein weiterer Hash, der durch das Signieren einiger Ihrer Sitzungsstatusvariablen mit einem Schlüssel generiert wird, der im Back-End geheim gehalten wird.
Im folgenden Code sehen Sie, wie eindeutige Sitzungstokens generiert werden.
PHP
Damit Sie dieses Beispiel verwenden können, müssen Sie die Google APIs-Clientbibliothek für PHP herunterladen.
// 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 zu verwenden.
// 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
Damit Sie dieses Beispiel verwenden können, müssen Sie die Google APIs-Clientbibliothek für Python herunterladen.
# 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 GET-HTTPS-Anfrage mit den entsprechenden URI-Parametern erstellt.
Bei allen Schritten dieses Vorgangs solltest du HTTPS statt HTTP verwenden. HTTP-Verbindungen werden abgelehnt. Sie sollten den Basis-URI mit dem Metadatenwert authorization_endpoint aus dem Discovery-Dokument abrufen. In der folgenden Diskussion wird davon ausgegangen, dass der Basis-URI https://accounts.google.com/o/oauth2/v2/auth ist.
Für eine grundlegende Anfrage geben Sie die folgenden Parameter an:
client_id, die Sie über API Console Credentials pageabrufen.response_type, der in einer grundlegenden Autorisierungscode-Anfragecodelauten sollte. Weitere Informationen finden Sie unterresponse_type.scope, was in einer grundlegenden Anfrageopenid emaillauten sollte. Weitere Informationen finden Sie unterscope.redirect_urisollte der HTTP-Endpunkt auf deinem Server sein, der die Antwort von Google erhält. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie in API Console Credentials pagekonfiguriert haben. Wenn dieser Wert nicht mit einem autorisierten URI übereinstimmt, schlägt die Anfrage mit dem Fehlerredirect_uri_mismatchfehl.statesollte den Wert des eindeutigen Fälschungstokens für die Sitzung 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.nonceist ein zufälliger Wert, der von Ihrer App generiert wird und den Wiederholungsschutz aktiviert, falls vorhanden.login_hintkann die E-Mail-Adresse des Nutzers oder der Stringsubsein, der der Google-ID des Nutzers entspricht. Wenn Sie keinlogin_hintangeben und der Nutzer aktuell angemeldet ist, enthält der Zustimmungsbildschirm eine Genehmigungsanfrage, um die E-Mail-Adresse des Nutzers für Ihre App freizugeben. Weitere Informationen finden Sie unterlogin_hint.- Verwenden Sie den Parameter
hd, um den OpenID Connect-Vorgang für Nutzer einer bestimmten Domain zu optimieren, die mit einer Google Cloud-Organisation verknüpft sind. Weitere Informationen finden Sie unterhd.
Hier ist ein Beispiel für einen vollständigen URI der OpenID Connect-Authentifizierung 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
Die 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 des Fälschungsstatus bestätigen
Die Antwort wird an die redirect_uri gesendet, die du in der Anfrage angegeben hast. Alle Antworten werden wie unten gezeigt 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 in Schritt 1 erstellten Sitzungstoken übereinstimmt. Mit dieser Umlaufbestätigung wird sichergestellt, dass der Nutzer kein schädliches Skript sendet.
Im folgenden Code sehen Sie, wie Sie die in Schritt 1 erstellten Sitzungstokens bestätigen:
PHP
Damit Sie dieses Beispiel verwenden können, müssen Sie die Google APIs-Clientbibliothek für PHP herunterladen.
// 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 zu verwenden.
// 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
Damit Sie dieses Beispiel verwenden können, müssen Sie die Google APIs-Clientbibliothek für Python herunterladen.
# 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. Exchange code gegen Zugriffstoken und ID-Token
Die Antwort enthält einen code-Parameter, einen einmaligen Autorisierungscode, den Ihr Server gegen ein Zugriffstoken und ein ID-Token austauschen kann. Ihr Server nimmt diesen Austausch über eine HTTPS-POST-Anfrage vor. 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 von POST enthalten:
| Felder | |
|---|---|
code |
Der Autorisierungscode, der von der ursprünglichen Anfrage zurückgegeben wird. |
client_id |
Die Client-ID, die du von API Console Credentials pageerhältst, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben. |
client_secret |
Der Clientschlüssel, den du aus API Console Credentials pageerhältst, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben. |
redirect_uri |
Ein autorisierter Weiterleitungs-URI für den jeweiligen client_id, der in der API Console
Credentials pageangegeben ist, wie unter Weiterleitungs-URI festlegen beschrieben. |
grant_type |
Dieses Feld muss den Wert authorization_code
wie in der OAuth 2.0-Spezifikation definiert enthalten. |
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 als Liste durch Leerzeichen getrennter Groß-/Kleinschreibung-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 |
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 du ein ID-Token vor deiner Verwendung prüfst. Da du jedoch direkt mit Google über einen HTTPS-Kanal zwischengeschaltet wirst und deinen Clientschlüssel zur Authentifizierung bei Google verwendest, kannst du sicher sein, dass das Token, das du erhältst, tatsächlich von Google stammt und gültig ist. Wenn dein Server das ID-Token an andere Komponenten deiner App weitergibt, ist es sehr wichtig, dass die anderen Komponenten das Token validieren, bevor du es verwendest.
Die meisten API-Bibliotheken kombinieren die Validierung mit der Decodierung der base64url-codierten Werte und dem Parsen des JSON-Codes. Deshalb müssen Sie wahrscheinlich das Token trotzdem validieren, wenn Sie auf die Anforderungen im ID-Token zugreifen.
Die Nutzlast eines ID-Tokens
Ein ID-Token ist ein JSON-Objekt, das eine Reihe von Name/Wert-Paaren enthält. Hier ein Beispiel zur 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 am oder nach dem ID-Token. Wird in Unix-Zeit (ganzzahlige Sekunden) dargestellt. |
iat |
immer | Der Zeitpunkt, an dem das ID-Token ausgestellt wurde. Wird in Unix-Zeit (ganzzahlige Sekunden) dargestellt. |
iss |
immer | Die Aussteller-ID für den Aussteller der Antwort. Für Google-ID-Tokens immer https://accounts.google.com oder accounts.google.com. |
sub |
immer | Eine Kennung für den Nutzer, die unter allen Google-Konten eindeutig ist und nie wiederverwendet wird. Ein Google-Konto kann zu verschiedenen Zeitpunkten mehrere E-Mail-Adressen haben. Der sub-Wert wird jedoch nie geändert. Verwenden Sie sub in Ihrer Anwendung als eindeutigen Kennungsschlüssel für den Nutzer. Maximale Länge von 255 ASCII-Zeichen, bei denen die Groß- und Kleinschreibung berücksichtigt wird. |
at_hash |
Zugriffstoken eines Zugriffstokens Überprüft, ob das Zugriffstoken mit dem Identitätstoken verknüpft ist. Wenn das ID-Token im Serverablauf mit einem access_token-Wert ausgegeben wird, ist dieser Anspruch immer enthalten. Dieser Anspruch kann als alternativer Mechanismus zum Schutz vor websiteübergreifenden Anfragefälschungsangriffen verwendet werden. Wenn Sie jedoch Schritt 1 und Schritt 3 ausführen, ist das Zugriffstoken nicht zu bestätigen. |
|
azp |
client_id des autorisierten Vortragenden. Dieser Anspruch ist nur erforderlich, wenn die Partei, die das ID-Token anfordert, nicht mit der Zielgruppe des ID-Tokens übereinstimmt. Dies kann bei Google der Fall sein, 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 für diesen Nutzer nicht eindeutig und kann nicht als Primärschlüssel verwendet werden. Wird nur angegeben, wenn Ihr Bereich den Wert email für den Geltungsbereich enthält. |
|
email_verified |
Dieser Wert ist „true“, wenn die E-Mail-Adresse des Nutzers verifiziert wurde. Andernfalls lautet sie „false“. | |
family_name |
An- oder Nachnamen des Nutzers Kann angegeben werden, wenn ein name-Anspruch vorhanden ist. |
|
given_name |
Den Vornamen oder den Vornamen des Nutzers Kann angegeben werden, wenn ein name-Anspruch vorhanden ist. |
|
hd |
Die Domain, die der Google Cloud-Organisation des Nutzers zugeordnet ist. Wird nur angegeben, wenn der Nutzer einer Google Cloud-Organisation angehö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 einer anklickbaren Form. Kann in folgenden Fällen angegeben werden:
Wenn |
|
nonce |
Der Wert von nonce, der von Ihrer App in der Authentifizierungsanfrage bereitgestellt wird.
Sie sollten den Schutz vor Replay-Angriffen erzwingen, indem Sie dafür sorgen, dass sie nur einmal angezeigt werden. |
|
picture |
Die URL des Profilbilds des Nutzers. Kann in folgenden Fällen angegeben werden:
Wenn |
|
profile |
Die URL der Profilseite des Nutzers. Kann in folgenden Fällen angegeben werden:
Wenn |
6. Nutzer authentifizieren
Nachdem Sie die 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 durch die Google API-Antwort erfüllt sind.
Wenn der Nutzer nicht in deiner Nutzerdatenbank vorhanden ist, solltest du ihn zum Registrierungsvorgang für neue Nutzer weiterleiten. Du kannst den Nutzer möglicherweise anhand der von Google erhaltenen Informationen automatisch registrieren oder zumindest viele der Felder ausfüllen, die du im Anmeldeformular benötigst. Zusätzlich zu den Informationen im ID-Token erhalten Sie weitere Nutzerprofilinformationen an unseren Nutzerprofilendpunkten.
Themen für Fortgeschrittene
In den folgenden Abschnitten wird die Google OAuth 2.0 API ausführlicher beschrieben. Die folgenden Informationen richten sich an Entwickler mit erweiterten Anforderungen in Bezug auf Authentifizierung und Autorisierung.
Zugriff auf andere Google APIs
Einer der Vorteile von OAuth 2.0 für die Authentifizierung besteht darin, dass deine Anwendung zur Authentifizierung des Nutzers gleichzeitig die Berechtigung zur Nutzung anderer Google APIs (z. B. YouTube, Google Drive, Kalender oder Kontakte) erhalten kann. Fügen Sie dazu die erforderlichen Bereiche in die Authentifizierungsanfrage ein, die Sie an Google senden. Wenn Sie Ihrer Authentifizierungsanfrage beispielsweise die Altersgruppe des Nutzers hinzufügen möchten, übergeben Sie den Umfangsparameter 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, können Sie auf alle APIs zugreifen, die sich auf die angeforderten Bereiche beziehen und gewährt wurden.
Aktualisierungstokens
In Ihrem Antrag auf API-Zugriff können Sie die Aktualisierung eines Tokens beantragen, das während des code-Austauschs zurückgegeben wird. Mit einem Aktualisierungstoken kann Ihre Anwendung kontinuierlich auf Google APIs zugreifen, während der Nutzer in Ihrer Anwendung nicht vorhanden ist. Wenn Sie ein Aktualisierungstoken anfordern möchten, fügen Sie in Ihrer Authentifizierungsanfrage den Parameter access_type auf offline hinzu.
Wichtige Hinweise:
- Bewahren Sie das Aktualisierungstoken sicher und dauerhaft auf, da Sie ein Aktualisierungstoken nur dann erhalten, wenn Sie den Codeaustausch zum ersten Mal ausführen.
- Es gibt ein Limit für die Anzahl der Aktualisierungstokens: ein Limit pro Kombination aus Client und Nutzer und ein anderes pro Nutzer und alle Clients. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, kann das Limit 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 in Ihrer Authentifizierungsanfrage den Parameter prompt auf consent. Wenn prompt=consent enthalten ist, wird der Zustimmungsbildschirm immer dann angezeigt, wenn Ihre App die Autorisierung von Zugriffsbereichen anfordert, auch wenn alle Bereiche zuvor Ihrem Google APIs-Projekt gewährt wurden. Geben Sie daher nur bei Bedarf prompt=consent an.
Weitere Informationen zum Parameter prompt finden Sie unter prompt in der Tabelle Authentifizierungs-URI-Parameter.
Authentifizierungs-URI-Parameter
In der folgenden Tabelle finden Sie 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 von API Console Credentials 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 einfacher Autorisierungscode-Vorgang gestartet, der ein POST an den Tokenendpunkt erfordert, um die Tokens zu erhalten. Wenn der Wert token id_token oder id_token token lautet, wird ein Impliziter Ablauf gestartet. In diesem Fall müssen JavaScript im Weiterleitungs-URI verwendet werden, um Tokens aus der URI-ID #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 im API Console- Credentials page festlegen, einschließlich des HTTP- oder HTTPS-Schemas, der Groß-/Kleinschreibung und des nachfolgenden Schrägstrichs „/“ (falls vorhanden). |
scope |
(Erforderlich) | Der Umfangsparameter muss mit dem Wert Wenn der Wert für den Bereich Wenn der Bereichswert Zusätzlich zu diesen OpenID-spezifischen Bereichen kann Ihr Bereichsargument auch andere Bereichswerte enthalten. Alle Werte für den Bereich müssen durch Leerzeichen getrennt sein. Wenn Sie beispielsweise pro Datei Zugriff auf Google Drive eines Nutzers wünschen, kann Ihr Geltungsbereich-Parameter Informationen zu verfügbaren Bereichen finden Sie unter OAuth 2.0-Bereiche für Google APIs oder in der Dokumentation zur gewünschten Google API. |
state |
(Optional, aber dringend empfohlen) | Ein undurchsichtiger String, der im Protokoll als Roundtrip ausgegeben wird. Das heißt, er wird im einfachen Ablauf als URI-Parameter und im impliziten Ablauf als URI-ID Der |
access_type |
(Optional) | Die zulässigen 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, mit dem angegeben wird, wie der Autorisierungsserver die Seiten zur Authentifizierung und die Einwilligungsoberfläche anzeigt. Die folgenden Werte werden von den Google-Servern angegeben und akzeptiert, haben aber keinen Einfluss auf das Verhalten: page, popup, touch und wap. |
hd |
(Optional) | Die Anmeldung für Konten optimieren, die einer Google Cloud-Organisation gehören. Wenn Sie die Google Cloud-Organisationsdomain einschließen (z. B. mycollege.edu), können Sie angeben, dass die Kontoauswahl-UI für Konten in dieser Domain optimiert werden soll. Wenn Sie Optimierungen für Google Cloud-Organisationskonten statt nur für eine Google Cloud-Organisationsdomain vornehmen möchten, legen Sie einen Wert für ein Sternchen ( 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üfe, ob das zurückgegebene ID-Token einen Anspruchswert |
include_granted_scopes |
(Optional) | Wenn für diesen Parameter der Wert true angegeben wird und die Autorisierungsanfrage gewährt wurde, enthält die Autorisierung alle vorherigen Autorisierungen, die dieser Nutzer/Anwendungskombination für andere Bereiche gewährt 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 dem Parameter einen Hinweis auf den Authentifizierungsserver senden. Wenn Sie diesen Hinweis weitergeben, wird die Kontoauswahl unterdrückt und das E-Mail-Feld auf dem Anmeldeformular vorab ausgefüllt oder die richtige Sitzung ausgewählt (wenn der Nutzer die Mehrfachanmeldung verwendet). So können Sie Probleme vermeiden, die auftreten, wenn Ihre App im falschen Nutzerkonto protokolliert.
Der Wert kann entweder eine E-Mail-Adresse oder der String sub sein, der der Google-ID des Nutzers entspricht. |
prompt |
(Optional) | Eine Liste mit durch Leerzeichen getrennten Stringwerten, die angibt, ob der Autorisierungsserver den Nutzer zur erneuten Authentifizierung und zur Einwilligung auffordert. Folgende Werte sind möglich:
Wenn kein Wert angegeben ist und der Nutzer keinen zuvor 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 dein Server alle ID-Tokens, die er von deinen Client-Apps erhält, als authentisch bestätigen.
In den folgenden Fällen senden Sie ID-Tokens in der Regel an Ihren Server:
- Senden von ID-Tokens mit Anfragen, die authentifiziert werden müssen. Die ID-Tokens zeigen den jeweiligen Nutzer, der die Anfrage stellt, und für welchen Client dieses ID-Token ausgestellt wurde.
ID-Tokens sind vertraulich und können missbraucht werden, wenn sie abgefangen werden. Diese Tokens müssen sicher verarbeitet werden, indem sie nur über HTTPS und nur über POST-Daten oder in Anfrageheadern übertragen werden. Wenn Sie ID-Tokens auf Ihrem Server speichern, müssen Sie sie ebenfalls sicher speichern.
Ein wichtiger Vorteil von ID-Tokens ist, dass du sie zwischen verschiedenen Komponenten deiner App übergeben kannst. Diese Komponenten können ein ID-Token als einfachen Authentifizierungsmechanismus verwenden, mit dem die App und der Nutzer authentifiziert werden. Bevor Sie die Informationen jedoch im ID-Token verwenden oder sich darauf verlassen können, dass der Nutzer sich authentifiziert hat, müssen Sie sie validieren.
Das Bestätigen eines ID-Tokens erfordert mehrere Schritte:
- Prüfen Sie, ob das ID-Token vom Aussteller korrekt 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. - Der Wert der
iss-Anforderung im ID-Token muss mithttps://accounts.google.comoderaccounts.google.comübereinstimmen. - Überprüfe, ob der Wert der
aud-Anforderung im ID-Token mit der Client-ID deiner App übereinstimmt. - Achten Sie darauf, dass die Ablaufzeit (
expAnspruch) 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 mit einer akzeptierten Domain übereinstimmt, die mit einer Google Cloud-Organisation verknüpft ist.
In den Schritten 2 bis 5 werden nur Strings und Datumsangaben verglichen, die recht einfach sind. Wir gehen hier also nicht näher darauf ein.
Der erste Schritt ist komplexer und erfordert eine kryptografische Signaturprüfung. Für die Fehlerbehebung kannst du den tokeninfo-Endpunkt von Google verwenden, um sie mit der auf deinem Server oder deinem Gerät implementierten lokalen Verarbeitung zu vergleichen. Angenommen, der Wert des ID-Tokens ist XYZ123. Entfernen Sie dann 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 tokeninfo-Endpunkt ist für die Fehlerbehebung nützlich. Für Produktionszwecke sollten Sie jedoch die öffentlichen Google-Schlüssel 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 Debug-Endpunkt können gedrosselt werden oder in anderer Weise vorübergehenden Fehlern ausgesetzt werden.
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 eine effizientere lokale Validierung ausführen als mit dem Endpunkt tokeninfo. Für diese Validierung müssen Zertifikate abgerufen und geparst werden und es müssen die entsprechenden kryptografischen Aufrufe durchgeführt werden, um die Signatur zu prüfen. Glücklicherweise gibt es für das Debugging in vielen verschiedenen Sprachen Debugging-Bibliotheken (siehe jwt.io).
Nutzerprofilinformationen abrufen
Sie können das Zugriffstoken, das Ihre Anwendung während des Authentifizierungsvorgangs erhält, und den OpenID Connect-Standard verwenden, um zusätzliche Profilinformationen über den Nutzer zu erhalten:
Um OpenID-konform zu sein, müssen Sie in Ihre Authentifizierungsanfrage die Werte des Bereichs
openid profileaufnehmen.Wenn Sie die E-Mail-Adresse des Nutzers einschließen möchten, können Sie einen zusätzlichen Wert für den Umfang
emailangeben. Wenn Sie sowohlprofileals auchemailangeben möchten, können Sie den folgenden Parameter in den URI Ihrer Authentifizierungsanfrage einfügen:scope=openid%20profile%20email
- Fügen Sie dem Autorisierungsheader das Zugriffstoken hinzu und stellen Sie eine HTTPS-
GET-Anfrage an den Endpunkt des Nutzerinformationens. Diese sollten Sie aus dem Discovery-Dokument mit dem Metadatenwertuserinfo_endpointabrufen. Die Antwort „userinfo“ enthält Informationen zum Nutzer, wie inOpenID Connect Standard Claimsund demclaims_supported-Metadatenwert des Discovery-Dokuments beschrieben. Nutzer oder ihre Organisationen können bestimmte Felder bereitstellen oder zurückhalten, sodass Sie Informationen zu jedem Feld für Ihre autorisierten Zugriffsbereiche erhalten.
Das Discovery-Dokument
Für das OpenID Connect-Protokoll sind mehrere Endpunkte zur Authentifizierung von Nutzern und zum Anfordern von Ressourcen wie Tokens, Nutzerinformationen und öffentlichen Schlüsseln erforderlich.
Zur Vereinfachung der Implementierung und mehr Flexibilität erlaubt 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. Dazu gehören die 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 aus dem Dokument ab. Zur Authentifizierung eines Nutzers würde Ihr Code beispielsweise den Metadatenwert authorization_endpoint (https://accounts.google.com/o/oauth2/v2/auth im Beispiel unten) als Basis-URI für Authentifizierungsanfragen abrufen, 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. Informationen zu ihrer Bedeutung finden Sie in diesem Dokument. Die Werte dienen nur der Veranschaulichung und können sich ändern, obwohl sie aus einer aktuellen Version des eigentlichen 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 eine HTTP-Umleitung vermeiden, indem Sie die Werte aus dem Discovery-Dokument im Cache speichern. Es werden Standard-HTTP-Caching-Header verwendet und sollten eingehalten werden.
Clientbibliotheken
Mit den folgenden Clientbibliotheken ist die Implementierung von OAuth 2.0 durch die Einbindung in gängige Frameworks einfacher:
OpenID Connect-Compliance
Das OAuth 2.0-Authentifizierungssystem von Google unterstützt die erforderlichen Funktionen der Spezifikation OpenID Connect Core. Alle Clients, die für die Verwendung mit OpenID Connect entwickelt wurden, sollten mit diesem Dienst kompatibel sein (mit Ausnahme des OpenID-Anfrageobjekts).