OpenID Connect

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

OAuth 2.0 einrichten

Bevor deine Anwendung das OAuth 2.0-Authentifizierungssystem von Google für die Nutzeranmeldung verwenden kann, musst du ein Projekt im Google API Console einrichten, um OAuth 2.0-Anmeldedaten abzurufen, einen Weiterleitungs-URI festzulegen und (optional) die Branding-Informationen anzupassen, die deinen Nutzern auf dem Bildschirm für die Nutzereinwilligung angezeigt werden. Sie können mit dem API Console auch ein Dienstkonto erstellen, die Abrechnung aktivieren, die Filterung einrichten und andere Aufgaben ausführen. Weitere Informationen finden Sie in der Google API Console-Hilfe.

OAuth 2.0-Anmeldedaten abrufen

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

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

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

  1. Go to the Credentials page.
  2. 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 den API Console festgelegt hast, bestimmt, wohin Google Antworten auf deine Authentifizierungsanfragen sendet.

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

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

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

Zustimmungsbildschirm für Nutzer anpassen

Die OAuth 2.0-Authentifizierung bietet Nutzern einen Zustimmungsbildschirm, in dem die Informationen beschrieben werden, die der Nutzer freigibt, sowie die geltenden Nutzungsbedingungen. Wenn sich der Nutzer anmeldet, wird er beispielsweise aufgefordert, Ihrer App Zugriff auf seine E-Mail-Adresse und grundlegende Kontoinformationen zu gewähren. Mit dem Parameter scope fordern Sie Zugriff auf diese Informationen an. Diesen Parameter nehmen Sie in die Authentifizierungsanfrage Ihrer App auf. Sie können mit Bereichen auch den Zugriff auf andere Google APIs anfordern.

Der Zustimmungsbildschirm für den Nutzer enthält auch Markeninformationen wie deinen Produktnamen, dein Logo und eine Startseiten-URL. Du verwaltest die Branding-Informationen in den API Console.

So aktivieren Sie den Zustimmungsbildschirm Ihres Projekts:

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

Der folgende Dialog zur Einholung von Einwilligungen zeigt, was ein Nutzer sehen würde, wenn in der Anfrage eine Kombination aus OAuth 2.0- und Google Drive-Bereichen vorhanden ist. (Dieses generische Dialogfeld wurde mit Google OAuth 2.0 Playground erstellt. Es enthält also keine Branding-Informationen, die in API Consolefestgelegt werden.)

Screenshot der Seite „Einwilligungsseite“

Auf den Dienst zugreifen

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

Wenn Sie keine Bibliothek verwenden möchten, folgen Sie der Anleitung im restlichen Dokument, in der die HTTP-Anfrageabläufe beschrieben werden, die den verfügbaren Bibliotheken zugrunde liegen.

Nutzer authentifizieren

Zum Authentifizieren des Nutzers müssen Sie ein ID-Token abrufen und validieren. ID-Tokens sind eine Standardfunktion von OpenID Connect, mit der Identitätsprüfungen im Internet geteilt werden können.

Die am häufigsten verwendeten Ansätze zum Authentifizieren eines Nutzers und zum Abrufen eines ID-Tokens werden als „Serverfluss“ und „impliziter“ Ablauf bezeichnet. Über den Serverfluss kann der Back-End-Server einer Anwendung die Identität der Person mit einem Browser oder Mobilgerät überprüfen. Der implizite Vorgang wird verwendet, wenn eine clientseitige Anwendung (in der Regel eine JavaScript-Anwendung, die im Browser ausgeführt wird) direkt auf APIs zugreifen muss, anstatt über den Back-End-Server.

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

Serverfluss

Achten Sie darauf, die Anwendung im API Console einzurichten, damit sie diese Protokolle verwenden und Ihre Nutzer authentifizieren kann. Wenn ein Nutzer versucht, sich über Google anzumelden, müssen Sie Folgendes tun:

  1. Anti-Fälschung-Token erstellen
  2. Authentifizierungsanfrage an Google senden
  3. Token für die Fälschungsstatus bestätigen
  4. Exchange code gegen Zugriffstoken und ID-Token
  5. Nutzerinformationen aus dem ID-Token abrufen
  6. Nutzer authentifizieren

1) Anti-Fälschung-Token erstellen

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

Eine gute Wahl für ein Statustoken ist ein String mit je 30 Zeichen, der mit einem hochwertigen Zufallsgenerator erstellt wird. Ein weiterer Hash, der durch das Signieren einiger Ihrer Sitzungsstatusvariablen mit einem Schlüssel generiert wird, der im Back-End geheim gehalten wird.

Im folgenden Code sehen Sie, wie eindeutige Sitzungstokens generiert werden.

PHP

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

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

Java

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

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

Python

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

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

2. Authentifizierungsanfrage an Google senden

Im nächsten Schritt wird eine GET-HTTPS-Anfrage mit den entsprechenden URI-Parametern erstellt. Bei allen Schritten dieses Vorgangs solltest du HTTPS statt HTTP verwenden. HTTP-Verbindungen werden abgelehnt. Sie sollten den Basis-URI mit dem Metadatenwert authorization_endpoint aus dem Discovery-Dokument abrufen. In der folgenden Diskussion wird davon ausgegangen, dass der Basis-URI https://accounts.google.com/o/oauth2/v2/auth ist.

Für eine grundlegende Anfrage geben Sie die folgenden Parameter an:

  • client_id, die Sie über API Console Credentials pageabrufen.
  • response_type, der in einer grundlegenden Autorisierungscode-Anfrage code lauten sollte. Weitere Informationen finden Sie unter response_type.
  • scope, was in einer grundlegenden Anfrage openid email lauten sollte. Weitere Informationen finden Sie unter scope.
  • redirect_uri sollte der HTTP-Endpunkt auf deinem Server sein, der die Antwort von Google erhält. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie in API Console Credentials pagekonfiguriert haben. Wenn dieser Wert nicht mit einem autorisierten URI übereinstimmt, schlägt die Anfrage mit dem Fehler redirect_uri_mismatch fehl.
  • state sollte den Wert des eindeutigen Fälschungstokens für die Sitzung sowie alle anderen Informationen enthalten, die zum Wiederherstellen des Kontextes erforderlich sind, wenn der Nutzer zu Ihrer Anwendung zurückkehrt, z.B. die Start-URL. Weitere Informationen finden Sie 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 Sie kein login_hint angeben und der Nutzer aktuell angemeldet ist, enthält der Zustimmungsbildschirm eine Genehmigungsanfrage, um die E-Mail-Adresse des Nutzers für Ihre App freizugeben. Weitere Informationen finden Sie unter login_hint.
  • Verwenden Sie den Parameter hd, um den OpenID Connect-Vorgang für Nutzer einer bestimmten Domain zu optimieren, die mit einer Google Cloud-Organisation verknüpft sind. Weitere Informationen finden Sie unter hd.

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

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

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

3. Bestätigung des Fälschungsstatus bestätigen

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

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

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

Im folgenden Code sehen Sie, wie Sie die in Schritt 1 erstellten Sitzungstokens bestätigen:

PHP

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

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

Java

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

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

Python

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

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

4. Exchange code gegen Zugriffstoken und ID-Token

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

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

Die tatsächliche Anfrage könnte so aussehen:

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

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

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

Felder
access_token Ein Token, das an eine Google API gesendet werden kann.
expires_in Die verbleibende Lebensdauer des Zugriffstokens in Sekunden.
id_token Ein JWT, das Identitätsinformationen über den Nutzer enthält, die von Google digital signiert wurden.
scope Die von access_token gewährten Zugriffsbereiche als Liste durch Leerzeichen getrennter Groß-/Kleinschreibung-Strings.
token_type Gibt den Typ des zurückgegebenen Tokens an. Derzeit hat dieses Feld immer den Wert Bearer.
refresh_token (optional)

Dieses Feld ist nur vorhanden, wenn der access_type-Parameter in der Authentifizierungsanfrage auf offline gesetzt wurde. Weitere Informationen finden Sie unter Aktualisierungstoken.

5. Nutzerinformationen aus dem ID-Token abrufen

Ein ID-Token ist ein JWT (JSON-Webtoken), also ein kryptografisch signiertes Base64-codiertes JSON-Objekt. Normalerweise ist es wichtig, dass du ein ID-Token vor deiner Verwendung prüfst. Da du jedoch direkt mit Google über einen HTTPS-Kanal zwischengeschaltet wirst und deinen Clientschlüssel zur Authentifizierung bei Google verwendest, kannst du sicher sein, dass das Token, das du erhältst, tatsächlich von Google stammt und gültig ist. Wenn dein Server das ID-Token an andere Komponenten deiner App weitergibt, ist es sehr wichtig, dass die anderen Komponenten das Token validieren, bevor du es verwendest.

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

Die Nutzlast eines ID-Tokens

Ein ID-Token ist ein JSON-Objekt, das eine Reihe von Name/Wert-Paaren enthält. Hier ein Beispiel zur Lesbarkeit:

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

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

Anspruch erheben Bereitgestellt Beschreibung
aud immer Die Zielgruppe, für die dieses ID-Token bestimmt ist. Dies muss eine der OAuth 2.0-Client-IDs Ihrer Anwendung sein.
exp immer Ablaufzeit am oder nach dem ID-Token. Wird in Unix-Zeit (ganzzahlige Sekunden) dargestellt.
iat immer Der Zeitpunkt, an dem das ID-Token ausgestellt wurde. Wird in Unix-Zeit (ganzzahlige Sekunden) dargestellt.
iss immer Die Aussteller-ID für den Aussteller der Antwort. Für Google-ID-Tokens immer https://accounts.google.com oder accounts.google.com.
sub immer Eine Kennung für den Nutzer, die unter allen Google-Konten eindeutig ist und nie wiederverwendet wird. Ein Google-Konto kann zu verschiedenen Zeitpunkten mehrere E-Mail-Adressen haben. Der sub-Wert wird jedoch nie geändert. Verwenden Sie sub in Ihrer Anwendung als eindeutigen Kennungsschlüssel für den Nutzer. Maximale Länge von 255 ASCII-Zeichen, bei denen die Groß- und Kleinschreibung berücksichtigt wird.
at_hash Zugriffstoken eines Zugriffstokens Überprüft, ob das Zugriffstoken mit dem Identitätstoken verknüpft ist. Wenn das ID-Token im Serverablauf mit einem access_token-Wert ausgegeben wird, ist dieser Anspruch immer enthalten. Dieser Anspruch kann als alternativer Mechanismus zum Schutz vor websiteübergreifenden Anfragefälschungsangriffen verwendet werden. Wenn Sie jedoch Schritt 1 und Schritt 3 ausführen, ist das Zugriffstoken nicht zu bestätigen.
azp client_id des autorisierten Vortragenden. Dieser Anspruch ist nur erforderlich, wenn die Partei, die das ID-Token anfordert, nicht mit der Zielgruppe des ID-Tokens übereinstimmt. Dies kann bei Google der Fall sein, wenn eine Webanwendung und eine Android-App ein anderes OAuth 2.0-client_id haben, aber dasselbe Google APIs-Projekt nutzen.
email Die E-Mail-Adresse des Nutzers. Dieser Wert ist möglicherweise für diesen Nutzer nicht eindeutig und kann nicht als Primärschlüssel verwendet werden. Wird nur angegeben, wenn Ihr Bereich den Wert email für den Geltungsbereich enthält.
email_verified Dieser Wert ist „true“, wenn die E-Mail-Adresse des Nutzers verifiziert wurde. Andernfalls lautet sie „false“.
family_name An- oder Nachnamen des Nutzers Kann angegeben werden, wenn ein name-Anspruch vorhanden ist.
given_name Den Vornamen oder den Vornamen des Nutzers Kann angegeben werden, wenn ein name-Anspruch vorhanden ist.
hd Die Domain, die der Google Cloud-Organisation des Nutzers zugeordnet ist. Wird nur angegeben, wenn der Nutzer einer Google Cloud-Organisation angehört.
locale Die Sprache des Nutzers, dargestellt durch ein BCP 47-Sprachtag. Kann angegeben werden, wenn ein name-Anspruch vorhanden ist.
name Der vollständige Name des Nutzers in einer anklickbaren Form. Kann in folgenden Fällen angegeben werden:
  • Der Anfragebereich enthielt den String „profile“
  • Das ID-Token wird bei einer Tokenaktualisierung zurückgegeben

Wenn name-Ansprüche vorhanden sind, kannst du damit die Nutzerdatensätze deiner App aktualisieren. Dieser Anspruch wird jedoch nicht garantiert.

nonce Der Wert von nonce, der von Ihrer App in der Authentifizierungsanfrage bereitgestellt wird. Sie sollten den Schutz vor Replay-Angriffen erzwingen, indem Sie dafür sorgen, dass sie nur einmal angezeigt werden.
picture Die URL des Profilbilds des Nutzers. Kann in folgenden Fällen angegeben werden:
  • Der Anfragebereich enthielt den String „profile“
  • Das ID-Token wird bei einer Tokenaktualisierung zurückgegeben

Wenn picture-Ansprüche vorhanden sind, kannst du damit die Nutzerdatensätze deiner App aktualisieren. Dieser Anspruch wird jedoch nicht garantiert.

profile Die URL der Profilseite des Nutzers. Kann in folgenden Fällen angegeben werden:
  • Der Anfragebereich enthielt den String „profile“
  • Das ID-Token wird bei einer Tokenaktualisierung zurückgegeben

Wenn profile-Ansprüche vorhanden sind, kannst du damit die Nutzerdatensätze deiner App aktualisieren. Dieser Anspruch wird jedoch nicht garantiert.

6. Nutzer authentifizieren

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

Wenn der Nutzer nicht in deiner Nutzerdatenbank vorhanden ist, solltest du ihn zum Registrierungsvorgang für neue Nutzer weiterleiten. Du kannst den Nutzer möglicherweise anhand der von Google erhaltenen Informationen automatisch registrieren oder zumindest viele der Felder ausfüllen, die du im Anmeldeformular benötigst. Zusätzlich zu den Informationen im ID-Token erhalten Sie weitere Nutzerprofilinformationen an unseren Nutzerprofilendpunkten.

Themen für Fortgeschrittene

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

Zugriff auf andere Google APIs

Einer der Vorteile von OAuth 2.0 für die Authentifizierung besteht darin, dass deine Anwendung zur Authentifizierung des Nutzers gleichzeitig die Berechtigung zur Nutzung anderer Google APIs (z. B. YouTube, Google Drive, Kalender oder Kontakte) erhalten kann. Fügen Sie dazu die erforderlichen Bereiche in die Authentifizierungsanfrage ein, die Sie an Google senden. Wenn Sie Ihrer Authentifizierungsanfrage beispielsweise die Altersgruppe des Nutzers hinzufügen möchten, übergeben Sie den Umfangsparameter openid email https://www.googleapis.com/auth/profile.agerange.read. Der Nutzer wird auf dem Zustimmungsbildschirm entsprechend aufgefordert. Mit dem Zugriffstoken, das Sie von Google erhalten, können Sie auf alle APIs zugreifen, die sich auf die angeforderten Bereiche beziehen und gewährt wurden.

Aktualisierungstokens

In Ihrem Antrag auf API-Zugriff können Sie die Aktualisierung eines Tokens beantragen, das während des code-Austauschs zurückgegeben wird. Mit einem Aktualisierungstoken kann Ihre Anwendung kontinuierlich auf Google APIs zugreifen, während der Nutzer in Ihrer Anwendung nicht vorhanden ist. Wenn Sie ein Aktualisierungstoken anfordern möchten, fügen Sie in Ihrer Authentifizierungsanfrage den Parameter access_type auf offline hinzu.

Wichtige Hinweise:

  • Bewahren Sie das Aktualisierungstoken sicher und dauerhaft auf, da Sie ein Aktualisierungstoken nur dann erhalten, wenn Sie den Codeaustausch zum ersten Mal ausführen.
  • Es gibt ein Limit für die Anzahl der Aktualisierungstokens: ein Limit pro Kombination aus Client und Nutzer und ein anderes pro Nutzer und alle Clients. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, kann das Limit erreicht werden. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.

Weitere Informationen finden Sie unter Zugriffstoken aktualisieren (Offlinezugriff).

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

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

Authentifizierungs-URI-Parameter

In der folgenden Tabelle finden Sie ausführlichere Beschreibungen der Parameter, die von der OAuth 2.0 Authentication API von Google akzeptiert werden.

Parameter Erforderlich Beschreibung
client_id (Erforderlich) Der Client-ID-String, den du von API Console Credentials pageerhältst, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben.
nonce (Erforderlich) Ein zufälliger Wert, der von Ihrer App generiert wird und den Replay-Schutz aktiviert.
response_type (Erforderlich) Wenn der Wert code ist, wird ein einfacher Autorisierungscode-Vorgang gestartet, der ein POST an den Tokenendpunkt erfordert, um die Tokens zu erhalten. Wenn der Wert token id_token oder id_token token lautet, wird ein Impliziter Ablauf gestartet. In diesem Fall müssen JavaScript im Weiterleitungs-URI verwendet werden, um Tokens aus der URI-ID #fragment abzurufen.
redirect_uri (Erforderlich) Legt fest, wohin die Antwort gesendet wird. Der Wert dieses Parameters muss genau mit einem der autorisierten Weiterleitungswerte übereinstimmen, die Sie im API Console- Credentials page festlegen, einschließlich des HTTP- oder HTTPS-Schemas, der Groß-/Kleinschreibung und des nachfolgenden Schrägstrichs „/“ (falls vorhanden).
scope (Erforderlich)

Der Umfangsparameter muss mit dem Wert openid beginnen und dann den Wert profile, den Wert email oder beides enthalten.

Wenn der Wert für den Bereich profile vorhanden ist, kann das ID-Token die standardmäßigen profile-Ansprüche des Nutzers enthalten. Das ist aber 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 Ihr Bereichsargument auch andere Bereichswerte enthalten. Alle Werte für den Bereich müssen durch Leerzeichen getrennt sein. Wenn Sie beispielsweise pro Datei Zugriff auf Google Drive eines Nutzers wünschen, kann Ihr Geltungsbereich-Parameter 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 zur gewünschten Google API.

state (Optional, aber dringend empfohlen)

Ein undurchsichtiger String, der im Protokoll als Roundtrip ausgegeben wird. Das heißt, er wird im einfachen Ablauf als URI-Parameter und im impliziten Ablauf als URI-ID #fragment zurückgegeben.

Der state kann zum Korrelieren von Anfragen und Antworten hilfreich sein. Da sich dein redirect_uri-Wert erraten lässt, kannst du mit einem state-Wert die Gewähr erhöhen, dass eine eingehende Verbindung das Ergebnis einer Authentifizierungsanfrage ist, die von deiner App initiiert wird. Wenn du in dieser state-Variable einen Zufallsstring generieren oder den Hash eines Clientstatus codieren kannst (z.B. ein Cookie), kannst du die Antwort zusätzlich validieren, damit die Anfrage und die Antwort vom selben Browser stammen. Dies bietet Schutz vor Angriffen wie der websiteübergreifenden Anfragefälschung.

access_type (Optional) Die zulässigen Werte sind offline und online. Der Effekt ist unter Offlinezugriff dokumentiert. Wenn ein Zugriffstoken angefordert wird, erhält der Client nur dann ein Aktualisierungstoken, wenn der Wert offline angegeben ist.
display (Optional) Ein ASCII-Stringwert, mit dem angegeben wird, wie der Autorisierungsserver die Seiten zur Authentifizierung und die Einwilligungsoberfläche anzeigt. Die folgenden Werte werden von den Google-Servern angegeben und akzeptiert, haben aber keinen Einfluss auf das Verhalten: page, popup, touch und wap.
hd (Optional)

Die Anmeldung für Konten optimieren, die einer Google Cloud-Organisation gehören. Wenn Sie die Google Cloud-Organisationsdomain einschließen (z. B. mycollege.edu), können Sie angeben, dass die Kontoauswahl-UI für Konten in dieser Domain optimiert werden soll. Wenn Sie Optimierungen für Google Cloud-Organisationskonten statt nur für eine Google Cloud-Organisationsdomain vornehmen möchten, legen Sie einen Wert für ein Sternchen (*) 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üfe, ob das zurückgegebene ID-Token einen Anspruchswert hd hat, der dem zu erwartenden Wert entspricht (z.B. mycolledge.edu). Im Gegensatz zum Anfrageparameter ist der Anspruch hd des ID-Tokens 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 wurde, enthält die Autorisierung alle vorherigen Autorisierungen, die dieser Nutzer/Anwendungskombination für andere Bereiche gewährt wurden. Weitere Informationen finden Sie unter Inkrementelle Autorisierung.

Beachten Sie, dass Sie mit dem Ablauf für installierte Anwendungen keine inkrementelle Autorisierung durchführen können.

login_hint (Optional) Wenn die Anwendung weiß, welchen Nutzer sie authentifizieren möchte, kann sie dem Parameter einen Hinweis auf den Authentifizierungsserver senden. Wenn Sie diesen Hinweis weitergeben, wird die Kontoauswahl unterdrückt und das E-Mail-Feld auf dem Anmeldeformular vorab ausgefüllt oder die richtige Sitzung ausgewählt (wenn der Nutzer die Mehrfachanmeldung verwendet). So können Sie Probleme vermeiden, die auftreten, wenn Ihre App im falschen Nutzerkonto protokolliert. Der Wert kann entweder eine E-Mail-Adresse oder der String sub sein, der der Google-ID des Nutzers entspricht.
prompt (Optional) Eine Liste mit durch Leerzeichen getrennten Stringwerten, die angibt, ob der Autorisierungsserver den Nutzer zur erneuten Authentifizierung und zur Einwilligung auffordert. Folgende Werte sind möglich:
  • none

    Der Autorisierungsserver zeigt keine Authentifizierungs- oder Nutzereinwilligungsbildschirme an. Wenn der Nutzer nicht bereits authentifiziert und für die angeforderten Bereiche keine Einwilligung konfiguriert hat, wird ein Fehler zurückgegeben. Mit none können Sie die 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 keinen zuvor autorisierten Zugriff hat, wird dem Nutzer ein Zustimmungsbildschirm angezeigt.

ID-Token prüfen

Du musst alle ID-Tokens auf deinem Server validieren, es sei denn, du weißt, dass sie direkt von Google stammen. Beispielsweise muss dein Server alle ID-Tokens, die er von deinen Client-Apps erhält, als authentisch bestätigen.

In den folgenden Fällen senden Sie ID-Tokens in der Regel an Ihren Server:

  • Senden von ID-Tokens mit Anfragen, die authentifiziert werden müssen. Die ID-Tokens zeigen den jeweiligen Nutzer, der die Anfrage stellt, und für welchen Client dieses ID-Token ausgestellt wurde.

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

Ein wichtiger Vorteil von ID-Tokens ist, dass du sie zwischen verschiedenen Komponenten deiner App übergeben kannst. Diese Komponenten können ein ID-Token als einfachen Authentifizierungsmechanismus verwenden, mit dem die App und der Nutzer authentifiziert werden. Bevor Sie die Informationen jedoch im ID-Token verwenden oder sich darauf verlassen können, dass der Nutzer sich authentifiziert hat, müssen Sie sie validieren.

Das Bestätigen eines ID-Tokens erfordert mehrere Schritte:

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

In den Schritten 2 bis 5 werden nur Strings und Datumsangaben verglichen, die recht einfach sind. Wir gehen hier also nicht näher darauf ein.

Der erste Schritt ist komplexer und erfordert eine kryptografische Signaturprüfung. Für die Fehlerbehebung kannst du den tokeninfo-Endpunkt von Google verwenden, um sie mit der auf deinem Server oder deinem Gerät implementierten lokalen Verarbeitung zu vergleichen. Angenommen, der Wert des ID-Tokens ist XYZ123. Entfernen Sie dann den URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Wenn die Tokensignatur gültig ist, ist die Antwort die JWT-Nutzlast in ihrer decodierten JSON-Objektform.

Der tokeninfo-Endpunkt ist für die Fehlerbehebung nützlich. Für Produktionszwecke sollten Sie jedoch die öffentlichen Google-Schlüssel aus dem Schlüsselendpunkt abrufen und die Validierung lokal ausführen. Sie sollten den Schlüssel-URI aus dem Discovery-Dokument mithilfe des Metadatenwerts jwks_uri abrufen. Anfragen an den Debug-Endpunkt können gedrosselt werden oder in anderer Weise vorübergehenden Fehlern ausgesetzt werden.

Da Google seine öffentlichen Schlüssel nur selten ändert, können Sie sie mit den Cache-Anweisungen der HTTP-Antwort im Cache speichern und in den meisten Fällen eine effizientere lokale Validierung ausführen als mit dem Endpunkt tokeninfo. Für diese Validierung müssen Zertifikate abgerufen und geparst werden und es müssen die entsprechenden kryptografischen Aufrufe durchgeführt werden, um die Signatur zu prüfen. Glücklicherweise gibt es für das Debugging in vielen verschiedenen Sprachen Debugging-Bibliotheken (siehe jwt.io).

Nutzerprofilinformationen abrufen

Sie können das Zugriffstoken, das Ihre Anwendung während des Authentifizierungsvorgangs erhält, und den OpenID Connect-Standard verwenden, um zusätzliche Profilinformationen über den Nutzer zu erhalten:

  1. Um OpenID-konform zu sein, müssen Sie in Ihre Authentifizierungsanfrage die Werte des Bereichs openid profile aufnehmen.

    Wenn Sie die E-Mail-Adresse des Nutzers einschließen möchten, können Sie einen zusätzlichen Wert für den Umfang email angeben. Wenn Sie sowohl profile als auch email angeben möchten, können Sie den folgenden Parameter in den URI Ihrer Authentifizierungsanfrage einfügen:

    scope=openid%20profile%20email
  2. Fügen Sie dem Autorisierungsheader das Zugriffstoken hinzu und stellen Sie eine HTTPS-GET-Anfrage an den Endpunkt des Nutzerinformationens. Diese sollten Sie aus dem Discovery-Dokument mit dem Metadatenwert userinfo_endpoint abrufen. Die Antwort „userinfo“ enthält Informationen zum Nutzer, wie in OpenID Connect Standard Claims und dem claims_supported-Metadatenwert des Discovery-Dokuments beschrieben. Nutzer oder ihre Organisationen können bestimmte Felder bereitstellen oder zurückhalten, sodass Sie Informationen zu jedem Feld für Ihre autorisierten Zugriffsbereiche erhalten.

Das Discovery-Dokument

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

Zur Vereinfachung der Implementierung und mehr Flexibilität erlaubt OpenID Connect die Verwendung eines „Discovery-Dokuments“, eines JSON-Dokuments an einem bekannten Speicherort mit Schlüssel/Wert-Paaren, das Details zur Konfiguration des OpenID Connect-Anbieters enthält. Dazu gehören die URIs der Endpunkte für Autorisierung, Token, Widerruf, Nutzerinformationen und öffentliche Schlüssel. Das Discovery-Dokument für den OpenID Connect-Dienst von Google kann hier abgerufen werden:

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

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

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

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

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

Clientbibliotheken

Mit den folgenden Clientbibliotheken ist die Implementierung von OAuth 2.0 durch die Einbindung in gängige Frameworks einfacher:

OpenID Connect-Compliance

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