Übersicht
Optimierte Verknüpfung mit OAuth-basiertem Google Log-in: Google Log-in ergänzt OAuth-Verknüpfung. Dies ermöglicht eine nahtlose Verknüpfung von .
Um Kontoverknüpfungen mit OAuth und Google Log-in durchzuführen, folge diesen allgemeinen Schritte:
- Bitten Sie den Nutzer zuerst, seine Einwilligung für den Zugriff auf sein Google-Profil zu geben.
- Anhand der Informationen in ihrem Profil können Sie prüfen, ob das Nutzerkonto vorhanden ist.
- Verknüpfen Sie die Konten für bestehende Nutzer.
- Wenn Sie in Ihrem Authentifizierungssystem keine Übereinstimmung für den Google-Nutzer finden können, Validieren Sie das von Google erhaltene ID-Token. Sie können dann ein nutzerbasiertes zu den Profilinformationen im ID-Token.
Abbildung 1. Kontoverknüpfung auf dem Smartphone eines Nutzers mit der optimierten Verknüpfung
Anforderungen für optimierte Verknüpfungen
- Implementiere den einfachen OAuth-Verknüpfungsvorgang für das Web. Ihr Dienst muss OAuth 2.0-konform unterstützen Endpunkte Autorisierung und Tokenaustausch.
- Ihr Endpunkt für den Tokenaustausch muss JSON Web Token (JWT)-Assertions unterstützen und die Intents
check
,create
undget
implementieren.
OAuth-Server implementieren
Der Endpunkt des Tokenaustauschs muss die Intents check
, create
und get
unterstützen. Unten sehen Sie die Schritte, die während der Kontoverknüpfung ausgeführt werden, und es wird angegeben, wann die verschiedenen Intents aufgerufen werden:
- Hat der Nutzer ein Konto in Ihrem Authentifizierungssystem? (Der Nutzer entscheidet sich mit Ja oder NEIN.)
<ph type="x-smartling-placeholder">
- </ph>
- JA : Nutzt der Nutzer die E-Mail-Adresse, die mit seinem Google-Konto verknüpft ist, um sich auf Ihrer Plattform anzumelden? (Der Nutzer entscheidet sich mit Ja oder NEIN.)
<ph type="x-smartling-placeholder">
- </ph>
- JA : Verfügt der Nutzer über ein übereinstimmendes Konto in Ihrem Authentifizierungssystem? (
check intent
wird zur Bestätigung aufgerufen) <ph type="x-smartling-placeholder">- </ph>
- JA :
get intent
wird aufgerufen und das Konto wird verknüpft, wenn der get-Intent erfolgreich zurückgegeben wird. - NEIN : Neues Konto erstellen? (Der Nutzer entscheidet sich mit Ja oder NEIN.)
<ph type="x-smartling-placeholder">
- </ph>
- JA :
create intent
wird aufgerufen und das Konto verknüpft, wenn der Erstellungs-Intent erfolgreich zurückgegeben wird. - NEIN : Der Web-OAuth-Ablauf wird ausgelöst, der Nutzer wird zu seinem Browser weitergeleitet und erhält die Möglichkeit, eine Verknüpfung mit einer anderen E-Mail-Adresse herzustellen.
- JA :
- JA :
- NEIN : Der Web-OAuth-Vorgang wird ausgelöst, der Nutzer wird zu seinem Browser weitergeleitet und hat die Möglichkeit, eine Verknüpfung mit einer anderen E-Mail-Adresse herzustellen.
- JA : Verfügt der Nutzer über ein übereinstimmendes Konto in Ihrem Authentifizierungssystem? (
- NEIN : Verfügt der Nutzer über ein übereinstimmendes Konto in Ihrem Authentifizierungssystem? (
check intent
wird zur Bestätigung aufgerufen) <ph type="x-smartling-placeholder">- </ph>
- JA :
get intent
wird aufgerufen und das Konto wird verknüpft, wenn der get-Intent erfolgreich zurückgegeben wird. - NEIN :
create intent
wird aufgerufen und das Konto verknüpft, wenn die Rückgabe des Intents zum Erstellen erfolgreich ist.
- JA :
- JA : Nutzt der Nutzer die E-Mail-Adresse, die mit seinem Google-Konto verknüpft ist, um sich auf Ihrer Plattform anzumelden? (Der Nutzer entscheidet sich mit Ja oder NEIN.)
<ph type="x-smartling-placeholder">
Check for an existing user account (check intent)
After the user gives consent to access their Google profile, Google sends a request that contains a signed assertion of the Google user's identity. The assertion contains information that includes the user's Google Account ID, name, and email address. The token exchange endpoint configured for your project handles that request.
If the corresponding Google account is already present in your authentication
system, your token exchange endpoint responds with account_found=true
. If the
Google account doesn't match an existing user, your token exchange endpoint
returns an HTTP 404 Not Found error with account_found=false
.
The request has the following form:
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
Your token exchange endpoint must be able to handle the following parameters:
Token endpoint parameters | |
---|---|
intent |
For these requests, the value of this parameter is
check . |
grant_type |
The type of token being exchanged. For these requests, this
parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion |
A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address. |
client_id |
The client ID you assigned to Google. |
client_secret |
The client secret you assigned to Google. |
To respond to the check
intent requests, your token exchange endpoint must perform the following steps:
- Validate and decode the JWT assertion.
- Check if the Google account is already present in your authentication system.
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“ undhd
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.
Check if the Google account is already present in your authentication system
Check whether either of the following conditions are true:
- The Google Account ID, found in the assertion's
sub
field, is in your user database. - The email address in the assertion matches a user in your user database.
If either condition is true, the user has already signed up. In that case, return a response like the following:
HTTP/1.1 200 Success Content-Type: application/json;charset=UTF-8 { "account_found":"true", }
If neither the Google Account ID nor the email address specified in the
assertion matches a user in your database, the user hasn't signed up yet. In
this case, your token exchange endpoint needs to reply with a HTTP 404 error
that specifies "account_found": "false"
, as in the following example:
HTTP/1.1 404 Not found Content-Type: application/json;charset=UTF-8 { "account_found":"false", }
Handle automatic linking (get intent)
After the user gives consent to access their Google profile, Google sends a request that contains a signed assertion of the Google user's identity. The assertion contains information that includes the user's Google Account ID, name, and email address. The token exchange endpoint configured for your project handles that request.
If the corresponding Google Account is already present in your authentication
system, your token exchange endpoint returns a token for the user. If the
Google Account doesn't match an existing user, your token exchange endpoint
returns a linking_error
error and optional login_hint
.
The request has the following form:
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
Your token exchange endpoint must be able to handle the following parameters:
Token endpoint parameters | |
---|---|
intent |
For these requests, the value of this parameter is get . |
grant_type |
The type of token being exchanged. For these requests, this
parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion |
A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address. |
scope |
Optional: Any scopes that you've configured Google to request from users. |
client_id |
The client ID you assigned to Google. |
client_secret |
The client secret you assigned to Google. |
To respond to the get
intent requests, your token exchange endpoint must perform the following steps:
- Validate and decode the JWT assertion.
- Check if the Google account is already present in your authentication system.
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“ undhd
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.
Check if the Google account is already present in your authentication system
Check whether either of the following conditions are true:
- The Google Account ID, found in the assertion's
sub
field, is in your user database. - The email address in the assertion matches a user in your user database.
If an account is found for the user, issue an access token and return the values in a JSON object in the body of your HTTPS response, like in the following example:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
In some cases, account linking based on ID token might fail for the user. If it
does so for any reason, your token exchange endpoint needs to reply with a HTTP
401 error that specifies error=linking_error
, as the following example shows:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"linking_error", "login_hint":"foo@bar.com" }
When Google receives a 401 error response with linking_error
, Google sends
the user to your authorization endpoint with login_hint
as a parameter. The
user completes account linking using the OAuth linking flow in their browser.
Handle account creation via Google Sign-In (create intent)
When a user needs to create an account on your service, Google makes a request
to your token exchange endpoint that specifies intent=create
.
The request has the following form:
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
Your token exchange endpoint must able to handle the following parameters:
Token endpoint parameters | |
---|---|
intent |
For these requests, the value of this parameter is create . |
grant_type |
The type of token being exchanged. For these requests, this
parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion |
A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address. |
client_id |
The client ID you assigned to Google. |
client_secret |
The client secret you assigned to Google. |
The JWT within the assertion
parameter contains the user's Google Account ID,
name, and email address, which you can use to create a new account on your
service.
To respond to the create
intent requests, your token exchange endpoint must perform the following steps:
- Validate and decode the JWT assertion.
- Validate user information and create new account.
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“ undhd
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.
Validate user information and create new account
Check whether either of the following conditions are true:
- The Google Account ID, found in the assertion's
sub
field, is in your user database. - The email address in the assertion matches a user in your user database.
If either condition is true, prompt the user to link their existing account
with their Google Account. To do so, respond to the request with an HTTP 401 error
that specifies error=linking_error
and gives the user's email address as the
login_hint
. The following is a sample response:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"linking_error", "login_hint":"foo@bar.com" }
When Google receives a 401 error response with linking_error
, Google sends
the user to your authorization endpoint with login_hint
as a parameter. The
user completes account linking using the OAuth linking flow in their browser.
If neither condition is true, create a new user account with the information provided in the JWT. New accounts don't typically have a password set. It's recommended that you add Google Sign-In to other platforms to enable users to log in with Google across the surfaces of your application. Alternatively, you can email the user a link that starts your password recovery flow to allow the user to set a password to sign in on other platforms.
When the creation is completed, issue an access token and return the values in a JSON object in the body of your HTTPS response, like in the following example:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Google API-Client-ID abrufen
Sie müssen Ihre Google API-Client-ID bei der Registrierung der Kontoverknüpfung angeben.
API-Client-ID über das Projekt abrufen, das Sie bei der OAuth-Verknüpfung erstellt haben Führen Sie dazu folgende Schritte aus:
- Öffnen Sie die Seite Anmeldedaten des Google API Console:
Erstellen Sie ein Google APIs-Projekt oder wählen Sie eines aus.
Wenn Ihr Projekt keine Client-ID für den Webanwendungstyp hat, klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID, um eine zu erstellen. Achten Sie darauf, Ihre Websitedomain im Feld Autorisierte JavaScript-Quellen ein. Wenn Sie lokale Tests oder die Entwicklung vor Ort verwenden, müssen Sie sowohl
http://localhost
als auchhttp://localhost:<port_number>
in das Feld Autorisierte JavaScript-Quellen ein.
Implementierung validieren
您可以使用 OAuth 2.0 Playground 工具验证您的实现。
在该工具中,执行以下步骤:
- 点击配置 以打开 OAuth 2.0 配置窗口。
- 在 OAuth flow 字段中,选择 Client-side(客户端)。
- 在 OAuth 端点字段中,选择自定义。
- 在相应字段中指定您的 OAuth 2.0 端点和您分配给 Google 的客户端 ID。
- 在第 1 步部分,不要选择任何 Google 范围。请将此字段留空或输入对服务器有效的范围(如果您不使用 OAuth 范围,则可以输入任意字符串)。完成后,点击授权 API。
- 在 Step 2 和 Step 3 部分中,完成 OAuth 2.0 流程,并验证每个步骤是否按预期运行。
您可以使用 Google 账号关联演示版工具验证您的实现。
在该工具中,执行以下步骤:
- 点击使用 Google 账号登录按钮。
- 选择您要关联的账号。
- 输入服务 ID。
- (可选)输入您要请求访问权限的一个或多个范围。
- 点击开始演示。
- 当系统提示时,请确认您同意或拒绝关联请求。
- 确认您已被重定向到您的平台。