Die Konten werden mithilfe von In-App-Käufen über den impliziten und Standard-Autorisierungscode von OAuth 2.0 verknüpft. Der Dienst muss die OAuth 2.0-konformen Endpunkte für die Autorisierung und den Tokenaustausch unterstützen.
在隐式流程中，Google 会在用户的浏览器中打开您的授权端点。成功登录后，系统会将长期访问令牌返回到 Google。现在，从 Google 发送的每个请求中都包含此访问令牌。
在授权代码流程中，您需要两个端点：
授权端点 - 向尚未登录的用户显示登录界面。授权端点还会创建一个短期授权代码，用于记录用户针对所请求的访问权限的同意情况。
令牌交换端点，负责两种交换类型：
- 将授权代码交换为长期刷新令牌和短期访问令牌。这种交换会在用户完成帐号关联流程时进行。
- 将长期有效的刷新令牌交换为短期访问令牌。当 Google 需要新的访问令牌时，由于此令牌已过期，因此出现这种交换。
选择 OAuth 2.0 流程
虽然隐式数据流的实现过程更简单，但 Google 建议隐式数据流签发的访问令牌永远不会过期。这是因为在令牌随隐式流程过期后，用户被迫再次关联自己的帐号。出于安全考虑，如果您需要令牌过期，我们强烈建议您改为使用授权代码流程。
设计准则
本部分将介绍针对 OAuth 关联流程托管的用户屏幕的设计要求和建议。在由 Google 的应用调用后，您的平台会向用户显示“登录 Google”页面和帐号关联屏幕。用户同意关联帐号后，会被重定向回 Google 的应用。
要求
- 您必须告知用户该用户帐号将与 Google 关联，而不是与特定 Google 产品（例如 Google Home 或 Google 助理）关联。
建议
建议您执行以下操作：
显示 Google 的隐私权政策。在同意屏幕上添加指向 Google 隐私权政策的链接。
要共享的数据。使用简洁明了的语言向用户说明他们的 Google 需要哪些数据以及为何收集这些数据。
明确的号召性用语。在同意屏幕上提供明确的号召性用语，例如“同意并关联”。这是因为用户需要了解他们需要与 Google 共享哪些数据，才能关联帐号。
能够取消。如果用户不关联，则可以提供返回或取消的方式。
清除登录流程。确保用户有明确的登录 Google 帐号的方法，例如用户名和密码字段或使用 Google 帐号登录字段。
能够解除关联。为用户提供解除关联的机制，例如他们在平台上的帐号设置网址。或者，您也可以添加指向 Google 帐号的链接，以便用户可以管理关联的帐号。
能够更改用户帐号。推荐一种供用户切换帐号的方法。如果用户往往拥有多个帐号，这一点尤其有用。
- 如果用户必须关闭同意屏幕才能切换帐号，请向 Google 发送一个可恢复错误，以便用户通过 OAuth 关联和隐式流程登录所需帐号。
添加徽标。在同意屏幕上显示公司徽标。 根据样式指南放置徽标。如果您还希望显示 Google 的徽标，请参阅徽标和商标。
Create the project
To create your project to use account linking:
- Go to the Google API Console.
- Klicken Sie auf Projekt erstellen .
- Geben Sie einen Namen ein oder akzeptieren Sie den generierten Vorschlag.
- Bestätigen oder bearbeiten Sie alle verbleibenden Felder.
- Klicken Sie auf Erstellen .
So zeigen Sie Ihre Projekt-ID an:
- Go to the Google API Console.
- Finden Sie Ihr Projekt in der Tabelle auf der Zielseite. Die Projekt - ID wird in der ID - Spalte.
Configure your OAuth Consent Screen
The Google Account Linking process includes a consent screen which tells users the application requesting access to their data, what kind of data they are asking for and the terms that apply. You will need to configure your OAuth consent screen before generating a Google API client ID.
- Open the OAuth consent screen page of the Google APIs console.
- If prompted, select the project you just created.
On the "OAuth consent screen" page, fill out the form and click the “Save” button.
Application name: The name of the application asking for consent. The name should accurately reflect your application and be consistent with the application name users see elsewhere. The application name will be shown on the Account Linking consent screen.
Application logo: An image on the consent screen that will help users recognize your app. The logo is shown on Account linking consent screen and on account settings
Support email: For users to contact you with questions about their consent.
Scopes for Google APIs: Scopes allow your application to access your user's private Google data. For the Google Account Linking use case, default scope (email, profile, openid) is sufficient, you don’t need to add any sensitive scopes. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. Learn more.
Authorized domains: To protect you and your users, Google only allows applications that authenticate using OAuth to use Authorized Domains. Your applications' links must be hosted on Authorized Domains. Learn more.
Application Homepage link: Home page for your application. Must be hosted on an Authorized Domain.
Application Privacy Policy link: Shown on Google Account Linking consent screen. Must be hosted on an Authorized Domain.
Application Terms of Service link (Optional): Must be hosted on an Authorized Domain.
Figure 1. Google Account Linking Consent Screen for a fictitious Application, Tunery
Check "Verification Status", if your application needs verification then click the "Submit For Verification" button to submit your application for verification. Refer to OAuth verification requirements for details.
OAuth-Server implementieren
Ein OAuth 2.0 - Server - Implementierung des Autorisierungscodes Stromes besteht aus zwei Endpunkten, die Ihr Dienst von HTTPS zur Verfügung stellt. Der erste Endpunkt ist der Autorisierungsendpunkt, der dafür verantwortlich ist, die Zustimmung von Benutzern für den Datenzugriff zu finden oder einzuholen. Der Autorisierungsendpunkt stellt Ihren Benutzern, die noch nicht angemeldet sind, eine Benutzeroberfläche zur Anmeldung bereit und zeichnet die Zustimmung zum angeforderten Zugriff auf. Der zweite Endpunkt ist der Token-Austausch-Endpunkt, der verwendet wird, um verschlüsselte Zeichenfolgen, sogenannte Tokens, abzurufen, die einem Benutzer den Zugriff auf Ihren Dienst autorisieren.
Wenn eine Google-Anwendung eine der APIs Ihres Dienstes aufrufen muss, verwendet Google diese Endpunkte zusammen, um von Ihren Nutzern die Erlaubnis zu erhalten, diese APIs in ihrem Namen aufzurufen.
Eine von Google initiierte OAuth 2.0-Autorisierungscodeflusssitzung hat den folgenden Ablauf:
- Google öffnet Ihren Autorisierungsendpunkt im Browser des Nutzers. Wenn der Flow auf einem Nur-Sprachgerät für eine Aktion gestartet wurde, überträgt Google die Ausführung an ein Telefon.
- Der Nutzer meldet sich an, falls er noch nicht angemeldet ist, und erteilt Google die Berechtigung, mit Ihrer API auf seine Daten zuzugreifen, sofern er noch keine Berechtigung erteilt hat.
- Ihr Dienst erstellt einen Berechtigungscode und gibt sie an Google. Leiten Sie dazu den Browser des Nutzers mit dem an die Anfrage angehängten Autorisierungscode zurück zu Google.
- Google sendet den Autorisierungscode zu Ihrem Token Austausch Endpunkt, die die Echtheit des Codes überprüft und gibt einen Zugriffstoken und ein Aktualisierungs - Token. Das Zugriffstoken ist ein kurzlebiges Token, das Ihr Dienst als Anmeldeinformationen für den Zugriff auf APIs akzeptiert. Das Aktualisierungstoken ist ein langlebiges Token, das Google speichern und verwenden kann, um neue Zugriffstokens zu erwerben, wenn diese ablaufen.
- Nachdem der Nutzer die Kontoverknüpfung abgeschlossen hat, enthält jede nachfolgende von Google gesendete Anfrage ein Zugriffstoken.
Autorisierungsanfragen bearbeiten
Wenn Sie eine Kontoverknüpfung mithilfe des OAuth 2.0-Autorisierungscodeflusses durchführen müssen, sendet Google den Nutzer mit einer Anfrage, die die folgenden Parameter enthält, an Ihren Autorisierungsendpunkt:
| Autorisierungsendpunktparameter | |
|---|---|
client_id | Die Client-ID, die Sie Google zugewiesen haben. |
redirect_uri | Die URL, an die Sie die Antwort auf diese Anfrage senden. |
state | Ein Buchhaltungswert, der unverändert im Weiterleitungs-URI an Google zurückgegeben wird. |
scope | Optional: Ein Leerzeichen getrennte Satz von Rahmen - Strings, die die Daten angeben Google die Berechtigung für anfordert. |
response_type | Der Typ des Werts, der in der Antwort zurückgegeben werden soll. Für den OAuth 2.0 Autorisierungscode Fluss ist der Antworttyp immer code . |
user_locale | Die Google - Konto Spracheinstellung in RFC5646 - Format verwendet , um Ihre Inhalte in dem bevorzugten Sprache des Benutzers zu lokalisieren. |
Zum Beispiel, wenn Ihre Berechtigung Endpunkt an verfügbar ist https://myservice.example.com/auth könnte eine Anfrage wie folgt aussehen:
GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE
Führen Sie die folgenden Schritte aus, damit Ihr Autorisierungsendpunkt Anmeldeanforderungen verarbeiten kann:
- Stellen Sie sicher , dass der
client_iddie Client - ID entspricht , die Sie bei Google zugewiesen, und dass derredirect_urientspricht die Umleitungs - URL zur Verfügung gestellt von Google für Ihren Dienst. Diese Prüfungen sind wichtig, um zu verhindern, dass unbeabsichtigten oder falsch konfigurierten Client-Apps Zugriff gewährt wird. Wenn Sie mehr OAuth 2.0 Ströme unterstützen, bestätigt auch , dass dieresponse_typeistcode. - Überprüfen Sie, ob der Benutzer bei Ihrem Dienst angemeldet ist. Wenn der Benutzer nicht angemeldet ist, führen Sie den Anmelde- oder Anmeldevorgang Ihres Dienstes durch.
- Generieren Sie einen Autorisierungscode, den Google für den Zugriff auf Ihre API verwenden kann. Der Autorisierungscode kann ein beliebiger Zeichenfolgenwert sein, muss jedoch den Benutzer, den Client, für den das Token bestimmt ist, sowie die Ablaufzeit des Codes eindeutig darstellen und darf nicht erraten werden. Normalerweise geben Sie Autorisierungscodes aus, die nach etwa 10 Minuten ablaufen.
- Bestätigen , dass die URL von dem angegebenen
redirect_uriParameter hat die folgende Form:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
- Leiten Sie den Browser des Benutzers an die URL von dem angegebenen
redirect_uriParameter. Fügen Sie den Autorisierungscode Sie gerade erzeugt und die ursprünglichen, unveränderten Zustand Wert , wenn Sie durch Anhängen der Redirect -codeundstateDas Folgende ist ein Beispiel der resultierenden URL:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING
Bearbeitung von Token-Austausch-Anfragen
Der Token-Austausch-Endpunkt Ihres Dienstes ist für zwei Arten von Token-Austausch verantwortlich:
- Autorisierungscodes für Zugriffstoken und Aktualisierungstoken austauschen
- Aktualisierungstoken gegen Zugriffstoken austauschen
Token-Austausch-Anfragen umfassen die folgenden Parameter:
| Endpunktparameter für Tokenaustausch | |
|---|---|
client_id | Eine Zeichenfolge, die den Ursprung der Anfrage als Google identifiziert. Diese Zeichenfolge muss in Ihrem System als eindeutige Kennung von Google registriert sein. |
client_secret | Eine geheime Zeichenfolge, die Sie bei Google für Ihren Dienst registriert haben. |
grant_type | Der Tokentyp, der ausgetauscht wird. Es ist entweder authorization_code oder refresh_token . |
code | Wenn grant_type=authorization_code dieser Parameter ist der Code von Google entweder Anmelde-empfangen oder Token Austausch Endpunkt. |
redirect_uri | Wenn grant_type=authorization_code ist dieser Parameter die URL in der ursprünglichen Genehmigungsanfrage verwendet. |
refresh_token | Wenn grant_type=refresh_token Dieser Parameter ist die Aktualisierungs - Token Google von Ihrem Token Austausch Endpunkt empfangen. |
Autorisierungscodes für Zugriffstoken und Aktualisierungstoken austauschen
Nachdem sich der Nutzer angemeldet hat und Ihr Autorisierungsendpunkt einen kurzlebigen Autorisierungscode an Google zurückgibt, sendet Google eine Anfrage an Ihren Token-Austausch-Endpunkt, um den Autorisierungscode gegen ein Zugriffstoken und ein Aktualisierungstoken auszutauschen.
Für diese Anforderungen ist der Wert von grant_type ist authorization_code , und der Wert des code ist der Wert des Autorisierungscodes Sie zuvor auf Google gewährt. Im Folgenden finden Sie ein Beispiel für eine Anforderung zum Austausch eines Autorisierungscodes gegen ein Zugriffstoken und ein Aktualisierungstoken:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI
Um Berechtigungscodes für einen Zugriff Austausch - Token und ein Aktualisierungs - Token, Token Austausch Endpunkt reagiert auf POST - Anfragen durch die folgenden Schritte ausführen:
- Stellen Sie sicher , dass die
client_ididentifiziert die Anforderung Ursprung als berechtigter Ursprung, und dass dieclient_secretden erwarteten Wert übereinstimmt. - Stellen Sie sicher, dass der Autorisierungscode gültig und nicht abgelaufen ist und dass die in der Anforderung angegebene Client-ID mit der Client-ID übereinstimmt, die dem Autorisierungscode zugeordnet ist.
- Bestätigen , dass die URL von dem angegebenen
redirect_uriParameter ist identisch mit dem Wert in der anfänglichen Berechtigungsanforderung verwendet. - Wenn Sie nicht alle der oben genannten Kriterien überprüfen können, geben eine HTTP 400 Bad Request Fehler mit
{"error": "invalid_grant"}wie der Körper. - Verwenden Sie andernfalls die Benutzer-ID aus dem Autorisierungscode, um ein Aktualisierungstoken und ein Zugriffstoken zu generieren. Bei diesen Token kann es sich um einen beliebigen Zeichenfolgenwert handeln, sie müssen jedoch den Benutzer und den Client, für den das Token bestimmt ist, eindeutig darstellen und dürfen nicht erraten werden. Notieren Sie bei Zugriffstoken auch die Ablaufzeit des Tokens, die normalerweise eine Stunde nach der Ausgabe des Tokens liegt. Aktualisierungstoken laufen nicht ab.
- Bringen Sie das folgende JSON - Objekt in dem Körper der HTTPS - Antwort:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Google speichert das Zugriffstoken und das Aktualisierungstoken für den Nutzer und protokolliert den Ablauf des Zugriffstokens. Wenn das Zugriffstoken abläuft, verwendet Google das Aktualisierungstoken, um ein neues Zugriffstoken von Ihrem Token-Austausch-Endpunkt abzurufen.
Aktualisierungstoken gegen Zugriffstoken austauschen
Wenn ein Zugriffstoken abläuft, sendet Google eine Anfrage an Ihren Token-Austausch-Endpunkt, um ein Aktualisierungstoken gegen ein neues Zugriffstoken auszutauschen.
Für diese Anforderungen ist der Wert von grant_type wird refresh_token , und der Wert von refresh_token ist der Wert des Aktualisierungs - Token Sie zuvor auf Google gewährt. Im Folgenden finden Sie ein Beispiel für eine Anforderung zum Austausch eines Aktualisierungstokens gegen ein Zugriffstoken:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN
Um ein Refresh - Austausch für ein Zugriffstoken Token, Token Austausch Endpunkt reagiert auf POST - Anfragen durch die folgenden Schritte ausführen:
- Stellen Sie sicher , dass die
client_ididentifiziert die Anforderung Herkunft wie Google, und dass dieclient_secretden erwarteten Wert übereinstimmt. - Stellen Sie sicher, dass das Aktualisierungstoken gültig ist und dass die in der Anforderung angegebene Client-ID mit der Client-ID übereinstimmt, die dem Aktualisierungstoken zugeordnet ist.
- Wenn Sie nicht alle der oben genannten Kriterien überprüfen können, geben eine HTTP 400 Bad Request Fehler mit
{"error": "invalid_grant"}wie der Körper. - Verwenden Sie andernfalls die Benutzer-ID aus dem Aktualisierungstoken, um ein Zugriffstoken zu generieren. Bei diesen Token kann es sich um einen beliebigen Zeichenfolgenwert handeln, sie müssen jedoch den Benutzer und den Client, für den das Token bestimmt ist, eindeutig darstellen und dürfen nicht erraten werden. Notieren Sie bei Zugriffstoken auch die Ablaufzeit des Tokens, normalerweise eine Stunde nach der Ausgabe des Tokens.
- Geben Sie das folgende JSON-Objekt im Hauptteil der HTTPS-Antwort zurück:
{ "token_type": "Bearer", "access_token": " ACCESS_TOKEN ", "expires_in": SECONDS_TO_EXPIRATION }
Benutzerinfo-Anfragen bearbeiten
Der Userinfo - Endpunkt ist eine OAuth 2.0 geschützte Ressource , die Rückkehr Anspruch über den verknüpften Benutzer. Das Implementieren und Hosten des userinfo-Endpunkts ist optional, mit Ausnahme der folgenden Anwendungsfälle:
- Linked Konto Sign-In mit Google One Tap.
- Reibungsfreihe Abonnement auf Android TV.
Nachdem das Zugriffstoken erfolgreich von Ihrem Token-Endpunkt abgerufen wurde, sendet Google eine Anfrage an Ihren userinfo-Endpunkt, um grundlegende Profilinformationen über den verknüpften Nutzer abzurufen.
| Userinfo-Endpunkt-Anforderungsheader | |
|---|---|
Authorization header | Das Zugriffstoken vom Typ Bearer. |
Zum Beispiel, wenn Ihr Userinfo Endpunkt bei verfügbar ist https://myservice.example.com/userinfo könnte eine Anfrage wie folgt aussehen:
GET /userinfo HTTP/1.1 Host: myservice.example.com Authorization: Bearer ACCESS_TOKEN
Führen Sie die folgenden Schritte aus, damit Ihr userinfo-Endpunkt Anfragen verarbeiten kann:
- Extrahieren Sie das Zugriffstoken aus dem Authorization-Header und geben Sie Informationen für den Benutzer zurück, der dem Zugriffstoken zugeordnet ist.
- Wenn der Zugriffstoken ungültig ist, der HTTP 401 Unauthorized Fehler bei der Verwendung von
WWW-AuthenticateResponse - Header. Im Folgenden finden Sie ein Beispiel für eine userinfo Fehlerreaktion:HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
Wenn ein 401 Unauthorized oder jede andere erfolglose Fehlerreaktion während des Verbindungsvorgangs zurückgeführt wird, wird der Fehler nicht mehr erzielbar ist, wird die abgerufene Token verworfen werden und der Benutzer wird um den Verknüpfungsvorgang erneut zu starten. Wenn die Zugriffstoken gültig ist, Rückkehr und HTTP 200 - Antwort mit dem folgende JSON - Objekt in dem Körper der HTTPS - Antwort:
{ "sub": "USER_UUID", "email": "EMAIL_ADDRESS", "given_name": "FIRST_NAME", "family_name": "LAST_NAME", "name": "FULL_NAME", "picture": "PROFILE_PICTURE", }Wenn Ihr Userinfo Endpunkt kehrt eine HTTP 200 Erfolgsantwort, werden die abgerufenen Token und Ansprüche registriert gegen den Benutzer Google Konto.Userinfo-Endpunktantwort subEine eindeutige ID, die den Benutzer in Ihrem System identifiziert. emailE-Mail-Adresse des Benutzers. given_nameOptional: Vorname des Benutzers. family_nameOptional: Nachname des Benutzers. nameOptional: Vollständiger Name des Benutzers. pictureOptional: Profilbild des Nutzers.
Implementierung validieren
Sie können Ihre Implementierung mithilfe der Validierung OAuth 2.0 Spielplatz - Tool.
Führen Sie im Tool die folgenden Schritte aus:
- Klicken Sie auf das OAuth 2.0 - Konfigurationsfenster zu öffnen.
- Im OAuth Strömungsfeld, wählen Sie Client-Seite.
- Im OAuth Endpunkte Feld wählen Sie Benutzerdefiniert.
- Geben Sie Ihren OAuth 2.0-Endpunkt und die Client-ID, die Sie Google zugewiesen haben, in die entsprechenden Felder ein.
- Im Schritt 1 Wählen Sie im Abschnitt keine Google Bereiche. Lassen Sie stattdessen dieses Feld leer oder geben Sie einen für Ihren Server gültigen Bereich ein (oder eine beliebige Zeichenfolge, wenn Sie keine OAuth-Bereiche verwenden). Wenn Sie fertig sind, klicken Sie auf Autorisieren APIs.
- In der Stufe 2 und Stufe 3 Abschnitte, geht durch die OAuth 2.0 fließen und sicherzustellen , dass jeder Schritt wie vorgesehen funktioniert.
Sie können Ihre Implementierung mithilfe der Validierung Google - Konto verknüpfen Demo - Tool.
Führen Sie im Tool die folgenden Schritte aus:
- Klicken Sie auf die Sign-in mit Google - Taste.
- Wählen Sie das Konto aus, das Sie verknüpfen möchten.
- Geben Sie die Service-ID ein.
- Geben Sie optional einen oder mehrere Bereiche ein, für die Sie Zugriff anfordern.
- Klicken Sie auf Start Demo.
- Wenn Sie dazu aufgefordert werden, bestätigen Sie, dass Sie der Verknüpfungsanfrage zustimmen und diese ablehnen können.
- Bestätigen Sie, dass Sie zu Ihrer Plattform weitergeleitet werden.