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 的徽标，请参阅徽标和商标。
Projekt erstellen
So erstellen Sie Ihr Projekt für die Kontoverknüpfung:
- 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.
OAuth-Zustimmungsbildschirm konfigurieren
Die Google-Kontoverknüpfung umfasst einen Zustimmungsbildschirm, auf dem Nutzer über die App informiert werden, die Zugriff auf ihre Daten anfordert, welche Art von Daten sie anfordern und welche Nutzungsbedingungen gelten. Sie müssen den OAuth-Zustimmungsbildschirm konfigurieren, bevor Sie eine Google API-Client-ID generieren.
- Öffnen Sie die Seite OAuth-Zustimmungsbildschirm der Google APIs-Konsole.
- Wenn Sie dazu aufgefordert werden, wählen Sie das soeben erstellte Projekt aus.
Füllen Sie auf der Seite „OAuth-Zustimmungsbildschirm“ das Formular aus und klicken Sie auf die Schaltfläche „Speichern“.
Name der App:Der Name der App, die um Ihre Einwilligung gebeten wird. Der Name sollte genau zu Ihrer App passen und mit dem App-Namen übereinstimmen, den Nutzer an anderer Stelle sehen. Der Name der App wird auf dem Zustimmungsbildschirm für die Kontoverknüpfung angezeigt.
App-Logo:Ein Bild auf dem Zustimmungsbildschirm, anhand dessen Nutzer Ihre App erkennen. Das Logo wird auf dem Zustimmungsbildschirm für die Kontoverknüpfung und in den Kontoeinstellungen angezeigt.
Support-E-Mail-Adresse:Diese E-Mail-Adresse richtet sich an Nutzer, die Fragen zu ihrer Einwilligung haben.
Bereiche für Google APIs:Mit Bereichen kann Ihre Anwendung auf die privaten Google-Daten Ihrer Nutzer zugreifen. Für den Anwendungsfall „Google-Kontoverknüpfung“ ist der Standardbereich (E-Mail-Adresse, Profil, OpenID) ausreichend. Sie müssen keine vertraulichen Bereiche hinzufügen. Im Allgemeinen empfiehlt es sich, Bereiche inkrementell anzufordern, und zwar dann, wenn Zugriff erforderlich ist, und nicht im Voraus. Weitere Informationen
Autorisierte Domains:Google lässt zu Ihrem Schutz und Ihrer Nutzer nur Anwendungen zu, die sich über OAuth authentifizieren, um autorisierte Domains zu verwenden. Die Links Ihrer Anwendungen müssen in autorisierten Domains gehostet werden. Weitere Informationen
Link zur Startseite der App:Startseite Ihrer App. Muss in einer autorisierten Domain gehostet werden.
Link zur Datenschutzerklärung der Anwendung:Wird auf dem Zustimmungsbildschirm für die Google-Kontoverknüpfung angezeigt. Muss in einer autorisierten Domain gehostet werden.
Link zu den Nutzungsbedingungen der Anwendung (optional): Muss in einer autorisierten Domain gehostet werden.
Abbildung 1. Zustimmungsbildschirm für die Google-Kontoverknüpfung für eine fiktive App, Tunery
Klicken Sie unter „Bestätigungsstatus“ auf „Bestätigungsstatus“. Wenn Ihr Antrag überprüft werden muss, klicken Sie auf die Schaltfläche „Zur Überprüfung einreichen“. Weitere Informationen finden Sie unter Anforderungen für die OAuth-Bestätigung.
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
您可以通过使用验证实现的OAuth 2.0游乐场工具。
在工具中，执行以下步骤：
- 单击配置打开的OAuth 2.0配置窗口。
- 在OAuth流场中，选择客户端。
- 在OAuth端点字段中，选择自定义。
- 在相应字段中指定您的 OAuth 2.0 端点和您分配给 Google 的客户端 ID。
- 在步骤1部分，不要选择任何谷歌范围。相反，将此字段留空或键入对您的服务器有效的范围（如果不使用 OAuth 范围，则输入任意字符串）。当您完成后，单击授权的API。
- 在步骤2和步骤3段，完成OAuth 2.0流程和验证每个步骤按预期工作。
您可以通过验证您的实现谷歌帐户链接演示工具。
在工具中，执行以下步骤：
- 点击登录在与谷歌按钮。
- 选择您要关联的帐户。
- 输入服务标识。
- （可选）输入您将请求访问的一个或多个范围。
- 单击开始演示。
- 出现提示时，确认您可以同意并拒绝链接请求。
- 确认您被重定向到您的平台。