Diese Seite wurde von der Cloud Translation API übersetzt.

OpenID Connect

Die OAuth 2.0 APIs von Google können zur Authentifizierung und Autorisierung verwendet werden. In diesem Dokument wird die OAuth 2.0-Implementierung für die Authentifizierung beschrieben, die der OpenID Connect-Spezifikation entspricht und OpenID-zertifiziert ist. Die Dokumentation unter OAuth 2.0 für den Zugriff auf Google APIs verwenden gilt auch für diesen Dienst. Wenn Sie sich dieses Protokoll interaktiv ansehen möchten, empfehlen wir den Google OAuth 2.0 Playground. Wenn Sie Hilfe bei Stack Overflow benötigen, taggen Sie Ihre Fragen mit "google-oauth".

OAuth 2.0 einrichten

Bevor Ihre Anwendung das OAuth 2.0-Authentifizierungssystem von Google für die Nutzeranmeldung verwenden kann, müssen Sie ein Projekt im Google API Console einrichten, um OAuth 2.0-Anmeldedaten abzurufen, einen Weiterleitungs-URI festzulegen und (optional) die Branding-Informationen anzupassen, die Ihre Nutzer auf dem Bildschirm zur Nutzereinwilligung sehen. Sie können API Console auch verwenden, um ein Dienstkonto zu erstellen, die Abrechnung zu aktivieren, die Filterung einzurichten und andere Aufgaben zu erledigen. Weitere Informationen finden Sie in der Google API Console-Hilfe.

OAuth 2.0-Anmeldedaten abrufen

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

Klicken Sie auf den folgenden Text, um die Client-ID und das Client-Geheimnis für einen bestimmten OAuth 2.0-Berechtigungsnachweis anzuzeigen: Wählen Sie den Berechtigungsnachweis aus . Wählen Sie im folgenden Fenster Ihr Projekt und die gewünschten Anmeldeinformationen aus und klicken Sie dann auf Anzeigen .

Oder zeigen Sie Ihre Client-ID und Ihr Client-Geheimnis auf der Seite Anmeldeinformationen in API Console :

Go to the Credentials page.
Klicken Sie auf den Namen Ihres Berechtigungsnachweises oder auf das Stiftsymbol ( ). Ihre Kunden-ID und Ihr Geheimnis befinden sich oben auf der Seite.

Weiterleitungs-URI festlegen

Der Weiterleitungs-URI, den du in der API Console festgelegt hast, bestimmt, wohin Google Antworten auf deine Authentifizierungsanfragen sendet.

Gehen Sie wie folgt vor, um die Umleitungs-URIs für einen bestimmten OAuth 2.0-Berechtigungsnachweis zu erstellen, anzuzeigen oder zu bearbeiten:

Go to the Credentials page.
Klicken Sie im Abschnitt OAuth 2.0-Client-IDs der Seite auf einen Berechtigungsnachweis.
Anzeigen oder Bearbeiten der Umleitungs-URIs.

Wenn auf der Seite Anmeldeinformationen kein Abschnitt zu OAuth 2.0-Client-IDs vorhanden ist, verfügt Ihr Projekt über keine OAuth-Anmeldeinformationen. Um einen zu erstellen, klicken Sie auf Anmeldeinformationen erstellen .

Zustimmungsbildschirm für Nutzer anpassen

Für Ihre Nutzer umfasst die OAuth 2.0-Authentifizierung einen Zustimmungsbildschirm, auf dem die von dem Nutzer freigegebenen Informationen und die geltenden Bedingungen beschrieben werden. Wenn sich ein Nutzer anmeldet, wird er beispielsweise aufgefordert, Ihrer App Zugriff auf seine E-Mail-Adresse und grundlegende Kontoinformationen zu geben. Mit dem Parameter scope fordern Sie Zugriff auf diese Informationen an. Er wird in die Authentifizierungsanfrage Ihrer Anwendung aufgenommen. Sie können Bereiche auch verwenden, um den Zugriff auf andere Google APIs anzufordern.

Der Bildschirm zur Nutzereinwilligung enthält auch Markeninformationen wie deinen Produktnamen, dein Logo und eine Startseiten-URL. Die Markeninformationen werden über die API Consoleverwaltet.

So aktivieren Sie den Zustimmungsbildschirm Ihres Projekts:

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

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

Screenshot der Seite „Einwilligungsseite“

Auf den Dienst zugreifen

Google und Drittanbieter stellen Bibliotheken zur Verfügung, mit denen Sie viele der Implementierungsdetails zum Authentifizieren von Nutzern und zum Zugriff auf Google APIs verwalten können. Beispiele hierfür sind Google Identity Services und die Google-Clientbibliotheken, die auf einer Vielzahl von Plattformen verfügbar sind.

Wenn Sie keine Bibliothek verwenden, folgen Sie der Anleitung im restlichen Dokument, in der die HTTP-Anfrageflüsse beschrieben werden, die den verfügbaren Bibliotheken zugrunde liegen.

Nutzer authentifizieren

Zum Authentifizieren des Nutzers müssen Sie ein ID-Token abrufen und validieren. ID-Tokens sind eine standardisierte Funktion von OpenID Connect, die für die Freigabe von Identitätsbestätigungen im Internet entwickelt wurde.

Die am häufigsten verwendeten Ansätze zur Authentifizierung eines Nutzers und zum Abrufen eines ID-Tokens werden als Server- und impliziter Ablauf bezeichnet. Über den Serverfluss kann der Back-End-Server einer Anwendung die Identität der Person mithilfe eines Browsers oder eines Mobilgeräts überprüfen. Der implizite Ablauf wird verwendet, wenn eine clientseitige Anwendung (normalerweise eine im Browser ausgeführte JavaScript-Anwendung) direkt auf APIs und nicht über ihren Back-End-Server zugreifen muss.

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

Serverfluss

Richten Sie Ihre Anwendung in der API Consoleein, damit diese Protokolle verwendet und Ihre Nutzer authentifiziert werden können. Wenn ein Nutzer versucht, sich über Google anzumelden, müssen Sie Folgendes tun:

Anti-Fälschungs-Statustoken erstellen
Authentifizierungsanfrage an Google senden
Token zur Bestätigung der Fälschungsstatus bestätigen
Exchange code für Zugriffstoken und ID-Token austauschen
Nutzerinformationen aus dem ID-Token abrufen
Nutzer authentifizieren

1. Fälschungsschutztoken erstellen

Sie müssen die Sicherheit Ihrer Nutzer schützen, indem Sie Fälschungsangriffe verhindern. Im ersten Schritt wird ein eindeutiges Sitzungstoken erstellt, das den Status zwischen der Anwendung und dem Client des Nutzers enthält. Später stimmen Sie dieses eindeutige Sitzungstoken mit der Authentifizierungsantwort ab, die vom Google OAuth-Anmeldedienst zurückgegeben wird, um zu bestätigen, dass der Nutzer die Anfrage stellt und kein böswilliger Angreifer. Diese Tokens werden häufig als CSRF-Tokens (Cross-Site Request Forgery) bezeichnet.

Eine gute Wahl für ein Zustandstoken ist ein String mit etwa 30 Zeichen, der mit einem hochwertigen Zufallszahlgenerator erstellt wird. Ein weiterer Hash wird generiert, indem einige Ihrer Sitzungsstatusvariablen mit einem Schlüssel signiert werden, der im Back-End geheim gehalten wird.

Der folgende Code zeigt, wie eindeutige Sitzungstokens generiert werden.

PHP

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

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

Java

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

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

Python

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

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

2. Authentifizierungsanfrage an Google senden

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

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

client_id, die Sie über API ConsoleCredentials pageabrufen.
response_type, die in einer grundlegenden Anfrage für einen Autorisierungscode code sein sollte. Weitere Informationen finden Sie unter response_type.
scope, die in einer einfachen Anfrage openid email sein sollte. Weitere Informationen finden Sie unter scope.
redirect_uri sollte der HTTP-Endpunkt auf Ihrem Server sein, der die Antwort von Google empfängt. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie in API ConsoleCredentials pagekonfiguriert haben. Wenn dieser Wert nicht mit einem autorisierten URI übereinstimmt, schlägt die Anfrage mit dem Fehler redirect_uri_mismatch fehl.
state sollte den Wert des eindeutigen Fälschungssicherungstokens sowie alle anderen Informationen enthalten, die zum Wiederherstellen des Kontextes erforderlich sind, wenn der Nutzer zu Ihrer Anwendung zurückkehrt, z.B. die Start-URL. Weitere Informationen finden Sie unter state.
nonce ist ein zufälliger Wert, der von Ihrer App generiert wird und den Wiederholungsschutz aktiviert, falls vorhanden.
login_hint kann die E-Mail-Adresse des Nutzers oder der String sub sein, der der Google-ID des Nutzers entspricht. Wenn du kein login_hint angibst und der Nutzer aktuell angemeldet ist, enthält der Zustimmungsbildschirm eine Genehmigungsanfrage, damit die E-Mail-Adresse des Nutzers für deine App freigegeben werden kann. Weitere Informationen findest du unter login_hint.
Verwenden Sie den Parameter hd, um den OpenID Connect-Ablauf für Nutzer einer bestimmten Domain zu optimieren, die einer Google Cloud-Organisation zugeordnet ist. Weitere Informationen finden Sie unter hd.

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

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

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

3. Bestätigung der Fälschungsstatus

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

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

Auf dem Server müssen Sie prüfen, ob state von Google mit dem Sitzungstoken übereinstimmt, das Sie in Schritt 1 erstellt haben. Mit dieser Umlaufbestätigung wird sichergestellt, dass der Nutzer kein schädliches Skript sendet.

Der folgende Code zeigt die Bestätigung der Sitzungstokens, die Sie in Schritt 1 erstellt haben:

PHP

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

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Java

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

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Python

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

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

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

Die Antwort enthält einen code-Parameter, einen einmaligen Autorisierungscode, den Ihr Server gegen ein Zugriffstoken und ein ID-Token austauschen kann. Ihr Server führt diesen Austausch durch, indem er eine HTTPS-POST-Anfrage sendet. Die POST-Anfrage wird an den Tokenendpunkt gesendet, den Sie mithilfe des Metadatenwerts token_endpoint aus dem Discovery-Dokument abrufen sollten. In der folgenden Diskussion wird davon ausgegangen, dass der Endpunkt https://oauth2.googleapis.com/token ist. Die Anfrage muss die folgenden Parameter im Text POST enthalten:

Felder
`code`	Der Autorisierungscode, der von der ursprünglichen Anfrage zurückgegeben wurde.
`client_id`	Die Client-ID, die du von API ConsoleCredentials pageerhältst, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben.
`client_secret`	Den Clientschlüssel, den du aus API ConsoleCredentials pageerhältst, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben.
`redirect_uri`	Ein autorisierter Weiterleitungs-URI für die angegebene `client_id` im Credentials pageder API Console, wie unter Weiterleitungs-URI festlegen beschrieben.
`grant_type`	Dieses Feld muss den Wert `authorization_code` enthalten, wie in der OAuth 2.0-Spezifikation definiert.

Die tatsächliche Anfrage könnte so aussehen:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

Eine erfolgreiche Antwort auf diese Anfrage enthält die folgenden Felder in einem JSON-Array:

Felder
`access_token`	Ein Token, das an eine Google API gesendet werden kann.
`expires_in`	Die verbleibende Lebensdauer des Zugriffstokens in Sekunden.
`id_token`	Ein JWT mit Identitätsinformationen zum Nutzer, die von Google digital signiert sind.
`scope`	Der von `access_token` gewährte Zugriffsbereich, ausgedrückt als Liste von Strings, bei denen die Leerzeichen durch Leerzeichen getrennt sind.
`token_type`	Gibt den zurückgegebenen Tokentyp an. Derzeit hat dieses Feld immer den Wert `Bearer`.
`refresh_token`	(optional) Dieses Feld ist nur vorhanden, wenn der Parameter `access_type` in der Authentifizierungsanfrage auf `offline` gesetzt wurde. Weitere Informationen

5. Nutzerinformationen aus dem ID-Token abrufen

Ein ID-Token ist ein JWT (JSON-Webtoken), also ein kryptografisch signiertes Base64-codiertes JSON-Objekt. Normalerweise ist es wichtig, dass Sie ein ID-Token vor der Verwendung validieren. Da Sie jedoch direkt über einen zwischengeschalteten HTTPS-Kanal mit Google kommunizieren und sich mit Ihrem Clientschlüssel bei Google authentifizieren, können Sie sicher sein, dass das Token, das Sie erhalten, tatsächlich von Google stammt und gültig ist. Wenn Ihr Server das ID-Token an andere Komponenten Ihrer Anwendung weitergibt, ist es sehr wichtig, dass die anderen Komponenten das Token validieren, bevor Sie es verwenden.

Da die meisten API-Bibliotheken die Validierung mit der Decodierung der base64url-codierten Werte und der darin enthaltenen JSON-Datei kombinieren, werden Sie wahrscheinlich das Token validieren, wenn Sie die Anforderungen im ID-Token aufrufen.

Nutzlast eines ID-Tokens

Ein ID-Token ist ein JSON-Objekt mit einer Reihe von Name/Wert-Paaren. Hier ein Beispiel zur besseren Lesbarkeit:

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "jsmith@example.com",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

Google-ID-Tokens können die folgenden Felder enthalten (sogenannte claims):

Anspruch erheben	Bereitgestellt	Beschreibung
`aud`	immer	Die Zielgruppe, für die dieses ID-Token bestimmt ist. Dies muss eine der OAuth 2.0-Client-IDs Ihrer Anwendung sein.
`exp`	immer	Ablaufzeit, ab dem das ID-Token nicht akzeptiert werden darf. Wird in Unix-Zeit (ganzzahlige Sekunden) dargestellt.
`iat`	immer	Der Zeitpunkt, zu dem das ID-Token ausgestellt wurde. Wird in Unix-Zeit (ganzzahlige Sekunden) dargestellt.
`iss`	immer	Die Aussteller-ID für den Aussteller der Antwort. Immer `https://accounts.google.com` oder `accounts.google.com` für Google-ID-Tokens.
`sub`	immer	Eine Kennung für den Nutzer, die unter allen Google-Konten eindeutig ist und nie wiederverwendet wird. Ein Google-Konto kann mehrere E-Mail-Adressen zu verschiedenen Zeitpunkten haben. Der `sub`-Wert bleibt jedoch unverändert. Verwende `sub` in deiner Anwendung als eindeutige Kennung für den Nutzer. Maximale Länge von 255 ASCII-Zeichen, bei denen Groß- und Kleinschreibung berücksichtigt wird.
`at_hash`		Zugriffstoken-Hash. Validierung, dass das Zugriffstoken an das Identitätstoken gebunden ist. Wenn das ID-Token im Serverablauf mit einem `access_token`-Wert ausgegeben wird, ist diese Anforderung immer enthalten. Diese Anforderung kann als alternativer Mechanismus zum Schutz vor websiteübergreifenden Anfragefälschungsangriffen verwendet werden. Wenn Sie jedoch Schritt 1 und Schritt 3 ausführen, ist es nicht erforderlich, das Zugriffstoken zu überprüfen.
`azp`		Die `client_id` des autorisierten Moderators. Diese Anforderung ist nur erforderlich, wenn die Partei, die das ID-Token anfordert, nicht mit der Zielgruppe des ID-Tokens übereinstimmt. Dies ist beispielsweise bei Hybrid-Apps der Fall, wenn eine Webanwendung und eine Android-App ein anderes OAuth 2.0-`client_id` haben, aber dasselbe Google APIs-Projekt nutzen.
`email`		Die E-Mail-Adresse des Nutzers. Dieser Wert ist möglicherweise nicht eindeutig für diesen Nutzer und kann nicht als Primärschlüssel verwendet werden. Nur angegeben, wenn Ihr Bereich den Bereichswert `email` enthält.
`email_verified`		Dieser Wert ist „True“, wenn die E-Mail-Adresse des Nutzers bestätigt wurde, andernfalls „False“.
`family_name`		Nachname(n) des Nutzers Kann angegeben werden, wenn ein `name`-Anspruch vorhanden ist.
`given_name`		Der Vorname oder der Vorname des Nutzers. Kann angegeben werden, wenn ein `name`-Anspruch vorhanden ist.
`hd`		Die mit der Google Cloud-Organisation des Nutzers verknüpfte Domain. Nur angegeben, wenn der Nutzer einer Google Cloud-Organisation gehört.
`locale`		Die Sprache des Nutzers, dargestellt durch ein BCP 47-Sprachtag. Kann angegeben werden, wenn ein `name`-Anspruch vorhanden ist.
`name`		Der vollständige Name des Nutzers in einem Format, das angezeigt werden kann. Kann angegeben werden, wenn: Der Anfragebereich enthielt den String „profile“. Das ID-Token wird von einer Tokenaktualisierung zurückgegeben. Wenn `name`-Ansprüche vorhanden sind, kannst du sie zum Aktualisieren der Nutzerdaten deiner App verwenden. Dieser Anspruch ist nie garantiert.
`nonce`		Der Wert von `nonce`, der von Ihrer App in der Authentifizierungsanfrage angegeben wurde. Sie sollten den Schutz vor Wiederholungsangriffen durchsetzen, indem Sie sicherstellen, dass er nur einmal präsentiert wird.
`picture`		Die URL des Profilbilds des Nutzers. Kann angegeben werden, wenn: Der Anfragebereich enthielt den String „profile“. Das ID-Token wird von einer Tokenaktualisierung zurückgegeben. Wenn `picture`-Ansprüche vorhanden sind, kannst du sie zum Aktualisieren der Nutzerdaten deiner App verwenden. Dieser Anspruch ist nie garantiert.
`profile`		Die URL der Profilseite des Nutzers. Kann angegeben werden, wenn: Der Anfragebereich enthielt den String „profile“. Das ID-Token wird von einer Tokenaktualisierung zurückgegeben. Wenn `profile`-Ansprüche vorhanden sind, kannst du sie zum Aktualisieren der Nutzerdaten deiner App verwenden. Dieser Anspruch ist nie garantiert.

6. Nutzer authentifizieren

Nachdem Sie Nutzerinformationen aus dem ID-Token abgerufen haben, sollten Sie die Nutzerdatenbank Ihrer App abfragen. Wenn der Nutzer bereits in Ihrer Datenbank vorhanden ist, sollten Sie eine Anwendungssitzung für diesen Nutzer starten, wenn alle Anmeldeanforderungen von der Google API-Antwort erfüllt werden.

Wenn der Nutzer nicht in Ihrer Nutzerdatenbank vorhanden ist, sollten Sie den Nutzer zu Ihrem Registrierungsvorgang für neue Nutzer weiterleiten. Möglicherweise können Sie den Nutzer anhand der Informationen, die Sie von Google erhalten, automatisch registrieren. Es ist aber auch möglich, dass Sie viele der Felder, die Sie für Ihr Anmeldeformular benötigen, vorab ausfüllen. Zusätzlich zu den Informationen im ID-Token können Sie an unseren Endpunkten weitere Nutzerprofilinformationen abrufen.

Themen für Fortgeschrittene

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

Zugriff auf andere Google APIs

Einer der Vorteile von OAuth 2.0 für die Authentifizierung besteht darin, dass deine Anwendung während der Authentifizierung des Nutzers die Berechtigung erhält, andere Google APIs im Namen des Nutzers (z. B. YouTube, Google Drive, Google Kalender oder Kontakte) gleichzeitig zu verwenden. Fügen Sie dazu die anderen benötigten Bereiche in die Authentifizierungsanfrage ein, die Sie an Google senden. Wenn Sie der Authentifizierungsanfrage beispielsweise die Altersgruppe des Nutzers hinzufügen möchten, übergeben Sie den Bereichsparameter openid email https://www.googleapis.com/auth/profile.agerange.read. Der Nutzer wird auf dem Zustimmungsbildschirm entsprechend aufgefordert. Mit dem Zugriffstoken, das Sie von Google zurückerhalten, können Sie auf alle APIs zugreifen, die mit den angeforderten und den erteilten Zugriffsbereichen in Zusammenhang stehen.

Aktualisierungstokens

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

Wichtige Hinweise:

Bewahren Sie das Aktualisierungstoken sicher und dauerhaft auf, da Sie ein Aktualisierungstoken nur beim ersten Ausführen des Codeaustauschs erhalten können.
Die Anzahl der ausgegebenen Aktualisierungstokens ist begrenzt: ein Limit pro Client/Nutzer-Kombination und ein weiteres pro Nutzer für alle Clients. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, können diese Limits erreicht werden. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.

Weitere Informationen finden Sie unter Zugriffstoken aktualisieren (Offlinezugriff).

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

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

Authentifizierungs-URI-Parameter

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

Parameter	Erforderlich	Beschreibung
`client_id`	(Erforderlich)	Der Client-ID-String, den du aus API ConsoleCredentials pageerhältst, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben.
`nonce`	(Erforderlich)	Ein zufälliger Wert, der von Ihrer App generiert wird und den Replay-Schutz aktiviert.
`response_type`	(Erforderlich)	Wenn der Wert `code` ist, wird ein Ablauf mit grundlegendem Autorisierungscode gestartet. Dabei muss `POST` an den Tokenendpunkt gesendet werden, um die Tokens zu erhalten. Wenn der Wert `token id_token` oder `id_token token` ist, wird ein Impliziter Ablauf gestartet. Dabei muss JavaScript beim Weiterleitungs-URI verwendet werden, um Tokens aus der URI `#fragment`-Kennung abzurufen.
`redirect_uri`	(Erforderlich)	Legt fest, wohin die Antwort gesendet wird. Der Wert dieses Parameters muss genau mit einem der autorisierten Weiterleitungswerte übereinstimmen, die Sie im API Console- Credentials page festgelegt haben (einschließlich HTTP- oder HTTPS-Schema, Fall und nachgestelltem „/“, falls vorhanden).
`scope`	(Erforderlich)	Der Umfangsparameter muss mit dem Wert `openid` beginnen und dann den Wert `profile` und/oder den Wert `email` enthalten. Wenn der Bereichswert `profile` vorhanden ist, enthält das ID-Token unter Umständen (aber nicht garantiert) die standardmäßigen `profile`-Ansprüche des Nutzers. Wenn der Bereichswert `email` vorhanden ist, enthält das ID-Token die Anforderungen `email` und `email_verified`. Neben diesen OpenID-spezifischen Bereichen kann Ihr Bereichsargument auch andere Bereichswerte enthalten. Alle Bereichswerte müssen durch Leerzeichen getrennt sein. Wenn Sie beispielsweise pro Dateizugriff auf das Google Drive-Konto eines Nutzers zugreifen möchten, könnte der Bereichsparameter `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, aber sehr empfehlenswert)	Ein intransparenter String, der im Protokoll einen Round-Trip enthält, d. h., er wird als URI-Parameter im einfachen Ablauf und in der URI-ID `#fragment` im Impliziten Ablauf zurückgegeben. Die `state` kann zum Korrelieren von Anfragen und Antworten nützlich sein. Da sich die `redirect_uri` erraten lässt, können Sie mit einem `state`-Wert die Sicherheit erhöhen, dass eine eingehende Verbindung das Ergebnis einer Authentifizierungsanfrage ist, die von Ihrer Anwendung initiiert wurde. Wenn Sie in dieser `state`-Variable einen Zufallsstring generieren oder den Hash eines Clientstatus (z.B. ein Cookie) codieren, können Sie die Antwort zusätzlich validieren, damit die Anfrage und die Antwort im selben Browser stammen. Dies bietet Schutz vor Angriffen wie der websiteübergreifenden Anfragefälschung.
`access_type`	(Optional)	Zulässige Werte sind `offline` und `online`. Der Effekt ist unter Offlinezugriff dokumentiert. Wenn ein Zugriffstoken angefordert wird, erhält der Client nur dann ein Aktualisierungstoken, wenn der Wert `offline` angegeben ist.
`display`	(Optional)	Ein ASCII-Stringwert, der angibt, wie der Autorisierungsserver die Authentifizierungs- und Einwilligungsseiten anzeigt. Die folgenden Werte werden von den Google-Servern angegeben und akzeptiert, haben aber keinen Einfluss auf ihr Verhalten: `page`, `popup`, `touch` und `wap`.
`hd`	(Optional)	Die Anmeldung von Konten einer Google Cloud-Organisation optimieren. Durch das Einbinden der Google Cloud-Organisationsdomain (z. B. `mycollege.edu`) können Sie angeben, dass die UI für die Kontoauswahl für Konten in dieser Domain optimiert werden soll. Wenn Sie die Optimierung für Google Cloud-Organisationskonten statt nur einer Google Cloud-Organisationsdomain vornehmen möchten, legen Sie einen Sternchenwert (``) fest: `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. Prüfen Sie unbedingt, ob das zurückgegebene ID-Token einen `hd`-Anforderungswert hat, der Ihren Erwartungen entspricht (z.B. `mycolledge.edu`). Im Gegensatz zum Anfrageparameter ist die ID-Token-Anfrage `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 ist und die Autorisierungsanfrage genehmigt wurde, umfasst die Autorisierung alle vorherigen Autorisierungen, die dieser Kombination aus Nutzer und Anwendung für andere Bereiche zugewiesen wurden. Weitere Informationen finden Sie unter Inkrementelle Autorisierung. Beachten Sie, dass Sie mit dem Ablauf für installierte Anwendungen keine inkrementelle Autorisierung durchführen können.
`login_hint`	(Optional)	Wenn die Anwendung weiß, welchen Nutzer sie authentifizieren möchte, kann sie den Parameter als Hinweis für den Authentifizierungsserver bereitstellen. Wenn Sie diesen Hinweis weitergeben, wird die Kontoauswahl unterdrückt und das E-Mail-Feld auf dem Anmeldeformular vorausgefüllt oder die richtige Sitzung ausgewählt (wenn der Nutzer die Mehrfachanmeldung verwendet). So können Sie Probleme vermeiden, die auftreten, wenn Ihre Anwendung im falschen Nutzerkonto angemeldet ist. Der Wert kann entweder eine E-Mail-Adresse oder der String `sub` sein, der der Google-ID des Nutzers entspricht.
`prompt`	(Optional)	Eine durch Leerzeichen getrennte Liste von Stringwerten, die angibt, ob der Autorisierungsserver den Nutzer zur erneuten Authentifizierung und zur Einwilligung auffordert. Mögliche Werte sind: `none` Der Autorisierungsserver zeigt keine Authentifizierungs- oder Nutzereinwilligungsbildschirme an. Wenn der Nutzer nicht bereits authentifiziert ist und für die angeforderten Bereiche keine vorkonfigurierte Einwilligung vorliegt, wird ein Fehler zurückgegeben. Mit `none` können Sie die vorhandene Authentifizierung und/oder Einwilligung prüfen. `consent` Der Autorisierungsserver fordert den Nutzer zur Einwilligung auf, bevor Informationen an den Client zurückgegeben werden. `select_account` Der Autorisierungsserver fordert den Nutzer auf, ein Nutzerkonto auszuwählen. Dadurch kann ein Nutzer, der mehrere Konten auf dem Autorisierungsserver hat, aus mehreren Konten auswählen, für die er möglicherweise aktuelle Sitzungen hat. Wenn kein Wert angegeben ist und der Nutzer zuvor keinen autorisierten Zugriff hat, wird dem Nutzer ein Zustimmungsbildschirm angezeigt.

ID-Token prüfen

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

In den folgenden Fällen senden Sie ID-Tokens häufig an Ihren Server:

ID-Tokens mit Anfragen senden, die authentifiziert werden müssen Die ID-Tokens teilen Ihnen mit, welcher Nutzer die Anfrage gesendet hat und welchem Client dieses ID-Token zugewiesen wurde.

ID-Tokens sind vertraulich und können missbraucht werden, wenn sie abgefangen werden. Sie müssen für eine sichere Verarbeitung dieser Tokens sorgen, indem Sie sie nur über HTTPS und nur über POST-Daten oder in Anfrageheadern übertragen. Wenn Sie ID-Tokens auf Ihrem Server speichern, müssen Sie sie ebenfalls sicher speichern.

Hilfreiche ID-Tokens sind unter anderem, dass sie an verschiedene Komponenten Ihrer Anwendung weitergegeben werden können. Diese Komponenten können ein ID-Token als einfachen Authentifizierungsmechanismus verwenden, mit dem die Anwendung und der Nutzer authentifiziert werden. Bevor Sie die Informationen im ID-Token verwenden oder sich darauf verlassen können, dass der Nutzer authentifiziert wurde, müssen Sie ihn validieren.

Die Validierung eines ID-Tokens erfordert mehrere Schritte:

Prüfen Sie, ob das ID-Token vom Aussteller ordnungsgemäß signiert ist. Von Google ausgestellte Tokens werden mit einem der Zertifikate signiert, die unter dem im jwks_uri-Metadatenwert des Discovery-Dokuments angegebenen URI gefunden werden.
Prüfe, ob der Wert der iss-Anforderung im ID-Token dem Wert https://accounts.google.com oder accounts.google.com entspricht.
Prüfe, ob der Wert der aud-Anforderung im ID-Token mit der Client-ID deiner App übereinstimmt.
Achten Sie darauf, dass die Ablaufzeit (exp-Anforderung) des ID-Tokens nicht abgelaufen ist.
Wenn Sie in der Anfrage einen hd-Parameterwert angegeben haben, prüfen Sie, ob das ID-Token eine hd-Anforderung hat, die einer akzeptierten Domain entspricht, die mit einer Google Cloud-Organisation verknüpft ist.

In den Schritten 2 bis 5 werden nur String- und Datumsvergleiche vorgenommen, die ziemlich einfach sind. Daher werden sie hier nicht beschrieben.

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

Der Endpunkt tokeninfo ist nützlich für die Fehlerbehebung. Für Produktionszwecke sollten Sie jedoch die öffentlichen Schlüssel von Google aus dem Schlüsselendpunkt abrufen und die Validierung lokal ausführen. Sie sollten den Schlüssel-URI aus dem Discovery-Dokument mithilfe des Metadatenwerts jwks_uri abrufen. Anfragen an den Debugging-Endpunkt können gedrosselt werden oder auf andere Weise zeitweise Fehler verursachen.

Da Google seine öffentlichen Schlüssel nur selten ändert, können Sie diese mit den Cache-Anweisungen der HTTP-Antwort im Cache speichern. In den meisten Fällen ist eine lokale Validierung viel effizienter als mit dem Endpunkt tokeninfo. Diese Validierung erfordert das Abrufen und Parsen von Zertifikaten und das Ausführen der entsprechenden kryptografischen Aufrufe zum Prüfen der Signatur. Glücklicherweise stehen in diesem Zusammenhang Bibliotheken mit vielen Fehlern und verschiedenen Sprachen zur Verfügung. Weitere Informationen finden Sie unter jwt.io.

Nutzerprofilinformationen abrufen

Sie können das Zugriffstoken (das Ihre Anwendung während des Authentifizierungsvorgangs) und den OpenID Connect-Standard verwendet, um zusätzliche Profilinformationen zum Nutzer zu erhalten:

Damit die OpenID-konform ist, müssen Sie die openid profile-Bereichswerte in Ihre Authentifizierungsanfrage aufnehmen.

Wenn die E-Mail-Adresse des Nutzers enthalten sein soll, können Sie einen zusätzlichen Bereichswert von email angeben. Wenn Sie sowohl profile als auch email angeben möchten, können Sie den folgenden Parameter in den URI für die Authentifizierungsanfrage einfügen:
```
scope=openid%20profile%20email
```
Fügen Sie dem Autorisierungsheader Ihr Zugriffstoken hinzu und stellen Sie eine HTTPS-GET-Anfrage an den Endpunkt „userinfo“. Diesen sollten Sie mit dem Metadatenwert userinfo_endpoint aus dem Discovery-Dokument abrufen. Die Nutzerinfo-Antwort enthält Informationen über den Nutzer, wie in OpenID Connect Standard Claims und im claims_supported-Metadatenwert des Discovery-Dokuments beschrieben. Nutzer oder ihre Organisationen können bestimmte Felder angeben oder zurückhalten, sodass Sie möglicherweise nicht für jedes Feld Informationen zu Ihren autorisierten Zugriffsbereichen erhalten.

Das Discovery-Dokument

Für das OpenID Connect-Protokoll müssen mehrere Endpunkte zur Authentifizierung von Nutzern und zum Anfordern von Ressourcen wie Tokens, Nutzerinformationen und öffentlichen Schlüsseln verwendet werden.

Um die Implementierung zu vereinfachen und die Flexibilität zu erhöhen, ermöglicht OpenID Connect die Verwendung eines „Discovery-Dokuments“, eines JSON-Dokuments an einem bekannten Speicherort mit Schlüssel/Wert-Paaren, das Details zur Konfiguration des OpenID Connect-Anbieters enthält, einschließlich der URIs der Endpunkte für Autorisierung, Token, Widerruf, Nutzerinformationen und öffentliche Schlüssel. Das Discovery-Dokument für den OpenID Connect-Dienst von Google kann hier abgerufen werden:

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

Wenn Sie die OpenID Connect-Dienste von Google verwenden möchten, sollten Sie den Discovery-Dokument-URI (https://accounts.google.com/.well-known/openid-configuration) in Ihrer Anwendung hartcodieren. Ihre Anwendung ruft das Dokument ab, wendet Caching-Regeln in der Antwort an und ruft dann nach Bedarf Endpunkt-URIs ab. Zum Beispiel würde der Code zum Authentifizieren eines Nutzers den Metadatenwert authorization_endpoint (im Beispiel unten https://accounts.google.com/o/oauth2/v2/auth) als Basis-URI für Authentifizierungsanfragen abrufen, die an Google gesendet werden.

Hier ein Beispiel für ein solches Dokument. Die Feldnamen sind in OpenID Connect Discovery 1.0 angegeben. Die Werte dienen nur der Veranschaulichung und können sich ändern, obwohl sie aus einer aktuellen Version des aktuellen Google Discovery-Dokuments kopiert wurden:

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

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

Clientbibliotheken

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

OpenID Connect-Compliance

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

OpenID Connect

OAuth 2.0 einrichten

OAuth 2.0-Anmeldedaten abrufen

Weiterleitungs-URI festlegen

Zustimmungsbildschirm für Nutzer anpassen

Auf den Dienst zugreifen

Nutzer authentifizieren

Serverfluss

1. Fälschungsschutztoken erstellen

PHP

Java

Python

2. Authentifizierungsanfrage an Google senden

3. Bestätigung der Fälschungsstatus

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 prüfen

Nutzerprofilinformationen abrufen

Das Discovery-Dokument

Clientbibliotheken

OpenID Connect-Compliance

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