Diese Seite wurde von der Cloud Translation API übersetzt.

OpenID Connect

Die OAuth 2.0 APIs von Google können sowohl zur Authentifizierung als auch zur 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. Um Hilfe auf Stack Overflow zu erhalten, markieren Sie Ihre Fragen mit dem Tag "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 Google API Console einrichten, um OAuth 2.0-Anmeldedaten abzurufen, einen Weiterleitungs-URI festzulegen und (optional) die Branding-Informationen anzupassen, die Ihre Nutzer auf dem Bildschirm für die Nutzereinwilligung sehen. Sie können auch API Console verwenden, um ein Dienstkonto zu erstellen, die Abrechnung zu aktivieren, Filter einzurichten und andere Aufgaben zu erledigen. Weitere Informationen finden Sie in der Google API Console-Hilfe.

OAuth 2.0-Anmeldedaten abrufen

Du benötigst 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 ( ). Ihre Kunden-ID und Ihr Geheimnis befinden sich oben auf der Seite.

Weiterleitungs-URI festlegen

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

To create, view, or edit the redirect URIs for a given OAuth 2.0 credential, do the following:

Go to the Credentials page.
In the OAuth 2.0 client IDs section of the page, click a credential.
View or edit the redirect URIs.

If there is no OAuth 2.0 client IDs section on the Credentials page, then your project has no OAuth credentials. To create one, click Create credentials.

Bildschirm für die Nutzereinwilligung anpassen

Für Ihre Nutzer umfasst die OAuth 2.0-Authentifizierung einen Zustimmungsbildschirm, auf dem die vom Nutzer freigegebenen Informationen und die geltenden Nutzungsbedingungen beschrieben werden. Ein Nutzer wird beispielsweise bei der Anmeldung aufgefordert, Ihrer Anwendung Zugriff auf seine E-Mail-Adresse und grundlegende Kontoinformationen zu gewähren. Zugriff auf diese Informationen fordern Sie über den Parameter scope an, den Ihre Anwendung in die Authentifizierungsanfrage einfügt. Sie können Bereiche auch verwenden, um Zugriff auf andere Google APIs anzufordern.

Der Bildschirm für die Nutzereinwilligung enthält auch Markeninformationen wie den Produktnamen, das Logo und eine URL der Startseite. Die Brandinginformationen werden in API Consoleverwaltet.

So aktivieren Sie den Zustimmungsbildschirm Ihres Projekts:

Öffnen Sie das Consent Screen page im Google API Console .
If prompted, select a project, or create a new one.
Füllen Sie das Formular aus und klicken Sie auf Speichern .

Im folgenden Dialog zur Einholung von Einwilligungen sehen Sie, was Nutzer sehen würden, wenn in der Anfrage eine Kombination aus OAuth 2.0- und Google Drive-Bereichen vorhanden ist. (Dieses allgemeine Dialogfeld wurde mit Google OAuth 2.0 Playground generiert und enthält daher keine Branding-Informationen, die im API Consolefestgelegt werden würden.)

Auf den Dienst zugreifen

Google und Drittanbieter stellen Bibliotheken zur Verfügung, mit denen Sie sich um viele Implementierungsdetails für die Authentifizierung von Nutzern und den Zugriff auf Google APIs kümmern können. Beispiele hierfür sind Google Identity Services und die Google-Clientbibliotheken, die für verschiedene Plattformen verfügbar sind.

Wenn Sie keine Bibliothek verwenden möchten, folgen Sie der Anleitung im restlichen Dokument. 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 werden als „Serverfluss“ und „Impliziter Ablauf“ bezeichnet. Mithilfe des Serverflusses kann der Back-End-Server einer Anwendung die Identität der Person über einen Browser oder ein Mobilgerät prüfen. Der implizite Ablauf wird verwendet, wenn eine clientseitige Anwendung (normalerweise eine im Browser ausgeführte JavaScript-Anwendung) direkt auf APIs statt über ihren Back-End-Server zugreifen muss.

In diesem Dokument wird beschrieben, wie der Serverablauf zur Authentifizierung des Nutzers ausgeführt wird. Der implizite Ablauf ist aufgrund der Sicherheitsrisiken bei der Handhabung und Verwendung von Tokens auf Clientseite erheblich komplizierter. Wenn Sie einen impliziten Vorgang implementieren müssen, empfehlen wir dringend die Verwendung von Google Identity Services.

Serverablauf

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

Token für den Status „Anti-Fälschung“ erstellen
Authentifizierungsanfrage an Google senden
Anti-Fälschungs-Token bestätigen
code gegen Zugriffstoken und ID-Token austauschen
Nutzerinformationen aus dem ID-Token abrufen
Nutzer authentifizieren

1. Anti-Fälschungstoken erstellen

Sie müssen die Sicherheit Ihrer Nutzer schützen, indem Sie Anfragenfälschungen verhindern. Der erste Schritt besteht darin, ein eindeutiges Sitzungstoken zu erstellen, das den Status zwischen Ihrer Anwendung und dem Client des Nutzers enthält. Später ordnen Sie dieses eindeutige Sitzungstoken der Authentifizierungsantwort zu, die vom Google-OAuth-Log-in-Dienst zurückgegeben wird, um zu bestätigen, dass der Nutzer die Anfrage stellt und kein böswilliger Angreifer. Diese Tokens werden oft als CSRF-Token (Cross-Site Request Forgery) bezeichnet.

Eine gute Wahl für ein Statustoken ist ein String aus etwa 30 Zeichen, der mit einem hochwertigen Zufallszahlengenerator erstellt wird. Eine weitere ist ein Hash, der durch Signieren einiger Sitzungsstatusvariablen mit einem Schlüssel generiert wird, der auf Ihrem Back-End geheim gehalten wird.

Mit dem folgenden Code wird das Generieren eindeutiger Sitzungstokens veranschaulicht.

PHP

Sie müssen die Google API-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 API-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 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 erstellen Sie eine HTTPS-GET-Anfrage mit den entsprechenden URI-Parametern. Beachten Sie, dass in allen Schritten dieses Prozesses HTTPS anstelle von HTTP verwendet wird. HTTP-Verbindungen werden abgelehnt. Rufen Sie den Basis-URI aus dem Discovery-Dokument mit dem Metadatenwert authorization_endpoint ab. In der folgenden Diskussion wird davon ausgegangen, dass der Basis-URI https://accounts.google.com/o/oauth2/v2/auth ist.

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

client_id, die Sie aus dem API Console- Credentials pageabrufen.
response_type: In einer einfachen Anfrage mit Autorisierungscode sollte der Wert code lauten. Weitere Informationen finden Sie unter response_type.
scope. In einer einfachen Anfrage sollte dieser openid email lauten. 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 du in der API Console Credentials pagekonfiguriert hast. Wenn dieser Wert mit keinem autorisierten URI übereinstimmt, schlägt die Anfrage mit dem Fehler redirect_uri_mismatch fehl.
state sollte den Wert des eindeutigen Sitzungstokens gegen Fälschung 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 finden Sie unter state.
nonce ist ein von der Anwendung generierter Zufallswert, der den Schutz vor Wiedergaben aktiviert, sofern vorhanden.
login_hint kann die E-Mail-Adresse des Nutzers oder der String sub sein, der der Google-ID des Nutzers entspricht. Wenn du kein login_hint angibst und der Nutzer derzeit angemeldet ist, enthält der Zustimmungsbildschirm eine Genehmigungsanfrage, um die E-Mail-Adresse des Nutzers für deine App freizugeben. Weitere Informationen findest du unter login_hint.
Verwenden Sie den Parameter hd, um den OpenID Connect-Ablauf für Nutzer einer bestimmten Domain zu optimieren, die mit einer Google Cloud-Organisation verknüpft ist. Weitere Informationen finden Sie unter hd.

Hier 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//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 deine App neue Informationen über sie anfordert oder wenn deine App Kontozugriff anfordert, den sie zuvor noch nicht genehmigt haben.

3. Anti-Fälschungsstatus-Token bestätigen

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

https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

Auf dem Server müssen Sie bestätigen, dass das von Google erhaltene state mit dem Sitzungstoken übereinstimmt, das Sie in Schritt 1 erstellt haben. Mit dieser Umlaufüberprüfung wird sichergestellt, dass die Anfrage nicht von einem schädlichen Skript, sondern vom Nutzer gesendet wird.

Mit dem folgenden Code können Sie die Sitzungstokens bestätigen, die Sie in Schritt 1 erstellt haben:

PHP

Sie müssen die Google API-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 API-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 APIs-Clientbibliothek für Python herunterladen, um dieses Beispiel verwenden zu können.

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

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

Die Antwort enthält den Parameter code, einen einmaligen Autorisierungscode, den Ihr Server gegen ein Zugriffstoken und ein ID-Token austauschen kann. Dein Server sendet für diesen Austausch eine HTTPS-POST-Anfrage. Die POST-Anfrage wird an den Tokenendpunkt gesendet, den Sie mit dem Metadatenwert 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 im POST-Text die folgenden Parameter enthalten:

Felder
`code`	Der Autorisierungscode, der von der ersten Anfrage zurückgegeben wird.
`client_id`	Die Client-ID, die Sie über die API Console Credentials pageerhalten, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben.
`client_secret`	Der Clientschlüssel, den Sie aus dem API Console Credentials pageabrufen, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben.
`redirect_uri`	Ein autorisierter Weiterleitungs-URI für die angegebene `client_id`, die in API Console- Credentials pageangegeben 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 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 des Nutzers enthält und von Google digital signiert wird.
`scope`	Die Zugriffsbereiche, die durch den `access_token` gewährt werden, ausgedrückt als Liste von durch Leerzeichen getrennten Strings unter Beachtung der Groß- und Kleinschreibung.
`token_type`	Gibt den Typ des zurückgegebenen Tokens an. Derzeit enthält 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), d. h. ein kryptografisch signiertes Base64-codiertes JSON-Objekt. Normalerweise ist es wichtig, dass du ein ID-Token vor der Verwendung prüfst. Da du aber direkt mit Google über einen zwischenfreien HTTPS-Kanal kommunizierst und deinen Clientschlüssel zur Authentifizierung bei Google verwendest, kannst du sicher sein, dass das erhaltene Token wirklich von Google stammt und gültig ist. Wenn Ihr Server das ID-Token an andere Komponenten Ihrer Anwendung weitergibt, ist es äußerst wichtig, dass die anderen Komponenten das Token vor der Verwendung validieren.

Da die meisten API-Bibliotheken die Validierung mit der Decodierung der base64url-codierten Werte und dem Parsen des darin enthaltenen JSONs kombinieren, wird das Token wahrscheinlich trotzdem validiert, wenn Sie auf die Anforderungen 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 zur besseren Lesbarkeit formatiertes Beispiel:

{
  "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 Ansprüche):

Anspruch erheben	Bereitgestellt	Beschreibung
`aud`	immer	Die Zielgruppe, für die dieses ID-Token bestimmt ist. Dabei muss es sich um eine der OAuth 2.0-Client-IDs Ihrer Anwendung handeln.
`exp`	immer	Ablaufzeit, ab der das ID-Token nicht akzeptiert werden darf. Wird in Unix-Zeit (ganzzahlige Sekunden) dargestellt.
`iat`	immer	Der Zeitpunkt, zu dem das ID-Token ausgestellt wurde. Wird in Unix-Zeit (ganzzahlige Sekunden) dargestellt.
`iss`	immer	Die Aussteller-ID für den Aussteller der Antwort. 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, aber der Wert `sub` bleibt unverändert. Verwenden Sie `sub` in Ihrer Anwendung als Schlüssel zur eindeutigen Kennung für den Nutzer. Maximale Länge: 255 ASCII-Zeichen, bei denen die Groß- und Kleinschreibung berücksichtigt wird.
`at_hash`		Zugriffstoken-Hash Bietet die Validierung, ob das Zugriffstoken mit dem Identitätstoken verknüpft ist. Wenn das ID-Token im Serverablauf mit einem `access_token`-Wert ausgegeben wird, ist diese Anforderung immer enthalten. Diese Anforderung kann als alternativer Mechanismus zum Schutz vor Cross-Site-Request-Fälschungen-Angriffen verwendet werden. Wenn Sie jedoch Schritt 1 und Schritt 3 ausführen, ist es nicht erforderlich, das Zugriffstoken zu verifizieren.
`azp`		`client_id` des autorisierten Vortragenden. Diese Anforderung ist nur erforderlich, wenn die Partei, die das ID-Token anfordert, nicht mit der Zielgruppe des ID-Tokens übereinstimmt. Dies kann bei Google bei Hybridanwendungen der Fall sein, bei denen eine Webanwendung und eine Android-App unterschiedliche OAuth 2.0-`client_id` haben, aber dasselbe Google APIs-Projekt verwenden.
`email`		Die E-Mail-Adresse des Nutzers. Dieser Wert ist möglicherweise nicht eindeutig für diesen Nutzer und nicht zur Verwendung als Primärschlüssel geeignet. Wird nur angegeben, wenn der Bereich den Wert `email` enthält.
`email_verified`		„True“, wenn die E-Mail-Adresse des Nutzers bestätigt wurde, andernfalls „false“.
`family_name`		Nachname des Nutzers Kann angegeben werden, wenn eine `name`-Anforderung vorliegt.
`given_name`		Vorname(n) oder Vorname(n) des Nutzers Kann angegeben werden, wenn eine `name`-Anforderung vorliegt.
`hd`		Die Domain, die mit der Google Cloud-Organisation des Nutzers verknüpft ist. Wird nur angegeben, wenn der Nutzer zu einer Google Cloud-Organisation gehört.
`locale`		Die Sprache des Nutzers, dargestellt durch ein BCP 47-Sprach-Tag. Kann angegeben werden, wenn eine `name`-Anforderung vorliegt.
`name`		Der vollständige Name des Nutzers in anzeigbarer Form. Kann in folgenden Fällen zur Verfügung gestellt werden: Der Anfragebereich enthielt den String „profile“ Das ID-Token wird von einer Token-Aktualisierung zurückgegeben. Wenn `name`-Anforderungen vorhanden sind, können Sie sie zum Aktualisieren der Nutzerdatensätze Ihrer App verwenden. Dieser Anspruch ist jedoch nicht zwangsläufig vorhanden.
`nonce`		Der Wert von `nonce`, der von Ihrer Anwendung in der Authentifizierungsanfrage bereitgestellt wird. Sie sollten den Schutz vor Replay-Angriffen durchsetzen, indem Sie darauf achten, dass er nur einmal angezeigt wird.
`picture`		Die URL des Profilbilds des Nutzers. Kann in folgenden Fällen zur Verfügung gestellt werden: Der Anfragebereich enthielt den String „profile“ Das ID-Token wird von einer Token-Aktualisierung zurückgegeben. Wenn `picture`-Anforderungen vorhanden sind, können Sie sie zum Aktualisieren der Nutzerdatensätze Ihrer App verwenden. Dieser Anspruch ist jedoch nicht zwangsläufig vorhanden.
`profile`		Die URL der Profilseite des Nutzers. Kann in folgenden Fällen zur Verfügung gestellt werden: Der Anfragebereich enthielt den String „profile“ Das ID-Token wird von einer Token-Aktualisierung zurückgegeben. Wenn `profile`-Anforderungen vorhanden sind, können Sie sie zum Aktualisieren der Nutzerdatensätze Ihrer App verwenden. Dieser Anspruch ist jedoch nicht zwangsläufig vorhanden.

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 für diesen Nutzer eine Anwendungssitzung starten, sofern die Google API-Antwort alle Anmeldeanforderungen erfüllt.

Wenn der Nutzer nicht in Ihrer Nutzerdatenbank vorhanden ist, sollten Sie ihn zum Registrierungsvorgang für neue Nutzer weiterleiten. Du kannst Nutzer möglicherweise auf Grundlage der Informationen, die du von Google erhältst, automatisch registrieren oder zumindest viele Felder deines Registrierungsformulars vorab ausfüllen. Zusätzlich zu den Informationen im ID-Token können Sie an unseren Nutzerprofilendpunkten weitere Nutzerprofilinformationen abrufen.

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 an Authentifizierung und Autorisierung.

Zugriff auf andere Google APIs

Einer der Vorteile von OAuth 2.0 zur Authentifizierung besteht darin, dass deine Anwendung während 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 anderen benötigten Bereiche in die Authentifizierungsanfrage ein, die Sie an Google senden. Wenn Sie beispielsweise der Authentifizierungsanfrage die Altersgruppe des Nutzers hinzufügen möchten, übergeben Sie den Bereichsparameter openid email https://www.googleapis.com/auth/profile.agerange.read. Der Nutzer wird auf dem Zustimmungsbildschirm entsprechend aufgefordert. Mit dem Zugriffstoken, das Sie von Google erhalten, können Sie auf alle APIs zugreifen, die sich auf die von Ihnen angeforderten und gewährten Zugriffsbereiche beziehen.

Aktualisierungstokens

In der Anfrage für den API-Zugriff können Sie ein Aktualisierungstoken anfordern, das während des code-Austauschs zurückgegeben wird. Ein Aktualisierungstoken bietet Ihrer Anwendung ständigen Zugriff auf Google APIs, während der Nutzer nicht in der Anwendung vorhanden ist. Wenn Sie ein Aktualisierungstoken anfordern möchten, setzen Sie den Parameter access_type in Ihrer Authentifizierungsanfrage auf offline.

Wichtige Hinweise:

Bewahren Sie das Aktualisierungstoken sicher und dauerhaft auf, da Sie ein Aktualisierungstoken nur beim ersten Ausführen des Codeaustauschs abrufen können.
Es gibt Limits für die Anzahl der ausgegebenen Aktualisierungstokens: ein Limit pro Client/Nutzer-Kombination und ein weiteres pro Nutzer für alle Clients. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, können diese Limits überschritten werden. Ältere Aktualisierungstokens funktionieren in diesem Fall nicht mehr.

Weitere Informationen finden Sie unter Zugriffstoken aktualisieren (Offlinezugriff).

Sie können den Nutzer auffordern, die Anwendung noch einmal zu autorisieren. Dazu setzen Sie den Parameter prompt in Ihrer Authentifizierungsanfrage auf consent. Wenn prompt=consent angegeben ist, wird der Zustimmungsbildschirm jedes Mal angezeigt, wenn Ihre Anwendung die Autorisierung von Zugriffsbereichen anfordert, auch wenn zuvor alle Bereiche Ihrem Google APIs-Projekt gewährt wurden. Verwenden Sie daher prompt=consent nur dann, wenn dies unbedingt erforderlich ist.

Weitere Informationen zum Parameter prompt finden Sie unter prompt in der Tabelle Authentifizierungs-URI-Parameter.

Authentifizierungs-URI-Parameter

Die folgende Tabelle enthält ausführlichere Beschreibungen der Parameter, die von der OAuth 2.0 Authentication API von Google akzeptiert werden.

Parameter	Erforderlich	Beschreibung
`client_id`	(erforderlich)	Der Client-ID-String, den Sie von API Console Credentials pageerhalten, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben.
`nonce`	(erforderlich)	Ein von Ihrer Anwendung generierter Zufallswert, der den Schutz vor Wiedergaben aktiviert.
`response_type`	(erforderlich)	Wenn der Wert `code` ist, wird ein Vorgang mit einem einfachen Autorisierungscode gestartet, für den eine `POST` zum Tokenendpunkt erforderlich ist, um die Tokens abzurufen. Wenn der Wert `token id_token` oder `id_token token` ist, wird ein impliziter Vorgang gestartet, bei dem JavaScript im Weiterleitungs-URI verwendet werden muss, um Tokens aus der URI `#fragment`-Kennung abzurufen.
`redirect_uri`	(erforderlich)	Legt fest, wohin die Antwort gesendet wird. Der Wert dieses Parameters muss genau mit einem der autorisierten Weiterleitungswerte übereinstimmen, die Sie in API Console Credentials page festgelegt haben(einschließlich HTTP- oder HTTPS-Schema, Groß-/Kleinschreibung und nachgestelltem „/“, falls vorhanden).
`scope`	(erforderlich)	Der Parameter für den Umfang muss mit dem Wert `openid` beginnen und dann den Wert `profile`, `email` oder beides enthalten. Wenn der `profile`-Bereichswert vorhanden ist, kann das ID-Token die `profile`-Standardanforderungen des Nutzers enthalten, dies ist jedoch nicht garantiert. Wenn der Bereichswert `email` vorhanden ist, enthält das ID-Token die Anforderungen `email` und `email_verified`. Zusätzlich zu diesen OpenID-spezifischen Bereichen kann das Bereichsargument auch andere Bereichswerte enthalten. Alle Werte für den Bereich müssen durch Leerzeichen getrennt sein. Wenn Sie beispielsweise pro Datei Zugriff auf das Google Drive-Konto eines Nutzers wünschen, kann der Bereichsparameter `openid profile email https://www.googleapis.com/auth/drive.file` lauten. Informationen zu verfügbaren Bereichen finden Sie unter OAuth 2.0-Bereiche für Google APIs oder in der Dokumentation für die Google API, die Sie verwenden möchten.
`state`	(Optional, wird aber dringend empfohlen)	Ein intransparenter String, bei dem im Protokoll ein Roundtrip ausgeführt wird. Das heißt, er wird im einfachen Ablauf als URI-Parameter und im impliziten Ablauf in der URI-ID `#fragment` zurückgegeben. Der `state` kann für die Korrelation von Anfragen und Antworten nützlich sein. Da Ihr `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 Anwendung initiierten Authentifizierungsanfrage ist. Wenn Sie einen zufälligen String generieren oder den Hash eines Clientstatus (z.B. ein Cookie) in dieser `state`-Variable codieren, können Sie die Antwort validieren, um zusätzlich zu prüfen, ob die Anfrage und die Antwort vom selben Browser stammen. Dies bietet Schutz vor Angriffen wie Cross-Site-Requestfälschung.
`access_type`	(Optional)	Die zulässigen Werte sind `offline` und `online`. Die Auswirkungen sind unter Offlinezugriff dokumentiert. Wenn ein Zugriffstoken angefordert wird, erhält der Client nur dann ein Aktualisierungstoken, wenn der Wert `offline` angegeben ist.
`display`	(Optional)	Ein ASCII-Stringwert, mit dem angegeben wird, wie der Autorisierungsserver die Seiten der Benutzeroberfläche zur Authentifizierung und Einwilligung anzeigt. Die folgenden Werte werden von den Google-Servern angegeben und akzeptiert, haben jedoch keinen Einfluss auf ihr Verhalten: `page`, `popup`, `touch` und `wap`.
`hd`	(Optional)	Optimieren Sie den Anmeldevorgang für Konten, die zu einer Google Cloud-Organisation gehören. Durch Einschließen der Google Cloud-Organisationsdomain (z. B. `mycollege.edu`) können Sie angeben, dass die UI zur Kontoauswahl für Konten in dieser Domain optimiert werden soll. Legen Sie den Wert eines Sternchens (``) fest, um im Allgemeinen statt nur einer Google Cloud-Organisationsdomain für Google Cloud-Organisationskonten zu optimieren: `hd=`. 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. Du musst validate, ob das zurückgegebene ID-Token einen `hd`-Anforderungswert hat, der deinen Erwartungen entspricht (z.B. `mycolledge.edu`). Im Gegensatz zum Anfrageparameter ist die ID-Token-Anforderung `hd` in einem Sicherheitstoken von Google enthalten, sodass der Wert vertrauenswürdig ist.
`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 Nutzer-/Anwendungskombination für andere Bereiche erteilt wurden. Weitere Informationen finden Sie unter Inkrementelle Autorisierung. Im Ablauf „Installierte Anwendung“ ist keine inkrementelle Autorisierung möglich.
`login_hint`	(Optional)	Wenn die Anwendung weiß, welchen Nutzer sie zu authentifizieren versucht, kann sie diesen Parameter als Hinweis an den Authentifizierungsserver senden. Wenn dieser Hinweis übergeben wird, wird die Kontoauswahl unterdrückt und entweder das E-Mail-Feld im Anmeldeformular automatisch ausgefüllt oder die richtige Sitzung ausgewählt (wenn der Nutzer die Mehrfachanmeldung verwendet). So lassen sich Probleme vermeiden, die auftreten, wenn sich Ihre Anwendung 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. Folgende Werte sind möglich: `none` Der Autorisierungsserver zeigt keine Authentifizierungs- oder Nutzereinwilligungsbildschirme an. Wenn der Nutzer noch nicht authentifiziert ist und keine Einwilligung für die angeforderten Bereiche vorkonfiguriert hat, gibt er einen Fehler zurück. Mit `none` können Sie prüfen, ob eine Authentifizierung bzw. Einwilligung vorliegt. `consent` Der Autorisierungsserver fordert den Nutzer um seine Zustimmung auf, bevor er Informationen an den Client zurückgibt. `select_account` Der Autorisierungsserver fordert den Nutzer auf, ein Nutzerkonto auszuwählen. Dadurch kann ein Nutzer, der mehrere Konten auf dem Autorisierungsserver hat, aus den verschiedenen Konten auswählen, für die er aktuell Sitzungen hat. Wenn kein Wert angegeben ist und der Nutzer zuvor keinen Zugriff autorisiert hat, wird ihm ein Zustimmungsbildschirm angezeigt.

ID-Token validieren

Du musst alle ID-Tokens auf deinem Server validieren, es sei denn, du weißt, dass sie direkt von Google stammen. Beispielsweise muss Ihr Server alle ID-Tokens, die er von Ihren Clientanwendungen erhält, als echt bestätigen lassen.

In den folgenden Fällen können ID-Tokens an Ihren Server gesendet werden:

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 dieses ID-Token gewährt wurde.

ID-Tokens sind vertraulich und können missbraucht werden, wenn sie abgefangen werden. Sie müssen für eine sichere Verarbeitung dieser Tokens sorgen, indem Sie sie nur über HTTPS und nur über POST-Daten oder in Anfrageheadern übertragen. Wenn Sie ID-Tokens auf Ihrem Server speichern, müssen Sie diese ebenfalls an einem sicheren Ort 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 jedoch 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 ordnungsgemäß vom Aussteller signiert ist. Von Google ausgestellte Tokens werden mit einem der Zertifikate signiert, die unter dem URI im Metadatenwert jwks_uri des Discovery-Dokuments angegeben sind.
Prüfen Sie, ob der Wert der iss-Anforderung im ID-Token https://accounts.google.com oder accounts.google.com entspricht.
Prüfen Sie, ob der Wert der aud-Anforderung im ID-Token der Client-ID Ihrer Anwendung entspricht.
Prüfen Sie, ob die Ablaufzeit (exp-Anforderung) des ID-Tokens nicht abgelaufen ist.
Wenn Sie in der Anfrage den Wert eines hd-Parameters angegeben haben, prüfen Sie, ob das ID-Token eine hd-Anforderung enthält, 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 relativ einfach sind und daher hier nicht näher erläutert werden.

Der erste Schritt ist komplexer und umfasst eine kryptografische Signaturprüfung. Für die Fehlerbehebung können Sie den tokeninfo-Endpunkt von Google verwenden, um einen Vergleich mit der lokalen Verarbeitung durchzuführen, die auf Ihrem Server oder Gerät implementiert ist. Angenommen, der Wert Ihres ID-Tokens lautet XYZ123. Dann würden Sie den URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123 dereferenzieren. Wenn die Tokensignatur gültig ist, wäre die Antwort die JWT-Nutzlast in ihrer decodierten JSON-Objektform.

Der Endpunkt tokeninfo ist nützlich für die Fehlerbehebung. Für Produktionszwecke sollten Sie jedoch die öffentlichen Schlüssel von Google vom Schlüsselendpunkt abrufen und die Validierung lokal durchführen. Rufen Sie den Schlüssel-URI aus dem Discovery-Dokument mit dem Metadatenwert jwks_uri ab. Anfragen an den Debugging-Endpunkt können gedrosselt oder auf andere Weise zeitweilig auftretenden Fehlern ausgesetzt werden.

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 eine lokale Validierung wesentlich effizienter als mit dem Endpunkt tokeninfo. Dazu müssen Zertifikate abgerufen und geparst und die entsprechenden kryptografischen Aufrufe ausgeführt werden, um die Signatur zu prüfen. Glücklicherweise gibt es dazu gut debuggene Bibliotheken in einer Vielzahl von Sprachen (siehe jwt.io).

Nutzerprofilinformationen abrufen

Mit dem Zugriffstoken, das Ihre Anwendung während des Authentifizierungsvorgangs empfängt, können Sie sowie den OpenID Connect-Standard verwenden, um zusätzliche Profilinformationen über den Nutzer zu erhalten:

Um OpenID-konform zu sein, müssen Sie die Werte für den openid profile-Bereich in Ihrer Authentifizierungsanfrage angeben.

Wenn Sie die E-Mail-Adresse des Nutzers einbeziehen möchten, können Sie einen zusätzlichen Bereichswert von email angeben. Wenn Sie sowohl profile als auch email angeben möchten, können Sie den folgenden Parameter in den URI der Authentifizierungsanfrage aufnehmen:
```
scope=openid%20profile%20email
```
Fügen Sie dem Autorisierungsheader Ihr Zugriffstoken hinzu und senden Sie eine HTTPS-GET-Anfrage an den Endpunkt „userinfo“. Diesen sollten Sie mit dem Metadatenwert userinfo_endpoint aus dem Discovery-Dokument abrufen. Die „userinfo“-Antwort enthält Informationen über den Nutzer, wie in OpenID Connect Standard Claims beschrieben, und den claims_supported-Metadatenwert 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 in Ihren autorisierten Zugriffsbereichen Informationen.

Discovery-Dokument

Das OpenID Connect-Protokoll erfordert die Verwendung mehrerer Endpunkte zur Authentifizierung von Nutzern und zum Anfordern von Ressourcen wie Tokens, Nutzerinformationen und öffentlichen Schlüsseln.

Um Implementierungen zu vereinfachen und die Flexibilität zu erhöhen, ermöglicht OpenID Connect die Verwendung eines „Discovery-Dokuments“. Das ist ein JSON-Dokument an einem bekannten Speicherort mit Schlüssel/Wert-Paaren, 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 abgerufen werden von:

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. Die Anwendung ruft das Dokument ab, wendet Caching-Regeln in der Antwort an und ruft dann nach Bedarf Endpunkt-URIs daraus ab. Zur Authentifizierung eines Nutzers würde Ihr Code beispielsweise den Metadatenwert authorization_endpoint (im Beispiel unten https://accounts.google.com/o/oauth2/v2/auth) als Basis-URI für Authentifizierungsanfragen abrufen, die an Google gesendet werden.

Im Folgenden finden Sie ein Beispiel für ein solches Dokument. Die Feldnamen entsprechen den in OpenID Connect Discovery 1.0 angegebenen Namen (ihre Bedeutungen 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 HTTP-Roundtrips vermeiden, indem Sie die Werte aus dem Discovery-Dokument im Cache speichern. Es werden Standard-HTTP-Caching-Header verwendet und müssen beachtet werden.

Clientbibliotheken

Die folgenden Clientbibliotheken vereinfachen die Implementierung von OAuth 2.0 durch die Einbindung in gängige Frameworks:

OpenID Connect-Compliance

Das OAuth 2.0-Authentifizierungssystem von Google unterstützt die erforderlichen Funktionen der Spezifikation OpenID Connect Core. Jeder Client, der für die Arbeit mit OpenID Connect entwickelt wurde, sollte mit diesem Dienst zusammenarbeiten (mit Ausnahme des OpenID-Anfrageobjekts).

OpenID Connect

OAuth 2.0 einrichten

OAuth 2.0-Anmeldedaten abrufen

Weiterleitungs-URI festlegen

Bildschirm für die Nutzereinwilligung anpassen

Auf den Dienst zugreifen

Nutzer authentifizieren

Serverablauf

1. Anti-Fälschungstoken erstellen

PHP

Java

Python

2. Authentifizierungsanfrage an Google senden

3. Anti-Fälschungsstatus-Token bestätigen

PHP

Java

Python

4. code gegen Zugriffstoken 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 Zugriffstoken und ID-Token austauschen