OpenID Connect

Die OAuth 2.0 APIs von Google können für die 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 dieses Protokoll interaktiv untersuchen möchten, empfehlen wir den Google OAuth 2.0 Playground. Damit Sie Hilfe in Stack Overflow erhalten, taggen Sie Ihre Fragen mit 'google-oauth'.

OAuth 2.0 einrichten

Bevor Ihre Anwendung das OAuth 2.0-Authentifizierungssystem von Google für die Nutzeranmeldung verwenden kann, müssen Sie ein Projekt in Google API Console einrichten, um OAuth 2.0-Anmeldedaten abzurufen, einen Weiterleitungs-URI festzulegen und (optional) die Markeninformationen 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 Filterfunktion 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 :

  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 API Console einrichtest, 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 des Nutzers anpassen

Für Ihre Nutzer umfasst die OAuth 2.0-Authentifizierung einen Zustimmungsbildschirm, auf dem beschrieben wird, welche Informationen der Nutzer freigibt und welche Bedingungen gelten. Wenn sich ein Nutzer anmeldet, wird er beispielsweise aufgefordert, Ihrer App Zugriff auf seine E-Mail-Adresse und grundlegende Kontoinformationen zu geben. Den Zugriff auf diese Informationen fordern Sie mit dem Parameter scope an, den Ihre Anwendung in die Authentifizierungsanfrage enthält. Sie können auch Bereiche verwenden, um den Zugriff auf andere Google APIs anzufordern.

Der Bildschirm zur Nutzereinwilligung enthält außerdem Markeninformationen wie Ihren Produktnamen, Ihr Logo und eine URL für die Startseite. Die Branding-Informationen kannst du in den API Consolefestlegen.

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 .

Das folgende Dialogfeld zur Einwilligung zeigt, was ein Nutzer sehen würde, wenn eine Kombination aus OAuth 2.0- und Google Drive-Bereichen in der Anfrage vorhanden ist. (Dieses allgemeine Dialogfeld wurde mit Google OAuth 2.0 Playground erstellt und enthält daher keine Markeninformationen, die in API Consolefestgelegt werden.)

Screenshot der Seite mit der Einwilligungsseite

Auf den Dienst zugreifen

Google und Drittanbieter stellen Bibliotheken zur Verfügung, mit denen Sie viele der Implementierungsdetails zur Authentifizierung von Nutzern und zum Zugriff auf Google APIs verwalten 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, in dem die HTTP-Anfrageabläufe beschrieben werden, die unter den verfügbaren Bibliotheken basieren.

Nutzer authentifizieren

Für die Authentifizierung des Nutzers müssen Sie ein ID-Token abrufen und validieren. 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 zum Authentifizieren eines Nutzers und zum Abrufen eines ID-Tokens sind der Ablauf „server&flow“ und der „implizite Ablauf“. Über den Serverfluss kann der Back-End-Server einer Anwendung die Identität der Person über einen Browser oder ein Mobilgerät überprüfen. Der implizite Ablauf wird verwendet, wenn eine clientseitige Anwendung (normalerweise eine im Browser ausgeführte JavaScript-Anwendung) direkt auf APIs und nicht auf ihren Back-End-Server zugreifen muss.

In diesem Dokument wird beschrieben, wie Sie den Serverfluss zur Authentifizierung des Nutzers ausführen. Der implizite Vorgang ist aufgrund von Sicherheitsrisiken bei der Verarbeitung 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 bei Google anzumelden, müssen Sie Folgendes tun:

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

1. Erstellen Sie ein Token für die Fälschung

Sie müssen die Sicherheit Ihrer Nutzer schützen, indem Sie Fälschungsangriffe auf Anfragen verhindern. Im ersten Schritt wird ein eindeutiges Sitzungstoken erstellt, das den Status zwischen Ihrer App und dem Client des Nutzers enthält. Später gleichen Sie dieses eindeutige Sitzungstoken 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 Zustandstoken ist ein String mit ungefähr 30 Zeichen, der mit einem hochwertigen Zufallsgenerator generiert wird. Ein weiterer Hash wird generiert, indem einige Ihrer Sitzungsvariablen mit einem Schlüssel signiert werden, der auf Ihrem Back-End geheim gehalten wird.

Der folgende Code zeigt die Erstellung eindeutiger Sitzungstokens.

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 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 statt 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 Autorisierungscode-Anfrage code lauten sollte. Weitere Informationen finden Sie unter response_type.
  • scope, die in einer grundlegenden Anfrage openid email sein sollten. Weitere Informationen finden Sie unter scope.
  • redirect_uri sollte der HTTP-Endpunkt auf deinem Server sein, an den die Antwort von Google gesendet wird. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie im 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 Sitzungstokens zur Fälschung sowie andere Informationen enthalten, die erforderlich sind, um den Kontext wiederherzustellen, 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 sub-String sein, der der Google-ID des Nutzers entspricht. Wenn du kein login_hint bereitstellst und der Nutzer aktuell 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-Vorgang 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 URI für die OpenID Connect-Authentifizierung mit Zeilenumbrüchen und Leerzeichen, um die Lesbarkeit zu verbessern:

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

Wenn deine App neue Informationen über sie anfordert oder wenn deine App Kontozugriff anfordert, die sie noch nicht genehmigt haben, müssen Nutzer ihre Einwilligung geben.

3. Status der Fälschungsstatus bestätigen

Die Antwort wird an die redirect_uri gesendet, die Sie in der Anfrage angegeben haben. Alle Antworten werden wie unten dargestellt 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 die state von Google mit dem Sitzungstoken übereinstimmt, das Sie in Schritt 1 erstellt haben. Diese Umlaufüberprüfung gewährleistet, dass die Anfrage von einem Nutzer und nicht von einem schädlichen Skript stammt.

Der folgende Code zeigt die Bestätigung der Sitzungstokens, 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 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. Exchange code gegen Zugriffstoken und ID-Token

Die Antwort enthält den Parameter code, einen einmaligen Autorisierungscode, den dein Server gegen ein Zugriffstoken und ein ID-Token austauschen kann. Ihr Server stellt diesen Austausch über eine HTTPS-POST-Anfrage her. 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 ersten Anfrage zurückgegeben wird.
client_id Die Client-ID, die Sie unter API ConsoleCredentials pageerhalten, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben.
client_secret Der Clientschlüssel, den Sie über die API ConsoleCredentials pageerhalten, wie unter OAuth 2.0-Anmeldedaten abrufen beschrieben.
redirect_uri Ein autorisierter Weiterleitungs-URI für den angegebenen client_id in der API Console Credentials page, wie unter Weiterleitungs-URI festlegen beschrieben.
grant_type Dieses Feld muss den Wert authorization_code enthalten, wie in der OAuth 2.0-Spezifikation definiert.

Die tatsächliche Anfrage könnte so aussehen:

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

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

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

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

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

5. Nutzerinformationen aus dem ID-Token abrufen

Ein ID-Token ist ein JWT (JSON Web Token), also ein kryptografisch signiertes Base64-codiertes JSON-Objekt. Normalerweise ist es wichtig, ein ID-Token zu validieren, bevor du es verwendest. Da du aber direkt mit Google über einen HTTPS-Kanal ohne zwischengeschaltete Person kommunizierst und deinen Clientschlüssel verwendest, um dich bei Google zu authentifizieren, kannst du sicher sein, dass das Token, das du erhältst, wirklich von Google stammt und gültig ist. Wenn dein Server das ID-Token an andere Komponenten deiner Anwendung weitergibt, ist es äußerst wichtig, dass die anderen Komponenten das Token validieren, bevor du es verwendest.

Da die meisten API-Bibliotheken die Validierung mit dem Decodieren der base64url-codierten Werte und dem Parsen des JSON-Codes kombinieren, müssen Sie das Token wahrscheinlich trotzdem validieren, 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 ein Beispiel, das zur besseren Lesbarkeit formatiert ist:

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

Google-ID-Tokens können die folgenden Felder enthalten (sogenannte Ansprüche):

Claim angegeben 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 Die Ablaufzeit am oder nach dem ID-Token darf nicht akzeptiert werden. 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 mehrere E-Mail-Adressen zu verschiedenen Zeitpunkten haben. Der Wert sub wird jedoch nie geändert. Verwende in deiner App sub als Schlüssel mit eindeutiger Kennung für den Nutzer. Maximale Länge: 255 ASCII-Zeichen, bei denen die Groß- und Kleinschreibung berücksichtigt wird.
at_hash Zugriffstoken-Hash. Stellt sicher, dass das Zugriffstoken an das Identitätstoken gebunden ist. Wenn das ID-Token im Serverablauf mit einem access_token-Wert ausgestellt wird, ist diese Anforderung immer enthalten. Dieser Anspruch kann als alternativer Mechanismus zum Schutz vor websiteübergreifenden Anfragefälschungsangriffen verwendet werden. Wenn Sie Schritt 1 und Schritt 3 ausführen, ist es jedoch nicht erforderlich, das Zugriffstoken zu bestätigen.
azp Die client_id des bevollmächtigten Vortragenden. Dieser Anspruch ist nur erforderlich, wenn die Partei, die das ID-Token anfordert, nicht mit der Zielgruppe des ID-Tokens übereinstimmt. Dies ist bei Google beispielsweise der Fall, wenn eine Webanwendung und eine Android-App ein anderes OAuth 2.0-client_id haben, aber dasselbe Google APIs-Projekt haben.
email E-Mail-Adresse des Nutzers Dieser Wert darf für diesen Nutzer nicht eindeutig sein und kann nicht als Primärschlüssel verwendet werden. Nur angegeben, wenn Ihr Bereich den Bereichswert email enthält.
email_verified Wahr, wenn die E-Mail-Adresse des Nutzers bestätigt wurde; andernfalls falsch.
family_name Nachnamen oder Nachnamen der Nutzer Kann angegeben werden, wenn ein name-Anspruch erhoben wird.
given_name Vor- oder Nachname des Nutzers. Kann angegeben werden, wenn ein name-Anspruch erhoben wird.
hd Die Domain, die mit der Google Cloud-Organisation des Nutzers verknüpft ist. Nur angegeben, wenn der Nutzer einer Google Cloud-Organisation angehört.
locale Die Sprache des Nutzers, dargestellt durch ein BCP 47-Sprach-Tag. Kann angegeben werden, wenn ein name-Anspruch vorliegt.
name Der vollständige Name des Nutzers in einem anzeigbaren Format. 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 Nutzerdatensätze deiner App verwenden. Dieser Anspruch wird niemals garantiert.

nonce Der Wert von nonce, der von Ihrer App in der Authentifizierungsanfrage bereitgestellt wurde. Sie sollten den Schutz vor Angriffen durch Wiederholungen erzwingen, indem Sie dafür sorgen, dass er nur einmal angezeigt 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 Nutzerdatensätze deiner App verwenden. Dieser Anspruch wird niemals 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 Nutzerdatensätze deiner App verwenden. Dieser Anspruch wird niemals 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 von der Google API-Antwort erfüllt werden.

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

Erweiterte Themen

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 für die Authentifizierung besteht darin, dass deine Anwendung bei der Authentifizierung des Nutzers gleichzeitig die Berechtigung erhält, andere Google APIs im Namen des Nutzers (z. B. YouTube, Google Drive, Google Kalender oder Google Kontakte) zu verwenden. Füge dazu die anderen Bereiche hinzu, die du in der Authentifizierungsanfrage benötigst, die du an Google sendest. Um beispielsweise die Altersgruppe des Nutzers zu Ihrer Authentifizierungsanfrage hinzuzufügen, übergeben Sie den Bereichsparameter openid email https://www.googleapis.com/auth/profile.agerange.read. Der Nutzer wird auf dem Zustimmungsbildschirm entsprechend gefragt. Mit dem Zugriffstoken, das Sie von Google zurückerhalten, können Sie auf alle APIs zugreifen, die sich auf die angeforderten und gewährten Zugriffsbereiche beziehen.

Aktualisierungstokens

In Ihrer Anfrage für den API-Zugriff können Sie ein Aktualisierungstoken anfordern, das während des code-Austauschs zurückgegeben wird. Ein Aktualisierungstoken ermöglicht Ihrer App, dauerhaft auf Google APIs zuzugreifen, während der Nutzer in Ihrer Anwendung nicht vorhanden ist. Zum Anfordern eines Aktualisierungstokens müssen Sie den Parameter access_type in der Authentifizierungsanfrage auf offline setzen.

Bitte beachten Sie:

  • Bewahren Sie das Aktualisierungstoken sicher und dauerhaft auf, da Sie nur dann ein Aktualisierungstoken erhalten, wenn Sie den Codeaustausch ausführen.
  • Die Anzahl der ausgestellten Aktualisierungstokens ist begrenzt: ein Limit pro Kombination aus Client und Nutzer und ein anderes pro Nutzer und Client. Wenn Ihre Anwendung zu viele Aktualisierungstokens anfordert, können diese Limits überschritten werden. In diesem Fall funktionieren ältere Aktualisierungstokens nicht mehr.

Weitere Informationen finden Sie unter Zugriffstoken aktualisieren (Offlinezugriff).

Du kannst den Nutzer auffordern, deine App noch einmal zu autorisieren. Setze dazu den Parameter prompt in deiner Authentifizierungsanfrage auf consent. Wenn prompt=consent enthalten ist, wird der Zustimmungsbildschirm jedes Mal angezeigt, wenn deine App die Autorisierung von Zugriffsbereichen anfordert, auch wenn alle Bereiche zuvor deinem Google APIs-Projekt gewährt wurden. Füge daher prompt=consent nur dann hinzu, wenn dies erforderlich ist.

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

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 Sie über API ConsoleCredentials pageerhalten, 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 lautet, wird ein Grundlegender 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 Vorgang gestartet. Hierfür müssen JavaScript beim Weiterleitungs-URI verwendet werden, um Tokens aus der URI #fragment-ID 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 ConsoleCredentials page festgelegt haben (einschließlich des HTTP- oder HTTPS-Schemas sowie des abschließenden „#&“;', falls vorhanden).
scope (Erforderlich)

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

Wenn der Bereichswert profile vorhanden ist, kann das ID-Token unter Umständen die Standardansprüche profile des Nutzers enthalten (was jedoch nicht unbedingt der Fall ist).

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 Bereichswerte müssen durch Leerzeichen getrennt sein. Wenn Sie beispielsweise pro Dateizugriff auf ein Google Drive-Konto eines Nutzers zugreifen möchten, könnte Ihr Umfangsparameter 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 opaker String, der im Protokoll eine Roundtrip-Anfrage ist, d. h. er wird im einfachen Ablauf als URI-Parameter und im implizierten Ablauf als URI-ID zurückgegeben.

Das state kann zum Korrelieren von Anfragen und Antworten nützlich sein. Da Ihr redirect_uri erraten werden kann, können Sie mit einem state-Wert die Wahrscheinlichkeit 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-Variablen codieren, können Sie die Antwort validieren. So stellen Sie zusätzlich sicher, dass die Anfrage und die Antwort im selben Browser stammen. Dies schützt vor Angriffen wie einer websiteübergreifenden Fälschung von Anfragen.

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 kein Aktualisierungstoken, es sei denn, der Wert offline ist angegeben.
display (Optional) Ein ASCII-Stringwert, mit dem angegeben wird, wie der Autorisierungsserver die Seiten für die Authentifizierung und die Einwilligungsoberfläche anzeigt. Die folgenden Werte werden angegeben und von den Google-Servern akzeptiert, haben aber keine Auswirkungen auf das Verhalten: page, popup, touch und wap.
hd (Optional)

Den Anmeldevorgang für Konten einer Google Cloud-Organisation optimieren Durch das Einbinden der Google Cloud-Domain der Organisation (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 für Google Cloud-Organisationskonten im Allgemeinen statt nur einer Google Cloud-Organisationsdomain optimieren 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 hd-Anforderungswert hat, der deinen Erwartungen 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 ist und die Autorisierungsanfrage genehmigt wurde, schließt die Autorisierung alle vorherigen Autorisierungen ein, 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 Apps 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 übergeben, wird die Kontoauswahl unterdrückt und das E-Mail-Feld im Anmeldeformular vorab ausgefüllt oder die richtige Sitzung ausgewählt (wenn der Nutzer die Mehrfachanmeldung verwendet). So können Probleme vermieden werden, 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 durch Leerzeichen getrennte Liste von Stringwerten, die angibt, ob der Autorisierungsserver den Nutzer zur nochmaligen Authentifizierung und Einwilligung einlädt. Folgende Werte sind möglich:
  • none

    Der Autorisierungsserver zeigt keine Authentifizierungs- oder Nutzereinwilligungsbildschirme an. Er gibt einen Fehler zurück, wenn der Nutzer noch nicht authentifiziert ist und für die angeforderten Bereiche keine Einwilligung konfiguriert hat. Mit none können Sie auf 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. So können Nutzer mit mehreren Konten auf dem Autorisierungsserver aus mehreren Konten auswählen, für die sie möglicherweise aktuelle Sitzungen haben.

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 Ihr Server alle von Ihren Clientanwendungen empfangenen ID-Tokens als echt bestätigen.

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

  • ID-Tokens mit Anfragen senden, die authentifiziert werden müssen Die ID-Tokens geben Aufschluss darüber, welcher Nutzer die Anfrage gesendet hat und welchem Client dieses ID-Token gewährt wurde.

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

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

Die Validierung eines ID-Tokens erfordert mehrere Schritte:

  1. Überprüfen Sie, ob das ID-Token vom Aussteller ordnungsgemäß signiert ist. Von Google ausgestellte Tokens werden mit einem der Zertifikate signiert, die unter dem URI gefunden werden, der im Discovery-Dokument im Metadatenwert jwks_uri angegeben ist.
  2. Prüfe, ob der Wert der iss-Anforderung im ID-Token https://accounts.google.com oder accounts.google.com ist.
  3. Prüfe, ob der Wert der aud-Anforderung im ID-Token der Client-ID deiner App entspricht.
  4. Prüfen Sie, ob die Ablaufzeit (exp Anforderung) des ID-Tokens abgelaufen ist.
  5. Wenn Sie in der Anfrage einen hd-Parameterwert 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.

In den Schritten 2 bis 5 werden nur Strings und Datumsangaben verglichen, die recht unkompliziert sind. Daher werden sie hier nicht im Detail erläutert.

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 dereferenzieren Sie den URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Wenn die Tokensignatur gültig ist, ist die Antwort die JWT-Nutzlast in ihrer decodierten JSON-Objektform.

Der Endpunkt tokeninfo ist nützlich für die Fehlerbehebung, aber für Produktionszwecke sollten Sie die öffentlichen Schlüssel von Google vom Schlüsselendpunkt abrufen und die Validierung lokal ausführen. Sie sollten den Schlüssel-URI aus dem Discovery-Dokument mit dem Metadatenwert jwks_uri abrufen. Anfragen an den Debugging-Endpunkt werden möglicherweise gedrosselt oder sind mitunter zeitweilig fehlerhaft.

Da Google seine öffentlichen Schlüssel nur selten ändert, kannst du sie mit den Cache-Anweisungen der HTTP-Antwort im Cache speichern und in den meisten Fällen die lokale Validierung viel effizienter durchführen 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 dafür Debugging-Bibliotheken in einer Vielzahl von Sprachen zur Verfügung (siehe jwt.io).

Nutzerprofilinformationen abrufen

Zum Abrufen weiterer Profilinformationen über den Nutzer können Sie das Zugriffstoken verwenden, das Ihre Anwendung während des Authentifizierungsvorgangs erhält, sowie den OpenID Connect-Standard:

  1. Damit sie OpenID-kompatibel sind, müssen Sie die Werte für den Bereich openid profile in Ihre Authentifizierungsanfrage aufnehmen.

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

    scope=openid%20profile%20email
  2. Fügen Sie dem Autorisierungsheader Ihr Zugriffstoken hinzu und senden Sie eine HTTPS-GET-Anfrage an den userinfo-Endpunkt, der aus dem Discovery-Dokument mit dem Metadatenwert userinfo_endpoint abgerufen werden sollte. Die „userinfo“-Antwort enthält Informationen zum Nutzer, wie unter OpenID Connect Standard Claims und dem Metadatenwert claims_supported 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 sind mehrere Endpunkte zur Authentifizierung von Nutzern und zum Anfordern von Ressourcen wie Tokens, Nutzerinformationen und öffentlichen Schlüsseln erforderlich.

Zur Vereinfachung von Implementierungen und mehr Flexibilität ermöglicht OpenID Connect die Verwendung eines „Discovery-Dokuments“ an einem bekannten Speicherort mit Schlüssel/Wert-Paaren, die Details zur Konfiguration des OpenID Connect-Anbieters enthalten, einschließlich der URIs der Autorisierungs-, Token-, Widerrufs-, Nutzerinfo- und öffentlichen Schlüsselendpunkte. 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. Die Anwendung ruft das Dokument ab, wendet Caching-Regeln in der Antwort an und ruft dann nach Bedarf Endpunkt-URIs daraus ab. Für die Authentifizierung eines Nutzers würde der 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.

Hier siehst du ein Beispiel für ein solches Dokument. Die Feldnamen sind in OpenID Connect Discovery 1.0 angegeben. Ihre Bedeutungen finden Sie in diesem Dokument. Die Werte dienen nur der Veranschaulichung und können sich ändern. Sie wurden jedoch aus einer aktuellen Version des eigentlichen Google Discovery-Dokuments kopiert:

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

Möglicherweise können Sie eine HTTP-Umgehung vermeiden, indem Sie die Werte aus dem Discovery-Dokument im Cache speichern. Es werden Standard-HTTP-Caching-Header verwendet und sollten berücksichtigt 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. Alle Clients, die für die Verwendung mit OpenID Connect entwickelt wurden, sollten mit diesem Dienst interagieren (mit Ausnahme des OpenID-Anfrageobjekts).