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 Verwenden von OAuth 2.0 für den Zugriff auf Google APIs gilt auch für diesen Dienst. Wenn Sie dieses Protokoll interaktiv erkunden 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 in der Google Cloud Console ein Projekt einrichten, um OAuth 2.0-Anmeldedaten zu erhalten, einen Weiterleitungs-URI festzulegen und (optional) die Branding-Informationen anzupassen, die Ihre Nutzer auf dem Bildschirm für die Nutzereinwilligung sehen. Sie können die Cloud Console auch verwenden, um ein Dienstkonto zu erstellen, die Abrechnung zu aktivieren, Filter einzurichten und andere Aufgaben auszuführen. Weitere Informationen finden Sie in der Google Cloud 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 den Clientschlüssel für bestimmte OAuth 2.0-Anmeldedaten aufzurufen: Anmeldedaten auswählen. Wählen Sie im daraufhin angezeigten Fenster Ihr Projekt und den gewünschten Berechtigungsnachweis aus und klicken Sie dann auf Ansehen.
Alternativ können Sie Ihre Client-ID und Ihren Clientschlüssel in der Cloud Console auf der Seite „Clients“ aufrufen:
- Rufen Sie die Seite „Clients“ auf.
- Klicken Sie auf den Namen Ihres Kunden oder auf das Bearbeitungssymbol (create). Ihre Client-ID und Ihr Clientschlüssel werden oben auf der Seite angezeigt.
Weiterleitungs-URI festlegen
Der Weiterleitungs-URI, den Sie in der Cloud Console festlegen, bestimmt, wohin Google Antworten auf Ihre Authentifizierungsanfragen sendet.
So erstellen, rufen Sie die Weiterleitungs-URIs für bestimmte OAuth 2.0-Anmeldedaten auf oder bearbeiten sie:
- Rufen Sie die Seite „Clients“ auf.
- Klicken Sie auf den Kunden.
- Rufen Sie die Weiterleitungs-URIs auf oder bearbeiten Sie sie.
Wenn auf der Seite „Clients“ kein Client aufgeführt ist, hat Ihr Projekt keine OAuth-Anmeldedaten. Klicken Sie auf Client erstellen, um einen zu erstellen.
Zustimmungsbildschirm anpassen
Für Ihre Nutzer umfasst die OAuth 2.0-Authentifizierung einen Zustimmungsbildschirm, auf dem die Informationen, die der Nutzer freigibt, und die geltenden Bedingungen beschrieben werden. 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 den Zugriff auf diese Informationen mit dem Parameter scope an, den Ihre App in ihre Authentifizierungsanfrage einfügt. Sie können Bereiche auch verwenden, um Zugriff auf andere Google APIs anzufordern.
Auf dem Bildschirm für die Nutzereinwilligung werden auch Branding-Informationen wie der Produktname, das Logo und die URL der Startseite angezeigt. Sie können die Branding-Informationen in der Cloud Console verwalten.
So aktivieren Sie den Zustimmungsbildschirm Ihres Projekts:
- Öffnen Sie in der Google Cloud Console die Seite „Branding“.
- Wählen Sie ein Projekt aus oder erstellen Sie ein neues, wenn Sie dazu aufgefordert werden.
- Füllen Sie das Formular aus und klicken Sie auf Speichern.
Der folgende Dialog zur Einholung von Einwilligungen zeigt, was ein Nutzer sieht, wenn in der Anfrage eine Kombination aus OAuth 2.0- und Google Drive-Bereichen vorhanden ist. (Dieses allgemeine Dialogfeld wurde mit dem Google OAuth 2.0 Playground generiert und enthält daher keine Branding-Informationen, die in der Cloud Console festgelegt werden.)
Auf den Dienst zugreifen
Google und Drittanbieter stellen Bibliotheken bereit, mit denen Sie viele der Implementierungsdetails für die Authentifizierung von Nutzern und den Zugriff auf Google APIs abdecken 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 weiteren Verlauf dieses Dokuments. Dort werden die HTTP-Anfrageabläufe beschrieben, die den verfügbaren Bibliotheken zugrunde liegen.
Nutzer authentifizieren
Zur Authentifizierung des Nutzers muss ein ID-Token abgerufen und validiert werden. ID-Tokens sind ein standardisiertes Feature von OpenID Connect, das 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 sind der „Server“- und der „implizite“ Ablauf. Der Serverablauf ermöglicht es dem Backend-Server einer Anwendung, die Identität der Person zu überprüfen, die einen Browser oder ein Mobilgerät verwendet. Der implizite Ablauf wird verwendet, wenn eine clientseitige Anwendung (normalerweise eine JavaScript-Anwendung, die im Browser ausgeführt wird) direkt auf APIs zugreifen muss, anstatt ihren Backend-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 erheblich komplizierter. Wenn Sie einen impliziten Ablauf implementieren müssen, empfehlen wir dringend, Google Identity Services zu verwenden.
Serverablauf
Richten Sie Ihre App in der Cloud Console ein, 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älschungs-Statustoken erstellen
- Authentifizierungsanfrage an Google senden
- Anti-Fälschungs-Zustandstoken bestätigen
codegegen Zugriffstoken und ID-Token eintauschen- Nutzerinformationen aus dem ID-Token abrufen
- Nutzer authentifizieren
1. Anti-Fälschungs-Statustoken erstellen
Sie müssen die Sicherheit Ihrer Nutzer schützen, indem Sie Angriffe durch Anfragefälschung verhindern. Der erste Schritt besteht darin, ein eindeutiges Sitzungstoken zu erstellen, das den Status zwischen Ihrer App und dem Client des Nutzers speichert. Dieses eindeutige Sitzungstoken wird später mit der Authentifizierungsantwort des Google OAuth-Anmeldedienstes abgeglichen, um zu prüfen, ob die Anfrage vom Nutzer und nicht von einem böswilligen Angreifer stammt. Diese Tokens werden oft als Tokens für websiteübergreifende Anfragen (CSRF) bezeichnet.
Eine gute Wahl für ein Zustandstoken ist ein String mit etwa 30 Zeichen, der mit einem hochwertigen Zufallszahlengenerator erstellt wurde. Eine weitere Möglichkeit 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 zu verwenden.
// 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
Sie müssen die Google API-Clientbibliothek für Python herunterladen, um dieses Beispiel zu verwenden.
# 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 Erläuterung 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 in der Cloud Console auf der Seite „Clients“ finden.response_type, der in einer einfachen Autorisierungscode-Vorgangsanfragecodesein sollte. (Weitere Informationen unterresponse_type.)scope, der in einer einfachen Anfrageopenid emailsein sollte. (Weitere Informationen unterscope.)redirect_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 auf der Seite „Anmeldedaten“ der Cloud Console konfiguriert haben. Wenn dieser Wert nicht mit einem autorisierten URI übereinstimmt, schlägt die Anfrage mit dem Fehlerredirect_uri_mismatchfehl.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. (Weitere Informationen unterstate.)nonceist ein zufälliger Wert, der von Ihrer App generiert wird und bei Vorhandensein einen Replay-Schutz ermöglicht.login_hintkann die E-Mail-Adresse des Nutzers oder der Stringsubsein, der der Google-ID des Nutzers entspricht. Wenn Sie keinenlogin_hintangeben und der Nutzer angemeldet ist, enthält der Zustimmungsbildschirm eine Anfrage zur Genehmigung der Freigabe der E-Mail-Adresse des Nutzers für Ihre App. (Weitere Informationen finden Sie unterlogin_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. Weitere Informationen finden Sie unterhd.
Hier ist ein Beispiel für einen vollständigen OpenID Connect-Authentifizierungs-URI mit Zeilenumbrüchen und Leerzeichen zur besseren 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//developers.google.com/oauthplayground& 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 oder Kontozugriff anfordert, den sie zuvor nicht genehmigt haben.
3. Anti-Fälschungs-Zustandstoken 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://developers.google.com/oauthplayground?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
Gemäß RFC 6749 MÜSSEN Clients nicht erkannte Antwortparameter ignorieren. Auf dem Server müssen Sie bestätigen, dass das von Google empfangene state mit dem Sitzungstoken übereinstimmt, das Sie in Schritt 1 erstellt haben. Diese Hin- und Rückbestätigung hilft dabei, zu überprüfen, ob die Anfrage vom Nutzer und nicht von einem schädlichen Script 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 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->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
Sie müssen die Google API-Clientbibliothek für Python herunterladen, um dieses Beispiel zu verwenden.
# 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 den Parameter code, einen einmaligen Autorisierungscode, den Ihr Server gegen ein Zugriffstoken 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 mit dem Metadatenwert token_endpoint aus dem Discovery-Dokument abrufen sollten. In der folgenden Erläuterung wird davon ausgegangen, dass der Endpunkt https://oauth2.googleapis.com/token ist. Die Anfrage muss die folgenden Parameter im POST-Text enthalten:
| Felder | |
|---|---|
code |
Der Autorisierungscode, der von der ersten Anfrage zurückgegeben wird. |
client_id |
Die Client-ID, die Sie auf der Seite „Clients“ in der Cloud Console erhalten, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben. |
client_secret |
Der Clientschlüssel, den Sie auf der Seite „Clients“ der Cloud Console erhalten, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben. |
redirect_uri |
Ein autorisierter Weiterleitungs-URI für die angegebene client_id, die in der Cloud Console auf der Seite „Clients“ angegeben ist, 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 etwa 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//developers.google.com/oauthplayground& 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 zum Nutzer enthält, die von Google digital signiert wurden. |
scope |
Die Zugriffsbereiche, die vom access_token gewährt werden, ausgedrückt als Liste von durch Leerzeichen getrennten Strings, bei denen die Groß-/Kleinschreibung beachtet wird. |
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 Zwischenstation mit Google kommunizieren und sich mit Ihrem Clientschlüssel bei Google authentifizieren, können Sie sicher sein, dass das empfangene Token wirklich von Google stammt und gültig ist. Wenn Ihr Server das ID-Token an andere Komponenten Ihrer App weitergibt, ist es sehr wichtig, dass die anderen Komponenten das Token validieren, bevor sie es verwenden.
Da die meisten API-Bibliotheken die Validierung mit dem Decodieren der base64url-codierten Werte und dem Parsen des darin enthaltenen JSON kombinieren, werden Sie das Token wahrscheinlich ohnehin validieren, wenn Sie auf die Claims 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 ist 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 (auch als Ansprüche bezeichnet) enthalten:
| Anspruch | Bereitgestellt | Beschreibung |
|---|---|---|
aud |
immer | Die Zielgruppe, für die dieses ID-Token bestimmt ist. Es muss eine der OAuth 2.0-Client-IDs Ihrer Anwendung sein. |
exp |
immer | Ablaufzeit, nach der das ID-Token nicht mehr akzeptiert werden darf. Wird in Unix-Epochenzeit (ganzzahlige Sekunden) dargestellt. |
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 Identifikationsschlüssel für den Nutzer. Maximale Länge von 255 ASCII-Zeichen, bei denen die Groß-/Kleinschreibung berücksichtigt wird. |
amr |
Ein JSON-Array von Strings, die die Authentifizierungsmethoden identifizieren, die für die Anmeldung in einem Google-Konto verwendet werden. Falls vorhanden, enthält es einen oder mehrere dieser möglichen [IANA.AMR]-Werte:
amr in der Authentifizierungsanfrage enthalten und in den Einstellungen aktiviert ist.
|
|
auth_time |
Der Zeitpunkt, zu dem die Nutzerauthentifizierung stattgefunden hat, eine JSON-Zahl, die die Anzahl der Sekunden darstellt, die seit der Unix-Epoche (1. Januar 1970, 00:00:00 UTC) vergangen sind. Wird bereitgestellt, wenn der Anspruch auth_time in der Authentifizierungsanfrage enthalten und in den Einstellungen aktiviert ist.
|
|
at_hash |
Zugriffstoken-Hash. Bestätigt, dass das Zugriffstoken an das Identitätstoken gebunden ist. Wenn das ID-Token im Serverablauf mit einem access_token-Wert ausgestellt wird, ist diese Anforderung immer enthalten. Diese Anforderung kann als alternativer Mechanismus zum Schutz vor websiteübergreifenden Anfragen 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 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 für Hybrid-Apps der Fall sein, bei denen eine Webanwendung und eine Android-App eine andere OAuth 2.0-client_id haben, aber dasselbe Google APIs-Projekt verwenden. |
|
email |
Die E-Mail-Adresse des Nutzers. Wird nur angegeben, wenn Sie den Bereich email in Ihre Anfrage aufgenommen haben. Der Wert dieser Anforderung ist möglicherweise nicht eindeutig für dieses Konto und kann sich im Laufe der Zeit ändern. Daher sollten Sie diesen Wert nicht als primäre Kennung für die Verknüpfung mit Ihrem Nutzereintrag verwenden. Sie können sich auch nicht auf die Domain des email-Claims verlassen, um Nutzer von Google Workspace- oder Cloud-Organisationen zu identifizieren. Verwenden Sie stattdessen den hd-Claim.
|
|
email_verified |
„True“, wenn die E-Mail-Adresse des Nutzers bestätigt wurde, andernfalls „False“. | |
family_name |
Der Nachname des Nutzers. Kann angegeben werden, wenn ein name-Anspruch vorhanden ist. |
|
given_name |
Der Vorname oder die Vornamen des Nutzers. Kann angegeben werden, wenn ein name-Anspruch vorhanden ist. |
|
hd |
Die Domain, die mit der Google Workspace- oder Cloud-Organisation des Nutzers verknüpft ist. Wird nur angegeben, wenn der Nutzer zu einer Google Cloud-Organisation gehört. Sie müssen diese Anforderung prüfen, wenn Sie den Zugriff auf eine Ressource auf Mitglieder bestimmter Domains beschränken. Das Fehlen dieser Anforderung zeigt an, dass das Konto nicht zu einer von Google gehosteten Domain gehört. | |
locale |
Die Sprache des Nutzers, dargestellt durch ein BCP 47-Sprach-Tag.
Kann angegeben werden, wenn ein name-Anspruch vorhanden ist. |
|
name |
Der vollständige Name des Nutzers in einer darstellbaren Form. Kann in folgenden Fällen angegeben werden:
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 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 Anwendung 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 zur Registrierung für neue Nutzer weiterleiten. Möglicherweise können Sie den Nutzer anhand der von Google erhaltenen Informationen automatisch registrieren oder zumindest viele der erforderlichen Felder im Registrierungsformular vorab ausfüllen. Zusätzlich zu den Informationen im ID-Token können Sie an unseren Nutzerprofil-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 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 die Berechtigung erhalten kann, andere Google APIs im Namen des Nutzers (z. B. YouTube, Google Drive, Kalender oder Kontakte) gleichzeitig mit der Authentifizierung des Nutzers zu verwenden. 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 sich auf die von Ihnen angeforderten und gewährten Zugriffsbereiche beziehen.
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 ermöglicht Ihrer App kontinuierlichen Zugriff auf Google APIs, während 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:
- Achten Sie darauf, das Aktualisierungstoken sicher und dauerhaft zu speichern, da Sie es nur beim ersten Ausführen des Codeaustauschvorgangs erhalten.
- Die Anzahl der ausgestellten 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, 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 in Ihrer Authentifizierungsanfrage den Parameter prompt auf consent setzen. Wenn prompt=consent enthalten ist, wird der Zustimmungsbildschirm jedes Mal angezeigt, wenn Ihre Anwendung 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 ein, wenn es erforderlich ist.
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-Authentifizierungs-API von Google akzeptiert werden.
| Parameter | Erforderlich | Beschreibung | ||||||
|---|---|---|---|---|---|---|---|---|
client_id |
(Erforderlich) | Der Client-ID-String, den Sie auf der Seite „Clients“ der Cloud Console erhalten, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben. | ||||||
nonce |
(Erforderlich) | Ein von Ihrer App generierter Zufallswert, der den Replay-Schutz ermöglicht. | ||||||
response_type |
(Erforderlich) | Wenn der Wert code ist, wird ein grundlegender Autorisierungscode-Vorgang gestartet, für den ein POST an den Token-Endpunkt erforderlich ist, um die Tokens abzurufen. Wenn der Wert token id_token oder id_token token ist, wird ein impliziter Ablauf gestartet. Dabei muss JavaScript am Weiterleitungs-URI verwendet werden, um Tokens aus der URI-#fragment-Kennung abzurufen. |
||||||
redirect_uri |
(Erforderlich) | Bestimmt, wohin die Antwort gesendet wird. Der Wert dieses Parameters muss genau mit einem der autorisierten Weiterleitungswerte übereinstimmen, die Sie in der Cloud Console auf der Seite „Clients“ 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 das Bereichsargument auch andere Bereichswerte enthalten. Alle Bereichswerte müssen durch Leerzeichen getrennt sein. Wenn Sie beispielsweise Zugriff auf einzelne Dateien im Google Drive eines Nutzers benötigen, könnte der Bereichsparameter Informationen zu 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 verschlüsselter String, der im Protokoll hin- und hergeleitet wird. Das bedeutet, dass er im einfachen Ablauf als URI-Parameter und im impliziten Ablauf in der URI-Kennung Die |
||||||
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. |
||||||
claims |
(Optional) | Mit dem
Anspruchsparameter werden ein oder mehrere optionale Felder angegeben, die in den Antworttypen für den Userinfo-Endpunkt oder das ID-Token der Authentifizierungsanfrage enthalten sein sollen. Der Wert ist ein JSON-Objekt, das den Antworttyp und die angeforderten Anforderungen enthält. Die folgenden Anspruchsanfragen werden von Google-Servern akzeptiert:
|
||||||
display |
(Optional) | Ein ASCII-Stringwert, der angibt, wie der Autorisierungsserver die Seiten der Benutzeroberfläche für Authentifizierung und Einwilligung anzeigt. Die folgenden Werte werden angegeben und von den Google-Servern akzeptiert, haben aber keine Auswirkungen auf das Verhalten des Protokollablaufs: page, popup, touch und wap. |
||||||
hd |
(Optional) | Optimieren Sie den Anmeldevorgang für Konten, die einer Google Cloud-Organisation gehören. Wenn Sie die Domain der Google Cloud-Organisation angeben (z. B. mycollege.edu), können Sie angeben, dass die Benutzeroberfläche für die Kontoauswahl für Konten in dieser Domain optimiert werden soll. Wenn Sie die Optimierung allgemein für Google Cloud-Organisationskonten und nicht nur für eine Google Cloud-Organisationsdomain vornehmen möchten, legen Sie 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üfen Sie, ob das zurückgegebene ID-Token einen |
||||||
include_granted_scopes |
(Optional) | Wenn dieser Parameter den Wert true hat und die Autorisierungsanfrage genehmigt wird, umfasst die Autorisierung alle vorherigen Autorisierungen, die dieser Nutzer/Anwendungs-Kombination für andere Bereiche gewährt wurden. Weitere Informationen finden Sie unter
Inkrementelle Autorisierung.
Beachten Sie, dass Sie mit dem Ablauf für installierte Apps keine inkrementelle Autorisierung durchführen können. |
||||||
login_hint |
(Optional) | Wenn Ihre App weiß, welcher Nutzer authentifiziert werden soll, kann sie diesen Parameter als Hinweis an den Authentifizierungsserver übergeben. Wenn Sie diesen Hinweis übergeben, wird die Kontoauswahl unterdrückt und entweder das E-Mail-Feld im Anmeldeformular vorausgefüllt oder die richtige Sitzung ausgewählt (wenn der Nutzer die Mehrfachanmeldung verwendet). So können Sie Probleme vermeiden, die auftreten, wenn sich Ihre App im 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 nicht zuvor autorisiert hat, wird dem Nutzer ein Zustimmungsbildschirm angezeigt. |
||||||
hl |
(Optional) | Ein BCP 47-Sprach-Tag, mit dem die Anzeigesprache für die Bildschirme für die Anmeldung, die Kontoauswahl und den Zustimmungsbildschirm angegeben wird. Wenn dieser Parameter nicht angegeben ist, wird die Sprache standardmäßig auf die Einstellungen des Google-Kontos oder des Browsers des Nutzers festgelegt. Wenn Sie beispielsweise die Benutzeroberfläche in britischem Englisch anfordern möchten, setzen Sie den Parameter auf en-GB.
|
||||||
ID-Token validieren
Sie müssen alle ID-Tokens auf Ihrem Server validieren, es sei denn, Sie wissen, dass sie direkt von Google stammen. Ihr Server muss beispielsweise alle ID-Tokens, die er von Ihren Client-Apps erhält, als authentisch verifizieren.
In den folgenden Situationen werden ID-Tokens häufig an den Server gesendet:
- Senden von ID-Tokens mit Anfragen, die authentifiziert werden müssen. Die ID-Tokens geben Aufschluss darüber, 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 mithilfe von POST-Daten oder in Anfrageheadern übertragen. Wenn Sie ID-Tokens auf Ihrem Server speichern, müssen Sie sie auch sicher speichern.
ID-Tokens sind nützlich, weil Sie sie an verschiedene Komponenten Ihrer Anwendung weitergeben können. Diese Komponenten können ein ID-Token als einfachen Authentifizierungsmechanismus verwenden, um die Anwendung 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 sich unter dem URI befinden, der im Metadatenwert
jwks_urides Discovery-Dokuments angegeben ist. - Prüfen Sie, ob der Wert der Anforderung
issim ID-Token mithttps://accounts.google.comoderaccounts.google.comübereinstimmt. - Prüfen Sie, ob der Wert der
aud-Anforderung im ID-Token mit der Client-ID Ihrer App übereinstimmt. - Prüfen Sie, ob die Ablaufzeit (
exp-Anspruch) 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.
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.
Zu Debugging-Zwecken können Sie den Google-Endpunkt tokeninfo verwenden, um die lokale Verarbeitung auf Ihrem Server oder Gerät zu vergleichen. Angenommen, der Wert Ihres ID-Tokens ist XYZ123. Anschließend dereferenzieren Sie den URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123.
Wenn die Tokensignatur gültig ist, ist die Antwort die JWT-Nutzlast in Form eines decodierten JSON-Objekts.
Der Endpunkt tokeninfo ist für die Fehlerbehebung nützlich. Für Produktionszwecke sollten Sie jedoch die öffentlichen Schlüssel von Google vom Endpunkt „keys“ abrufen und die Validierung lokal durchführen. Sie sollten den Schlüssel-URI aus dem Discovery-Dokument mit dem Metadatenwert jwks_uri abrufen. Anfragen an den Debugging-Endpunkt können gedrosselt werden oder anderweitig zeitweiligen Fehlern unterliegen.
Da Google seine öffentlichen Schlüssel nur selten ändert, können Sie sie mithilfe der Cache-Anweisungen der HTTP-Antwort im Cache speichern. In den meisten Fällen ist die lokale Validierung dann viel effizienter als die Verwendung des Endpunkts tokeninfo. Für diese Validierung müssen Zertifikate abgerufen und geparst werden. Außerdem müssen die entsprechenden kryptografischen Aufrufe zur Überprüfung der Signatur durchgeführt werden. Glücklicherweise gibt es dafür gut debuggte Bibliotheken in einer Vielzahl von Sprachen (siehe jwt.io).
Informationen zum Nutzerprofil 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 Ihre Anwendung OpenID-konform ist, 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 URI Ihrer Authentifizierungsanfrage einfügen:scope=openid%20profile%20emailFügen Sie Ihr Zugriffstoken dem Autorisierungsheader hinzu und senden Sie eine HTTPS-
GET-Anfrage an den userinfo-Endpunkt, den Sie mit dem Metadatenwertuserinfo_endpointaus dem Discovery-Dokument abrufen sollten. Die userinfo-Antwort enthält Informationen zum Nutzer, wie inOpenID Connect Standard Claimsund im Metadatenwertclaims_supporteddes Discovery-Dokuments beschrieben. Nutzer oder ihre Organisationen können bestimmte Felder angeben oder weglassen. Daher erhalten Sie möglicherweise nicht für jedes Feld Informationen für Ihre autorisierten Zugriffsbereiche.
Discovery-Dokument
Das OpenID Connect-Protokoll erfordert die Verwendung mehrerer Endpunkte, um Nutzer zu authentifizieren und Ressourcen wie Tokens, Nutzerinformationen und öffentliche Schlüssel anzufordern.
Um die Implementierung zu vereinfachen und die Flexibilität zu erhöhen, ermöglicht OpenID Connect die Verwendung eines „Discovery-Dokuments“. Dies ist ein JSON-Dokument, das sich an einem bekannten Speicherort befindet und Schlüssel/Wert-Paare enthält, die Details zur Konfiguration des OpenID Connect-Anbieters enthalten, 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 URI des Discovery-Dokuments (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 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 in OpenID Connect Discovery 1.0 angegebenen. Die Bedeutung der Feldnamen finden Sie in diesem Dokument. Die Werte dienen nur zur 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" ] }
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 Einbindung in gängige Frameworks:
- Google APIs-Clientbibliothek für Java
- Google APIs-Clientbibliothek für Python
- Google APIs-Clientbibliothek für .NET
- Google APIs-Clientbibliothek für Ruby
- Google APIs-Clientbibliothek für PHP
- OAuth 2.0-Bibliothek für Google Web Toolkit
- Google Toolbox for Mac OAuth 2.0 Controllers
OpenID Connect-Compliance
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 interagieren (mit Ausnahme des OpenID-Anfrageobjekts).