Diese Seite wurde von der Cloud Translation API übersetzt.

OpenID Connect

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 OAuth 2.0 für den Zugriff auf Google APIs verwenden gilt auch für diesen Dienst. Wenn Sie dieses Protokoll interaktiv kennenlernen 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 in der einrichten, um OAuth 2.0-Anmeldedaten zu erhalten, eine Weiterleitungs-URI festzulegen und (optional) die Branding-Informationen anzupassen, die Ihre Nutzer auf dem Bildschirm zur Nutzereinwilligung sehen. Sie können auch verwenden, um ein Dienstkonto zu erstellen, die Abrechnung zu aktivieren, die Filterung einzurichten und andere Aufgaben auszuführen. Weitere Informationen finden Sie in der -Hilfe.

OAuth 2.0-Anmeldedaten abrufen

Sie benötigen OAuth 2.0-Anmeldedaten, einschließlich einer Client-ID und eines Clientschlüssels, um Nutzer zu authentifizieren und Zugriff auf die APIs von Google zu erhalten.

Weiterleitungs-URI festlegen

Der Weiterleitungs-URI, den Sie in der festlegen, bestimmt, wohin Google Antworten auf Ihre Authentifizierungsanfragen sendet.

Bildschirm zur Einwilligung der Nutzer anpassen

Die OAuth 2.0-Authentifizierung umfasst einen Einwilligungsbildschirm, auf dem die von den Nutzern freigegebenen Informationen und die geltenden Nutzungsbedingungen 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 der Authentifizierungsanfrage enthält. Sie können auch Berechtigungen verwenden, um Zugriff auf andere Google APIs anzufordern.

Der Bildschirm zur Nutzereinwilligung enthält außerdem Markeninformationen wie den Produktnamen, das Logo und die URL der Startseite. Sie verwalten die Branding-Informationen in der .

Im folgenden Einwilligungsdialog wird dargestellt, 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 dem Google OAuth 2.0 Playground erstellt und enthält daher keine Branding-Informationen, die in der festgelegt würden.

Auf den Dienst zugreifen

Google und Drittanbieter stellen Bibliotheken bereit, mit denen Sie viele der Implementierungsdetails zur Authentifizierung von Nutzern und zum Zugriff auf Google APIs erledigen können. Beispiele hierfür sind die Google Identity Services und die Google-Clientbibliotheken, die für eine Vielzahl von Plattformen verfügbar sind.

Wenn Sie keine Bibliothek verwenden möchten, folgen Sie der Anleitung im restlichen Teil 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 eine standardisierte Funktion von OpenID Connect, die zum Teilen von Identitätsausdrücken im Internet entwickelt wurde.

Die gängigsten Ansätze zur Authentifizierung eines Nutzers und zum Abrufen eines ID-Tokens werden als „Server-Ablauf“ und „impliziter Ablauf“ bezeichnet. Beim Serverablauf kann der Back-End-Server einer Anwendung die Identität der Person überprüfen, die einen Browser oder ein Mobilgerät verwendet. Der implizite Ablauf wird verwendet, wenn eine clientseitige Anwendung (in der Regel eine JavaScript-App, die im Browser ausgeführt wird) direkt und nicht über den Back-End-Server auf APIs zugreifen muss.

In diesem Dokument wird beschrieben, wie der Serverablauf für die Authentifizierung des Nutzers ausgeführt wird. Der implizite Ablauf ist aufgrund der Sicherheitsrisiken beim Umgang mit und der Verwendung von Tokens auf der Clientseite deutlich komplizierter. Wenn Sie einen impliziten Ablauf implementieren müssen, empfehlen wir dringend die Verwendung von Google Identity Services.

Serverfluss

Richten Sie Ihre App in der ein, damit sie diese Protokolle verwenden und Ihre Nutzer authentifizieren kann. Wenn ein Nutzer versucht, sich mit Google anzumelden, müssen Sie Folgendes tun:

Statustoken zur Fälschungssicherheit erstellen
Authentifizierungsanfrage an Google senden
Status-Token zur Fälschungssicherheit bestätigen
code gegen Zugriffs- und ID-Token austauschen
Nutzerinformationen aus dem ID-Token abrufen
Nutzer authentifizieren

1. Statustoken zur Fälschungssicherheit 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. Sie gleichen dieses eindeutige Sitzungstoken später mit der Authentifizierungsantwort ab, die vom Google OAuth-Anmeldedienst zurückgegeben wird, um zu prüfen, ob die Anfrage vom Nutzer und nicht von einem böswilligen Angreifer stammt. Diese Tokens werden oft als CSRF-Tokens (Cross-Site Request Forgery) bezeichnet.

Ein geeigneter String für ein Status-Token ist ein String mit etwa 30 Zeichen, der mit einem hochwertigen Zufallszahlengenerator erstellt wurde. Eine weitere Möglichkeit ist ein Hash, der generiert wird, indem einige Ihrer Sitzungsstatusvariablen mit einem Schlüssel signiert werden, der auf Ihrem Back-End geheim gehalten wird.

Im folgenden Code wird gezeigt, wie eindeutige Sitzungstokens generiert werden.

PHP

Sie müssen die Google APIs-Clientbibliothek für PHP herunterladen, um dieses Beispiel verwenden zu können.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

Java

Sie müssen die Google APIs-Clientbibliothek für Java herunterladen, um dieses Beispiel verwenden zu können.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

Python

Sie müssen die Google APIs-Clientbibliothek für Python herunterladen, um dieses Beispiel verwenden zu können.

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. Authentifizierungsanfrage an Google senden

Im nächsten Schritt wird eine HTTPS-GET-Anfrage mit den entsprechenden URI-Parametern erstellt. Beachten Sie, dass in allen Schritten dieses Prozesses HTTPS anstelle von HTTP verwendet wird. HTTP-Verbindungen werden abgelehnt. Du solltest den Basis-URI mit dem Metadatenwert authorization_endpoint aus dem Discovery-Dokument abrufen. In der folgenden Beschreibung wird davon ausgegangen, dass der Basis-URI https://accounts.google.com/o/oauth2/v2/auth ist.

Geben Sie für eine einfache Anfrage die folgenden Parameter an:

client_id, die Sie von der erhalten.
response_type, die in einer einfachen Autorisierungscode-Anfrage code sein sollte. Weitere Informationen finden Sie unter response_type.
scope, was in einer einfachen Anfrage openid email sein sollte. (Weitere Informationen finden Sie unter scope.)
redirect_uri sollte der HTTP-Endpunkt auf Ihrem Server sein, an den die Antwort von Google gesendet wird. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie in der konfiguriert haben. Wenn dieser Wert nicht mit einem autorisierten URI übereinstimmt, schlägt die Anfrage mit dem Fehler redirect_uri_mismatch fehl.
state sollte den Wert des eindeutigen Sitzungstokens zur Betrugsprävention sowie alle anderen Informationen enthalten, die zum Wiederherstellen des Kontexts erforderlich sind, wenn der Nutzer zu deiner Anwendung zurückkehrt, z.B. die Start-URL. (Weitere Informationen finden Sie unter state.)
nonce ist ein von Ihrer App generierter Zufallswert, der den Replay-Schutz aktiviert, wenn er vorhanden ist.
login_hint kann die E-Mail-Adresse des Nutzers oder der String sub sein, der der Google-ID des Nutzers entspricht. Wenn Sie keine login_hint angeben und der Nutzer derzeit angemeldet ist, enthält der Einwilligungsbildschirm eine Genehmigungsanfrage, die E-Mail-Adresse des Nutzers an Ihre App weiterzugeben. Weitere Informationen finden Sie unter login_hint.
Mit dem Parameter hd können Sie den OpenID Connect-Ablauf für Nutzer einer bestimmten Domain optimieren, die mit einer Google Workspace- oder Cloud-Organisation verknüpft ist. Weitere Informationen finden Sie unter hd.

Hier ist ein Beispiel für einen vollständigen OpenID Connect-Authentifizierungs-URI mit Zeilenumbrüchen und Leerzeichen für eine bessere Lesbarkeit:

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//oauth2.example.com/code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=jsmith@example.com&
 nonce=0394852-3190485-2490358&
 hd=example.com

Nutzer müssen ihre Einwilligung geben, wenn Ihre App neue Informationen über sie anfordert oder wenn Ihre App den Kontozugriff anfordert, den sie zuvor nicht genehmigt haben.

3. Statustoken zur Fälschungssicherheit bestätigen

Die Antwort wird an die redirect_uri gesendet, die Sie in der Anfrage angegeben haben. Alle Antworten werden im Abfragestring zurückgegeben, wie unten dargestellt:

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 musst du prüfen, ob das von Google empfangene state mit dem Sitzungstoken übereinstimmt, das du in Schritt 1 erstellt hast. Diese Rücksendebestätigung trägt dazu bei, sicherzustellen, dass die Anfrage vom Nutzer und nicht von einem schädlichen Script stammt.

Im folgenden Code wird gezeigt, wie die Sitzungstokens bestätigt werden, 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 Zugriffs- und ID-Token austauschen

Die Antwort enthält einen code-Parameter, einen einmaligen Autorisierungscode, den dein Server gegen ein Zugriffs- und ID-Token eintauschen kann. Dazu sendet Ihr Server eine HTTPS-POST-Anfrage. Die POST-Anfrage wird an den Token-Endpunkt gesendet, den du mit dem Metadatenwert token_endpoint aus dem Discovery-Dokument abrufen solltest. In der folgenden Diskussion wird davon ausgegangen, dass der Endpunkt https://oauth2.googleapis.com/token ist. Die Anfrage muss die folgenden Parameter im POST-Body enthalten:

Felder
`code`	Der Autorisierungscode, der von der ursprünglichen Anfrage zurückgegeben wird.
`client_id`	Die Client-ID, die du von der abrufen kannst, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben.
`client_secret`	Der Clientschlüssel, den Sie von erhalten, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben.
`redirect_uri`	Ein autorisierter Weiterleitungs-URI für die angegebene `client_id` in der , 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, das Identitätsinformationen über den Nutzer enthält und von Google digital signiert wurde.
`scope`	Die Zugriffsbereiche, die durch das `access_token` gewährt werden, als Liste von durch Leerzeichen getrennten, groß- und kleinschreibungssensitiven Strings.
`token_type`	Gibt den Typ des zurückgegebenen Tokens an. Derzeit hat dieses Feld immer den Wert `Bearer`.
`refresh_token`	(optional) Dieses Feld ist nur vorhanden, wenn der Parameter `access_type` in der Authentifizierungsanfrage auf `offline` gesetzt wurde. Weitere Informationen finden Sie unter Aktualisierungstokens.

5. Nutzerinformationen aus dem ID-Token abrufen

Ein ID-Token ist ein JWT (JSON Web Token), also ein kryptografisch signiertes Base64-codiertes JSON-Objekt. Normalerweise ist es wichtig, dass Sie ein ID-Token validieren, bevor Sie es verwenden. Da Sie jedoch direkt über einen HTTPS-Kanal ohne Vermittler mit Google kommunizieren und sich mit Ihrem Client-Secret bei Google authentifizieren, können Sie davon ausgehen, dass das empfangene Token tatsächlich von Google stammt und gültig ist. Wenn Ihr Server das ID-Token an andere Komponenten Ihrer App weitergibt, ist es äußerst wichtig, dass die anderen Komponenten das Token validieren, bevor sie es verwenden.

Da die meisten API-Bibliotheken die Validierung mit der Dekodierung der base64url-codierten Werte und dem Parsen des JSON-Codes kombinieren, müssen Sie das Token wahrscheinlich trotzdem validieren, wenn Sie auf die Berechtigungen im ID-Token zugreifen.

Nutzlast eines ID-Tokens

Ein ID-Token ist ein JSON-Objekt, das eine Reihe von Namen/Wert-Paaren enthält. Hier ein Beispiel, das für eine bessere Lesbarkeit formatiert ist:

{
  "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 (sogenannte Anspruchsrechte) 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, ab der das ID-Token nicht mehr akzeptiert werden darf. Wird in Unix-Zeit (ganze Sekunden) angegeben.
`iat`	immer	Der Zeitpunkt, zu dem das ID-Token ausgestellt wurde. In Unix-Zeit (ganze Sekunden) angegeben.
`iss`	immer	Die Aussteller-ID des Ausstellers der Antwort. Immer `https://accounts.google.com` oder `accounts.google.com` für Google-ID-Tokens.
`sub`	immer	Eine eindeutige Kennung für den Nutzer, die für alle Google-Konten einmalig ist und nie wiederverwendet wird. Ein Google-Konto kann zu verschiedenen Zeitpunkten mehrere E-Mail-Adressen haben, der Wert `sub` ändert sich jedoch nie. Verwenden Sie `sub` in Ihrer Anwendung als Schlüssel für die eindeutige Kennung des Nutzers. Maximale Länge: 255 ASCII-Zeichen, wobei die Groß- und Kleinschreibung beachtet wird.
`at_hash`		Hash des Zugriffstokens. Prüft, ob das Zugriffstoken mit dem Identitätstoken verknüpft ist. Wenn das ID-Token im Serverablauf mit einem `access_token`-Wert ausgestellt wird, ist dieser Anspruch immer enthalten. Dieser Anspruch kann als alternativer Mechanismus zum Schutz vor Cross-Site-Request-Forgery-Angriffen verwendet werden. Wenn Sie jedoch Schritt 1 und Schritt 3 ausführen, ist es nicht erforderlich, das Zugriffstoken zu überprüfen.
`azp`		Die `client_id` des bevollmächtigten Ausstellers. Dieser Anspruch ist nur erforderlich, wenn die Partei, die das ID-Token anfordert, nicht mit der Zielgruppe des ID-Tokens übereinstimmt. Das kann bei Google für Hybrid-Apps der Fall sein, bei denen eine Webanwendung und eine Android-App eine unterschiedliche OAuth 2.0-`client_id` haben, aber dasselbe Google APIs-Projekt verwenden.
`email`		Die E-Mail-Adresse des Nutzers. Wird nur bereitgestellt, wenn Sie den Umfang `email` in Ihre Anfrage aufgenommen haben. Der Wert dieses Anspruchs ist möglicherweise nicht für dieses Konto eindeutig und kann sich im Laufe der Zeit ändern. Verwenden Sie diesen Wert daher nicht als primäre Kennung, um eine Verknüpfung mit Ihrem Nutzerdatensatz herzustellen. Außerdem können Sie die Domain des `email`-Anspruchs nicht verwenden, um Nutzer von Google Workspace- oder Cloud-Organisationen zu identifizieren. Verwenden Sie stattdessen den `hd`-Anspruch.
`email_verified`		„Wahr“, wenn die E-Mail-Adresse des Nutzers bestätigt wurde, andernfalls „Falsch“.
`family_name`		Der Nachname oder die Nachnamen des Nutzers. Kann angegeben werden, wenn ein `name`-Anspruch vorliegt.
`given_name`		Der oder die Vornamen des Nutzers. Kann angegeben werden, wenn ein `name`-Anspruch vorliegt.
`hd`		Die Domain, die mit der Google Workspace- oder Cloud-Organisation des Nutzers verknüpft ist. Wird nur bereitgestellt, wenn der Nutzer zu einer Google Cloud-Organisation gehört. Sie müssen diese Erklärung ankreuzen, wenn Sie den Zugriff auf eine Ressource nur auf Mitglieder bestimmter Domains beschränken. Wenn diese Anforderung nicht vorhanden ist, gehört das Konto nicht zu einer von Google gehosteten Domain.
`locale`		Die Sprache des Nutzers, dargestellt durch ein BCP 47-Sprach-Tag. Kann angegeben werden, wenn ein `name`-Anspruch vorliegt.
`name`		Der vollständige Name des Nutzers in einer anzeigbaren Form. Kann in folgenden Fällen angegeben werden: Der Anfragebereich enthielt den String „Profil“. Das ID-Token wird von einer Tokenaktualisierung zurückgegeben. Wenn `name`-Anfragen vorhanden sind, können Sie sie verwenden, um die Nutzerdaten Ihrer App zu aktualisieren. Dieser Anspruch ist nicht immer vorhanden.
`nonce`		Der Wert von `nonce`, der von Ihrer App in der Authentifizierungsanfrage angegeben wurde. Sie sollten Schutz vor Replay-Angriffen erzwingen, indem Sie dafür sorgen, dass der Code nur einmal präsentiert wird.
`picture`		Die URL des Profilbilds des Nutzers. Kann in folgenden Fällen angegeben werden: Der Anfragebereich enthielt den String „Profil“. Das ID-Token wird von einer Tokenaktualisierung zurückgegeben. Wenn `picture`-Anspruche vorhanden sind, können Sie sie verwenden, um die Nutzerdaten Ihrer App zu aktualisieren. Dieser Anspruch ist nicht immer vorhanden.
`profile`		Die URL der Profilseite des Nutzers. Kann in folgenden Fällen angegeben werden: Der Anfragebereich enthielt den String „Profil“. Das ID-Token wird von einer Tokenaktualisierung zurückgegeben. Wenn `profile`-Anspruche vorhanden sind, können Sie sie verwenden, um die Nutzerdaten Ihrer App zu aktualisieren. Dieser Anspruch ist nicht immer vorhanden.

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 die Google API-Antwort alle Anmeldevoraussetzungen erfüllt.

Wenn der Nutzer nicht in Ihrer Nutzerdatenbank vorhanden ist, sollten Sie ihn zum Registrierungsvorgang für neue Nutzer weiterleiten. Unter Umständen können Sie den Nutzer anhand der Informationen, die Sie von Google erhalten, automatisch registrieren. Alternativ können Sie viele der Felder in Ihrem Registrierungsformular zumindest vorab ausfüllen. Zusätzlich zu den Informationen im ID-Token können Sie über unsere Nutzerprofilendpunkte weitere Nutzerprofilinformationen abrufen.

Themen für Fortgeschrittene

In den folgenden Abschnitten wird die Google OAuth 2.0 API genauer beschrieben. Diese Informationen richten sich an Entwickler mit erweiterten Anforderungen an Authentifizierung und Autorisierung.

Zugriff auf andere Google APIs

Einer der Vorteile der Verwendung von OAuth 2.0 für die Authentifizierung besteht darin, dass Ihre Anwendung gleichzeitig mit der Authentifizierung des Nutzers die Berechtigung erhalten kann, andere Google APIs im Namen des Nutzers zu verwenden, z. B. YouTube, Google Drive, Kalender oder Kontakte. Fügen Sie dazu die erforderlichen zusätzlichen Bereiche in die Authentifizierungsanfrage ein, die Sie an Google senden. Wenn du beispielsweise deiner Authentifizierungsanfrage die Altersgruppe des Nutzers hinzufügen möchtest, gib den Gültigkeitsbereichsparameter openid email https://www.googleapis.com/auth/profile.agerange.read an. Der Nutzer wird auf dem Zustimmungsbildschirm entsprechend aufgefordert. Mit dem Zugriffstoken, das Sie von Google erhalten, können Sie auf alle APIs zugreifen, die mit den von Ihnen angeforderten und gewährten Zugriffsbereichen zusammenhängen.

Aktualisierungstokens

In Ihrer Anfrage für den API-Zugriff können Sie ein Aktualisierungstoken anfordern, das beim code-Austausch zurückgegeben wird. Mit einem Aktualisierungstoken kann Ihre App auch dann kontinuierlich auf Google APIs zugreifen, wenn der Nutzer nicht in Ihrer Anwendung angemeldet ist. Wenn du ein Aktualisierungstoken anfordern möchtest, setze den Parameter access_type in deiner Authentifizierungsanfrage auf offline.

Wichtige Hinweise:

Speichere das Aktualisierungstoken sicher und dauerhaft, da du es nur beim ersten Mal erhalten kannst, wenn du den Code-Austauschvorgang durchführst.
Die Anzahl der ausgestellten Aktualisierungstokens ist begrenzt: ein Limit pro Kombination aus Client und Nutzer und ein weiteres pro Nutzer für alle Clients. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, kann es zu diesen Limits kommen. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.

Weitere Informationen finden Sie unter Zugriffstoken aktualisieren (Offlinezugriff).

Sie können den Nutzer auffordern, Ihre App noch einmal zu autorisieren, indem Sie in Ihrer Authentifizierungsanfrage den Parameter prompt auf consent festlegen. Wenn prompt=consent enthalten ist, wird der Einwilligungsbildschirm jedes Mal angezeigt, wenn Ihre App die Autorisierung von Zugriffsbereichen anfordert, auch wenn alle Bereiche zuvor Ihrem Google APIs-Projekt gewährt wurden. Fügen Sie prompt=consent daher nur bei Bedarf ein.

Weitere Informationen zum Parameter prompt findest du in der Tabelle Authentifizierungs-URI-Parameter unter prompt.

Authentifizierungs-URI-Parameter

In der folgenden Tabelle finden Sie eine vollständigere Beschreibung der Parameter, die von der OAuth 2.0-Authentifizierungs-API von Google akzeptiert werden.

Parameter	Erforderlich	Beschreibung
`client_id`	(Erforderlich)	Der Client-ID-String, den Sie von abrufen, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben.
`nonce`	(Erforderlich)	Ein von Ihrer App generierter Zufallswert, der den Replay-Schutz aktiviert.
`response_type`	(Erforderlich)	Wenn der Wert `code` ist, wird ein grundlegender Autorisierungscode-Vorgang gestartet, für den ein `POST` an den Tokenendpunkt erforderlich ist, um die Tokens abzurufen. Wenn der Wert `token id_token` oder `id_token token` ist, wird ein impliziter Ablauf gestartet. Dazu ist JavaScript am Weiterleitungs-URI erforderlich, um Tokens aus der URI-Kennung `#fragment` 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 festgelegt haben(einschließlich des HTTP- oder HTTPS-Schemas, der Groß- und Kleinschreibung und gegebenenfalls eines abschließenden „/“).
`scope`	(Erforderlich)	Der Parameter „scope“ muss mit dem Wert `openid` beginnen und dann den Wert `profile`, den Wert `email` oder beide enthalten. Wenn der `profile`-Scope-Wert vorhanden ist, enthält das ID-Token möglicherweise (aber nicht garantiert) die standardmäßigen `profile`-Anforderungen des Nutzers. Wenn der Wert „`email`“ für den Umfang vorhanden ist, enthält das ID-Token die Ansprüche `email` und `email_verified`. Zusätzlich zu diesen OpenID-spezifischen Bereichen kann das Bereichsargument auch andere Bereichswerte enthalten. Alle Bereichswerte müssen durch Leerzeichen getrennt werden. Wenn Sie beispielsweise pro Datei Zugriff auf das Google Drive eines Nutzers benötigen, könnte der Umfangsparameter `openid profile email https://www.googleapis.com/auth/drive.file` sein. Informationen zu verfügbaren Bereichen finden Sie unter OAuth 2.0-Bereiche für Google APIs oder in der Dokumentation der zu verwendenden Google API.
`state`	(Optional, aber dringend empfohlen)	Ein undurchsichtiger String, der im Protokoll weitergeleitet wird. Das bedeutet, dass er im Basisablauf als URI-Parameter und im impliziten Ablauf in der URI-`#fragment`-Kennung zurückgegeben wird. Die `state` kann nützlich sein, um Anfragen und Antworten zu korrelieren. Da Ihre `redirect_uri` erraten werden kann, können Sie mit einem `state`-Wert die Sicherheit erhöhen, dass eine eingehende Verbindung das Ergebnis einer von Ihrer App initiierten Authentifizierungsanfrage ist. Wenn Sie einen zufälligen String generieren oder den Hash eines bestimmten Clientstatus (z.B. eines Cookies) in dieser `state`-Variablen codieren, können Sie die Antwort validieren, um zusätzlich sicherzustellen, dass die Anfrage und Antwort aus demselben Browser stammen. Dies bietet Schutz vor Angriffen wie websiteübergreifenden Anfragefälschungen.
`access_type`	(Optional)	Die zulässigen Werte sind `offline` und `online`. Die Auswirkungen sind unter Offlinezugriff beschrieben. 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 Authentifizierungs- und Einwilligungsseiten der Benutzeroberfläche anzeigt. Die folgenden Werte werden angegeben und von den Google-Servern akzeptiert, haben aber keine Auswirkungen auf das Verhalten: `page`, `popup`, `touch` und `wap`.
`hd`	(Optional)	Vereinfachen Sie den Anmeldevorgang für Konten, die zu einer Google Cloud-Organisation gehören. Wenn Sie die Google Cloud-Organisationsdomain (z. B. `mycollege.edu`) angeben, 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, setzen Sie einen Stern (``) als Wert: `hd=`. Sie sollten sich nicht darauf verlassen, dass diese UI-Optimierung festlegt, wer auf Ihre App zugreifen kann, da clientseitige Anfragen geändert werden können. Prüfen Sie, ob das `hd`-Anspruchselement im zurückgegebenen ID-Token den erwarteten Wert hat (z. B. `mycolledge.edu`). Im Gegensatz zum Anfrageparameter ist das `hd`-Anspruchselement des ID-Tokens in einem Sicherheitstoken von Google enthalten. Der Wert kann also als vertrauenswürdig angesehen werden.
`include_granted_scopes`	(Optional)	Wenn für diesen Parameter der Wert `true` angegeben wird und die Autorisierungsanfrage gewährt wird, umfasst die Autorisierung alle vorherigen Autorisierungen, die dieser Kombination aus Nutzer und Anwendung für andere Bereiche gewährt wurden. Weitere Informationen finden Sie unter Inkrementelle Autorisierung. Mit dem Ablauf für installierte Apps ist keine inkrementelle Autorisierung möglich.
`login_hint`	(Optional)	Wenn Ihre App weiß, welchen Nutzer sie authentifizieren möchte, kann sie diesen Parameter als Hinweis an den Authentifizierungsserver senden. Wenn Sie diesen Hinweis übergeben, wird die Kontoauswahl unterdrückt und entweder das E-Mail-Feld im Anmeldeformular wird vorab ausgefüllt oder die richtige Sitzung wird ausgewählt (falls der Nutzer die Mehrere Anmeldungen verwendet). So können Sie Probleme vermeiden, die auftreten, wenn in Ihrer App das falsche Nutzerkonto angemeldet wird. 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: `none` Der Autorisierungsserver zeigt keine Authentifizierungs- oder Nutzereinwilligungsbildschirme an. Er gibt einen Fehler zurück, wenn der Nutzer noch nicht authentifiziert ist und die Einwilligung für die angeforderten Bereiche nicht vorab konfiguriert wurde. Mit `none` können Sie prüfen, ob eine vorhandene Authentifizierung und/oder Einwilligung vorliegt. `consent` Der Autorisierungsserver fordert den Nutzer zur Einwilligung auf, bevor er Informationen an den Client zurückgibt. `select_account` Der Autorisierungsserver fordert den Nutzer auf, ein Nutzerkonto auszuwählen. So kann ein Nutzer, der mehrere Konten beim Autorisierungsserver hat, aus den Konten auswählen, für die er aktuelle Sitzungen hat. Wenn kein Wert angegeben ist und der Nutzer den Zugriff zuvor nicht autorisiert hat, wird ihm ein Einwilligungsbildschirm angezeigt.

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 bestätigen.

In den folgenden gängigen Situationen können Sie ID-Tokens an Ihren Server senden:

Senden von ID-Tokens mit Anfragen, die authentifiziert werden müssen. Anhand der ID-Tokens kannst du den Nutzer ermitteln, der die Anfrage stellt, und für welchen Client das ID-Token gewährt wurde.

ID-Tokens sind vertraulich und können bei Abfangen missbraucht werden. Sie müssen dafür sorgen, dass diese Tokens sicher verarbeitet werden, indem Sie sie nur über HTTPS und nur über POST-Daten oder innerhalb von Anfrage-Headern übertragen. Wenn Sie ID-Tokens auf Ihrem Server speichern, müssen Sie sie auch sicher speichern.

ID-Tokens sind unter anderem deshalb nützlich, weil sie an verschiedene Komponenten Ihrer App übergeben werden können. Diese Komponenten können ein ID-Token als einfachen Authentifizierungsmechanismus verwenden, um die App und den Nutzer zu authentifizieren. Bevor Sie die Informationen im ID-Token verwenden oder sich darauf verlassen können, dass sich der Nutzer authentifiziert hat, müssen Sie es validieren.

Die Validierung eines ID-Tokens erfordert mehrere Schritte:

Prüfen Sie, ob das ID-Token vom Aussteller ordnungsgemäß signiert wurde. Von Google ausgestellte Tokens werden mit einem der Zertifikate signiert, die unter dem URI gefunden werden, der im Metadatenwert jwks_uri des Discovery-Dokuments angegeben ist.
Prüfen Sie, ob der Wert der iss-Anforderung im ID-Token https://accounts.google.com oder accounts.google.com ist.
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 noch nicht abgelaufen ist.
Wenn du in der Anfrage einen Wert für den hd-Parameter angegeben hast, überprüfe, ob das ID-Token einen hd-Anspruch enthält, der mit einer akzeptierten Domain übereinstimmt, die mit einer Google Cloud-Organisation verknüpft ist.

Die Schritte 2 bis 5 umfassen nur String- und Datumsvergleiche, die recht einfach sind. Wir gehen hier nicht näher darauf ein.

Der erste Schritt ist komplexer und umfasst die Überprüfung der kryptografischen Signatur. Zum Debuggen können Sie den tokeninfo-Endpunkt von Google verwenden, um die lokale Verarbeitung auf Ihrem Server oder Gerät zu vergleichen. Angenommen, der Wert Ihres ID-Tokens lautet XYZ123. Dann entfernen Sie die Referenz auf den URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Wenn die Tokensignatur gültig ist, enthält die Antwort die JWT-Nutzlast in decodierter JSON-Objektform.

Der tokeninfo-Endpunkt ist für die Fehlerbehebung nützlich. Für die Produktion sollten Sie jedoch die öffentlichen Schlüssel von Google vom Schlüsselendpunkt abrufen und die Validierung lokal ausführen. Sie sollten den Schlüssel-URI mit dem Metadatenwert jwks_uri aus dem Discovery-Dokument abrufen. Anfragen an den Debug-Endpunkt können gedrosselt oder anderweitig von sporadischen Fehlern betroffen sein.

Da Google seine öffentlichen Schlüssel nur selten ändert, kannst du sie mithilfe der Cache-Anweisungen der HTTP-Antwort im Cache speichern und in den meisten Fällen eine lokale Validierung viel effizienter durchführen als mit dem tokeninfo-Endpunkt. Für diese Validierung müssen Zertifikate abgerufen und geparst sowie die entsprechenden kryptografischen Aufrufe zur Überprüfung der Signatur ausgeführt werden. Glücklicherweise gibt es gut debuggte Bibliotheken in einer Vielzahl von Sprachen, die dies ermöglichen (siehe jwt.io).

Nutzerprofilinformationen abrufen

Wenn Sie zusätzliche Profilinformationen zum Nutzer abrufen möchten, können Sie das Zugriffstoken (das Ihre Anwendung während des Authentifizierungsablaufs erhält) und den OpenID Connect-Standard verwenden:

Damit die OpenID-Compliance eingehalten wird, müssen Sie die Werte für den openid profile-Bereich in Ihre Authentifizierungsanfrage aufnehmen.

Wenn die E-Mail-Adresse des Nutzers enthalten sein soll, können Sie einen zusätzlichen Gültigkeitsbereichswert von email angeben. Wenn du sowohl profile als auch email angeben möchtest, kannst du den folgenden Parameter in den URI der Authentifizierungsanfrage einfügen:
```
scope=openid%20profile%20email
```
Füge dem Autorisierungsheader dein Zugriffstoken hinzu und sende eine HTTPS-GET-Anfrage an den Userinfo-Endpunkt, den du mit dem userinfo_endpoint-Metadatenwert aus dem Discovery-Dokument abrufen solltest. Die Antwort „userinfo“ enthält Informationen zum Nutzer, wie in OpenID Connect Standard Claims beschrieben, und den Metadatenwert claims_supported des Discovery-Dokuments. Nutzer oder ihre Organisationen können bestimmte Felder angeben oder zurückhalten. 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 für die Authentifizierung von Nutzern und für das Anfordern von Ressourcen wie Tokens, Nutzerinformationen und öffentlichen Schlüsseln.

Zur Vereinfachung von Implementierungen und zur Steigerung der Flexibilität ermöglicht OpenID Connect die Verwendung eines „Discovery-Dokuments“. Das 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 unter folgenden Links abgerufen werden:

https://accounts.google.com/.well-known/openid-configuration

Wenn Sie die OpenID Connect-Dienste von Google verwenden möchten, sollten Sie den URI des Discovery-Dokuments (https://accounts.google.com/.well-known/openid-configuration) in Ihre Anwendung einfügen. Ihre Anwendung ruft das Dokument ab, wendet Caching-Regeln in der Antwort an und ruft bei Bedarf Endpunkt-URIs daraus ab. Wenn Sie beispielsweise einen Nutzer authentifizieren möchten, ruft Ihr Code den Metadatenwert authorization_endpoint (https://accounts.google.com/o/oauth2/v2/auth im Beispiel unten) als Basis-URI für Authentifizierungsanfragen ab, die an Google gesendet werden.

Hier ist ein Beispiel für ein solches Dokument. Die Feldnamen entsprechen den in OpenID Connect Discovery 1.0 angegebenen Namen. Die Bedeutungen finden Sie in diesem Dokument. Die Werte dienen nur zur Veranschaulichung und können sich ändern. Sie wurden aus einer aktuellen Version des Google Discovery-Dokuments kopiert:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

Möglicherweise können Sie einen HTTP-Rücklauf vermeiden, indem Sie die Werte aus dem Discovery-Dokument im Cache speichern. Es werden Standard-HTTP-Caching-Header verwendet, die beachtet werden sollten.

Clientbibliotheken

Die folgenden Clientbibliotheken vereinfachen die Implementierung von OAuth 2.0, da sie in gängige Frameworks eingebunden werden können:

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 können (mit Ausnahme des OpenID-Anfrageobjekts).

OpenID Connect

OAuth 2.0 einrichten

OAuth 2.0-Anmeldedaten abrufen

Weiterleitungs-URI festlegen

Bildschirm zur Einwilligung der Nutzer anpassen

Auf den Dienst zugreifen

Nutzer authentifizieren

Serverfluss

1. Statustoken zur Fälschungssicherheit erstellen

PHP

Java

Python

2. Authentifizierungsanfrage an Google senden

3. Statustoken zur Fälschungssicherheit bestätigen

PHP

Java

Python

4. code gegen Zugriffs- und ID-Token austauschen

5. Nutzerinformationen aus dem ID-Token abrufen

Nutzlast eines ID-Tokens

6. Nutzer authentifizieren

Themen für Fortgeschrittene

Zugriff auf andere Google APIs

Aktualisierungstokens

Aufforderung zur erneuten Einwilligung

Authentifizierungs-URI-Parameter

ID-Token validieren

Nutzerprofilinformationen abrufen

Discovery-Dokument

Clientbibliotheken

OpenID Connect-Compliance

4. `code` gegen Zugriffs- und ID-Token austauschen