Vereinfachte Verknüpfung mit OAuth und „Über Google anmelden“

Übersicht

Mit OAuth-basierter Anmeldung mit Google und optimierter Verknüpfung wird die Anmeldung mit Google zusätzlich zur OAuth-Verknüpfung eingeführt. So können Google-Nutzer ihre Konten nahtlos verknüpfen und auch ein neues Konto erstellen, um den Dienst mit ihrem Google-Konto zu nutzen.

So verknüpfst du Konten mit OAuth und der Anmeldung mit Google:

1. Bitte den Nutzer zuerst um die Einwilligung, auf sein Google-Profil zuzugreifen.
2. Prüfe anhand der Informationen im Profil, ob das Nutzerkonto vorhanden ist.
3. Verknüpfe die Konten für bestehende Nutzer.
4. Wenn du im Authentifizierungssystem keine Übereinstimmung für den Google-Nutzer findest, validiere das von Google empfangene ID-Token. Anschließend kannst du einen Nutzer anhand der im ID-Token enthaltenen Profilinformationen erstellen.

Abbildung 1. Kontoverknüpfung auf dem Smartphone eines Nutzers mit optimierter Verknüpfung

Anforderungen für die optimierte Verknüpfung

• Implementiere den grundlegenden OAuth-Verknüpfungsvorgang für das Web. Dein Dienst muss OAuth 2.0-konforme Autorisierungs- und Tokenaustausch-Endpunkte unterstützen.
• Dein Tokenaustausch-Endpunkt muss JSON Web Token-Assertions (JWT) unterstützen und die Intents check, create und get implementieren.

• Registriere deine Google API-Client-ID.

OAuth-Server implementieren

Dein Tokenaustausch-Endpunkt muss die Intents check, create und get unterstützen. Führe die folgenden Schritte aus, um den Kontoverknüpfungsvorgang abzuschließen und zu erfahren, wann die verschiedenen Intents verwendet werden:

1. Hat der Nutzer ein Konto in deinem Authentifizierungssystem? (Der Nutzer entscheidet, indem er JA oder NEIN auswählt.)
   1. JA : Meldet sich der Nutzer mit der E-Mail-Adresse an, die mit seinem Google-Konto verknüpft ist? (Der Nutzer entscheidet, indem er JA oder NEIN auswählt.)
      1. JA : Hat der Nutzer ein passendes Konto in deinem Authentifizierungssystem? (check intent wird zur Bestätigung aufgerufen)
         1. JA : get intent wird aufgerufen und das Konto wird verknüpft, wenn get intent erfolgreich zurückgegeben wird.
         2. NEIN : Neues Konto erstellen? (Der Nutzer entscheidet, indem er JA oder NEIN auswählt.)
            1. JA : create intent wird aufgerufen und das Konto wird verknüpft, wenn create intent erfolgreich zurückgegeben wird.
            2. NEIN : Der Web-OAuth-Vorgang wird ausgelöst, der Nutzer wird zu seinem Browser weitergeleitet und hat die Möglichkeit, eine andere E-Mail-Adresse zu verknüpfen.
      2. NEIN : Der Web-OAuth-Vorgang wird ausgelöst, der Nutzer wird zu seinem Browser weitergeleitet und hat die Möglichkeit, eine andere E-Mail-Adresse zu verknüpfen.
   2. NEIN : Hat der Nutzer ein passendes Konto in deinem Authentifizierungssystem? (check intent wird zur Bestätigung aufgerufen)
      1. JA : get intent wird aufgerufen und das Konto wird verknüpft, wenn get intent erfolgreich zurückgegeben wird.
      2. NEIN : create intent wird aufgerufen und das Konto wird verknüpft, wenn create intent erfolgreich zurückgegeben wird.

Nach einem vorhandenen Nutzerkonto suchen (Intent überprüfen)

Nachdem der Nutzer seine Einwilligung für den Zugriff auf sein Google-Profil erteilt hat, sendet Google eine -Anfrage, die eine signierte Bestätigung der Identität des Google-Nutzers enthält. Die Assertion enthält Informationen wie die Google-Konto-ID, Name und E-Mail-Adresse. Der Tokenaustausch-Endpunkt, der für Ihr diese Anfrage verarbeitet.

Wenn das entsprechende Google-Konto bereits in Ihrer Authentifizierung vorhanden ist reagiert, antwortet der Endpunkt des Tokenaustauschs mit account_found=true. Wenn die Das Google-Konto stimmt mit keinem vorhandenen Nutzer überein, Ihr Endpunkt für den Tokenaustausch gibt den Fehler „HTTP 404 Not Found“ mit account_found=false zurück.

Die Anfrage hat das folgende Format:

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

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=check&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

Der Endpunkt des Tokenaustauschs muss die folgenden Parameter verarbeiten können:

Ihr Endpunkt für den Tokenaustausch muss die folgenden Schritte ausführen, um auf die Intent-Anfragen check zu antworten:

• Validieren und decodieren Sie die JWT-Assertion.
• Prüfen Sie, ob das Google-Konto bereits in Ihrem Authentifizierungssystem vorhanden ist.

JWT-Assertion validieren und decodieren

Sie können die JWT-Assertion mit einem JWT-Decodierungsbibliothek für Ihre Sprache. Verwenden Sie Die öffentlichen Schlüssel von Google, verfügbar in JWK oder PEM-Formate, zur Überprüfung die Signatur des Tokens.

Nach der Decodierung sieht die JWT-Assertion so aus:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Neben der Verifizierung der Tokensignatur müssen Sie auch prüfen, ob die Aussteller (Feld iss) ist https://accounts.google.com, die Zielgruppe (Feld aud) enthält Ihre zugewiesene Client-ID und das Token, das nicht abgelaufen ist. (Feld exp).

Mit den Feldern email, email_verified und hd können Sie festlegen, Google hostet eine E-Mail-Adresse und ist für sie maßgeblich. In Fällen, in denen Google autoritativer Nutzer, der derzeit als rechtmäßiger Kontoinhaber bekannt ist und Sie können das Passwort oder andere Methoden zur Identitätsbestätigung überspringen. Andernfalls werden diese Methoden kann vor der Verknüpfung zur Bestätigung des Kontos verwendet werden.

Fälle, in denen Google als vertrauenswürdig eingestuft wird:

• email hat das Suffix @gmail.com. Dies ist ein Gmail-Konto.
• email_verified ist „true“ und hd ist festgelegt. Dies ist ein G Suite-Konto.

Nutzer können sich für ein Google-Konto registrieren, ohne Gmail oder die G Suite zu verwenden. Wann? email enthält kein @gmail.com-Suffix und hd fehlt. Google ist kein werden zur Bestätigung der Identität empfohlen, Nutzenden. email_verified kann auch „true“ sein, da Google das Nutzer beim Erstellen des Google-Kontos, aber die Inhaberschaft des Drittanbieters Ihr E-Mail-Konto hat sich in der Zwischenzeit möglicherweise geändert.

Prüfen, ob das Google-Konto bereits in Ihrem Authentifizierungssystem vorhanden ist

Prüfen Sie, ob eine der folgenden Bedingungen erfüllt ist:

• Die Google-Konto-ID, die Sie im Feld sub der Assertion finden, gehört Ihrem Nutzer Datenbank.
• Die E-Mail-Adresse in der Assertion stimmt mit einem Nutzer in Ihrer Nutzerdatenbank überein.

Wenn eine der Bedingungen erfüllt ist, hat sich der Nutzer bereits registriert. In diesem Fall eine Antwort wie die folgende zurückgeben:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

{
  "account_found":"true",
}

Wenn weder die Google-Konto-ID noch die E-Mail-Adresse im Assertion mit einem Nutzer in Ihrer Datenbank übereinstimmt, hat sich dieser Nutzer noch nicht registriert. In muss der Tokenaustausch-Endpunkt mit dem HTTP-Fehler 404 der "account_found": "false" angibt, wie im folgenden Beispiel:

HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8

{
  "account_found":"false",
}

Automatische Verknüpfung (get-Intent)

Nachdem der Nutzer seine Einwilligung für den Zugriff auf sein Google-Profil erteilt hat, sendet Google eine -Anfrage, die eine signierte Bestätigung der Identität des Google-Nutzers enthält. Die Assertion enthält Informationen wie die Google-Konto-ID, Name und E-Mail-Adresse. Der Tokenaustausch-Endpunkt, der für Ihr diese Anfrage verarbeitet.

Wenn das entsprechende Google-Konto bereits in Ihrer Authentifizierung vorhanden ist System gibt Ihr Tokenaustausch-Endpunkt ein Token für den Nutzer zurück. Wenn die Google-Konto stimmt mit keinem vorhandenen Nutzer überein, Ihr Endpunkt für den Tokenaustausch gibt einen linking_error-Fehler und optional login_hint zurück.

Die Anfrage hat das folgende Format:

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

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

Der Endpunkt des Tokenaustauschs muss die folgenden Parameter verarbeiten können:

Ihr Endpunkt für den Tokenaustausch muss die folgenden Schritte ausführen, um auf die Intent-Anfragen get zu antworten:

• Validieren und decodieren Sie die JWT-Assertion.
• Prüfen Sie, ob das Google-Konto bereits in Ihrem Authentifizierungssystem vorhanden ist.

JWT-Assertion validieren und decodieren

Sie können die JWT-Assertion mit einem JWT-Decodierungsbibliothek für Ihre Sprache. Verwenden Sie Die öffentlichen Schlüssel von Google, verfügbar in JWK oder PEM-Formate, zur Überprüfung die Signatur des Tokens.

Nach der Decodierung sieht die JWT-Assertion so aus:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Neben der Verifizierung der Tokensignatur müssen Sie auch prüfen, ob die Aussteller (Feld iss) ist https://accounts.google.com, die Zielgruppe (Feld aud) enthält Ihre zugewiesene Client-ID und das Token, das nicht abgelaufen ist. (Feld exp).

Mit den Feldern email, email_verified und hd können Sie festlegen, Google hostet eine E-Mail-Adresse und ist für sie maßgeblich. In Fällen, in denen Google autoritativer Nutzer, der derzeit als rechtmäßiger Kontoinhaber bekannt ist und Sie können das Passwort oder andere Methoden zur Identitätsbestätigung überspringen. Andernfalls werden diese Methoden kann vor der Verknüpfung zur Bestätigung des Kontos verwendet werden.

Fälle, in denen Google als vertrauenswürdig eingestuft wird:

• email hat das Suffix @gmail.com. Dies ist ein Gmail-Konto.
• email_verified ist „true“ und hd ist festgelegt. Dies ist ein G Suite-Konto.

Nutzer können sich für ein Google-Konto registrieren, ohne Gmail oder die G Suite zu verwenden. Wann? email enthält kein @gmail.com-Suffix und hd fehlt. Google ist kein werden zur Bestätigung der Identität empfohlen, Nutzenden. email_verified kann auch „true“ sein, da Google das Nutzer beim Erstellen des Google-Kontos, aber die Inhaberschaft des Drittanbieters Ihr E-Mail-Konto hat sich in der Zwischenzeit möglicherweise geändert.

Prüfen, ob das Google-Konto bereits in Ihrem Authentifizierungssystem vorhanden ist

Prüfen Sie, ob eine der folgenden Bedingungen erfüllt ist:

• Die Google-Konto-ID, die Sie im Feld sub der Assertion finden, gehört Ihrem Nutzer Datenbank.
• Die E-Mail-Adresse in der Assertion stimmt mit einem Nutzer in Ihrer Nutzerdatenbank überein.

Wenn für den Nutzer ein Konto gefunden wird, geben Sie ein Zugriffstoken aus und geben Sie die Werte wie im folgenden Beispiel in einem JSON-Objekt im Text Ihrer HTTPS-Antwort zurück:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "expires_in": SECONDS_TO_EXPIRATION
}

In einigen Fällen schlägt die auf dem ID-Token basierende Kontoverknüpfung für den Nutzer möglicherweise fehl. Wenn es aus irgendeinem Grund tut, muss Ihr Endpunkt für den Tokenaustausch mit einem HTTP-Statuscode 401-Fehler, der error=linking_error angibt, wie im folgenden Beispiel gezeigt:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

Wenn Google eine 401-Fehlerantwort mit linking_error erhält, sendet Google den Nutzer zu Ihrem Autorisierungsendpunkt mit login_hint als Parameter. Die Der Nutzer schließt die Kontoverknüpfung mithilfe des OAuth-Verknüpfungsvorgangs in seinem Browser ab.

Konten mit „Über Google anmelden“ erstellen (Create-Intent)

Wenn ein Nutzer ein Konto für Ihren Dienst erstellen muss, sendet Google eine Anfrage an Ihren Token-Austausch-Endpunkt, in der intent=create angegeben ist.

Die Anfrage hat das folgende Format:

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

response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&assertion=JWT&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

Ihr Endpunkt für den Tausch von Tokens muss die folgenden Parameter verarbeiten können:

Das JWT im Parameter assertion enthält die Google-Konto-ID, den Namen und die E-Mail-Adresse des Nutzers. Damit können Sie ein neues Konto in Ihrem Dienst erstellen.

Um auf Anfragen für den Intent create zu reagieren, muss Ihr Endpunkt für den Tausch von Tokens die folgenden Schritte ausführen:

• JWT-Assertion validieren und decodieren
• Nutzerinformationen bestätigen und neues Konto erstellen

JWT-Assertion validieren und decodieren

Sie können die JWT-Assertion mit einem JWT-Decodierungsbibliothek für Ihre Sprache. Verwenden Sie Die öffentlichen Schlüssel von Google, verfügbar in JWK oder PEM-Formate, zur Überprüfung die Signatur des Tokens.

Nach der Decodierung sieht die JWT-Assertion so aus:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Neben der Verifizierung der Tokensignatur müssen Sie auch prüfen, ob die Aussteller (Feld iss) ist https://accounts.google.com, die Zielgruppe (Feld aud) enthält Ihre zugewiesene Client-ID und das Token, das nicht abgelaufen ist. (Feld exp).

Mit den Feldern email, email_verified und hd können Sie festlegen, Google hostet eine E-Mail-Adresse und ist für sie maßgeblich. In Fällen, in denen Google autoritativer Nutzer, der derzeit als rechtmäßiger Kontoinhaber bekannt ist und Sie können das Passwort oder andere Methoden zur Identitätsbestätigung überspringen. Andernfalls werden diese Methoden kann vor der Verknüpfung zur Bestätigung des Kontos verwendet werden.

Fälle, in denen Google als vertrauenswürdig eingestuft wird:

• email hat das Suffix @gmail.com. Dies ist ein Gmail-Konto.
• email_verified ist „true“ und hd ist festgelegt. Dies ist ein G Suite-Konto.

Nutzer können sich für ein Google-Konto registrieren, ohne Gmail oder die G Suite zu verwenden. Wann? email enthält kein @gmail.com-Suffix und hd fehlt. Google ist kein werden zur Bestätigung der Identität empfohlen, Nutzenden. email_verified kann auch „true“ sein, da Google das Nutzer beim Erstellen des Google-Kontos, aber die Inhaberschaft des Drittanbieters Ihr E-Mail-Konto hat sich in der Zwischenzeit möglicherweise geändert.

Nutzerinformationen bestätigen und neues Konto erstellen

Prüfen Sie, ob eine der folgenden Bedingungen erfüllt ist:

• Die Google-Konto-ID, die sich im Feld sub der Assertion befindet, ist in Ihrer Nutzerdatenbank vorhanden.
• Die E-Mail-Adresse in der Assertion stimmt mit einem Nutzer in Ihrer Nutzerdatenbank überein.

Wenn eine der beiden Bedingungen zutrifft, fordern Sie den Nutzer auf, sein bestehendes Konto mit seinem Google-Konto zu verknüpfen. Antworten Sie dazu auf die Anfrage mit einem HTTP 401-Fehler, in dem error=linking_error angegeben ist und die E-Mail-Adresse des Nutzers als login_hint angegeben wird. Hier ist eine Beispielantwort:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

Wenn Google eine 401-Fehlerantwort mit linking_error erhält, wird der Nutzer mit login_hint als Parameter an Ihren Autorisierungsendpunkt weitergeleitet. Der Nutzer schließt die Kontoverknüpfung über den OAuth-Verknüpfungsvorgang in seinem Browser ab.

Wenn keine der beiden Bedingungen zutrifft, erstellen Sie ein neues Nutzerkonto mit den im JWT bereitgestellten Informationen. Für neue Konten ist in der Regel kein Passwort festgelegt. Es wird empfohlen, „Mit Google anmelden“ auf anderen Plattformen hinzuzufügen, damit sich Nutzer auf allen Oberflächen Ihrer Anwendung mit Google anmelden können. Alternativ können Sie dem Nutzer einen Link senden, mit dem er den Passwortwiederherstellungsprozess starten und ein Passwort festlegen kann, um sich auf anderen Plattformen anzumelden.

Wenn die Erstellung abgeschlossen ist, stellen Sie ein Zugriffstoken aus und geben Sie die Werte in einem JSON-Objekt im Text Ihrer HTTPS-Antwort zurück, wie im folgenden Beispiel:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "expires_in": SECONDS_TO_EXPIRATION
}

Google API-Client-ID abrufen

Du musst deine Google API-Client-ID während der Registrierung für die Kontoverknüpfung angeben.

So rufst du deine API-Client-ID mit dem Projekt ab, das du beim Ausführen der Schritte zur OAuth-Verknüpfung erstellt hast: Führe dazu folgende Schritte aus:

1. Rufe die Seite „Clients“ auf.

2. Erstelle ein Google APIs-Projekt oder wähle ein vorhandenes aus.

   Wenn dein Projekt keine Client-ID für den Anwendungstyp „Webanwendung“ hat, klicke auf Client erstellen , um eine zu erstellen. Gib die Domain deiner Website im Feld Autorisierte JavaScript-Quellen an. Wenn du lokale Tests oder Entwicklungen durchführst, musst du sowohl http://localhost als auch http://localhost:<port_number> zum Feld Autorisierte JavaScript-Quellen hinzufügen.

Implementierung validieren

Sie können Ihre Implementierung mit dem OAuth 2.0 Playground Tool validieren.

Führen Sie im Tool die folgenden Schritte aus:

1. Klicken Sie auf die Konfigurationseinstellungen settings , um das Fenster „OAuth 2.0-Konfiguration“ zu öffnen.
2. Wählen Sie im Feld OAuth-Ablauf die Option Clientseitig aus.
3. Wählen Sie im Feld OAuth-Endpunkte die Option Benutzerdefiniert aus.
4. Geben Sie in den entsprechenden Feldern Ihren OAuth 2.0-Endpunkt und die Client-ID an, die Sie Google zugewiesen haben.
5. Wählen Sie im Abschnitt Schritt 1 keine Google-Bereiche aus. Lassen Sie dieses Feld stattdessen leer oder geben Sie einen für Ihren Server gültigen Bereich ein (oder eine beliebige Zeichenfolge, wenn Sie keine OAuth-Bereiche verwenden). Klicken Sie anschließend auf APIs autorisieren.
6. Führen Sie in den Abschnitten Schritt 2 und Schritt 3 den OAuth 2.0-Ablauf durch und prüfen Sie, ob jeder Schritt wie vorgesehen funktioniert.

Sie können Ihre Implementierung mit dem Tool „Google-Kontoverknüpfung – Demo“ validieren.

Führen Sie im Tool die folgenden Schritte aus:

1. Klicken Sie auf die Schaltfläche Mit Google anmelden.
2. Wählen Sie das Konto aus, das Sie verknüpfen möchten.
3. Geben Sie die Dienst-ID ein.
4. Optional können Sie einen oder mehrere Bereiche eingeben, für die Sie Zugriff anfordern möchten.
5. Klicken Sie auf Demo starten.
6. Bestätigen Sie bei Aufforderung, dass Sie der Verknüpfungsanfrage zustimmen und sie ablehnen können.
7. Bestätigen Sie, dass Sie zu Ihrer Plattform weitergeleitet werden.