Google-Kontoverknüpfung mit OAuth

Konten werden über die branchenüblichen impliziten und Autorisierungscode-Vorgänge für OAuth 2.0 verknüpft. Ihr Dienst muss OAuth 2.0-konforme Autorisierungs- und Token-Austauschendpunkte unterstützen.

Beim impliziten Ablauf öffnet Google Ihren Autorisierungsendpunkt im Browser des Nutzers. Nach der erfolgreichen Anmeldung geben Sie ein langlebiges Zugriffstoken an Google zurück. Dieses Zugriffstoken ist jetzt in jeder Anfrage enthalten, die von Google gesendet wird.

Für den Ablauf mit Autorisierungscode sind zwei Endpunkte erforderlich:

  • Den Autorisierungsendpunkt, der noch nicht angemeldeten Nutzern die Anmelde-UI anzeigt. Der Autorisierungsendpunkt erstellt auch einen kurzlebigen Autorisierungscode, um die Einwilligung der Nutzer in den angeforderten Zugriff zu erfassen.

  • Der Token-Austausch-Endpunkt, der für zwei Arten von Anzeigenplattformen verantwortlich ist:

    1. Hier wird ein Autorisierungscode gegen ein langlebiges Aktualisierungstoken und ein kurzlebiges Zugriffstoken eingetauscht. Dieser Austausch erfolgt, wenn der Nutzer die Kontoverknüpfung durchläuft.
    2. Ein langlebiges Aktualisierungstoken wird gegen ein kurzlebiges Zugriffstoken eingetauscht. Dieser Austausch erfolgt, wenn Google ein neues Zugriffstoken benötigt, weil das vorherige abgelaufen ist.

OAuth 2.0-Vorgang auswählen

Der implizite Ablauf ist zwar einfacher zu implementieren, Google empfiehlt jedoch, dass die über den impliziten Ablauf ausgestellten Zugriffstokens nie ablaufen. Das liegt daran, dass der Nutzer beim impliziten Ablauf gezwungen wird, sein Konto noch einmal zu verknüpfen, nachdem ein Token abgelaufen ist. Wenn Sie aus Sicherheitsgründen ein Ablaufdatum für Tokens benötigen, empfehlen wir Ihnen dringend, stattdessen den Ablaufvorgang für Autorisierungscodes zu verwenden.

Gestaltungsrichtlinien

In diesem Abschnitt werden die Designanforderungen und -empfehlungen für den Nutzerbildschirm beschrieben, den Sie für OAuth-Verknüpfungsvorgänge hosten. Nachdem die Funktion von der Google-App aufgerufen wurde, wird dem Nutzer auf Ihrer Plattform eine Seite zur Anmeldung bei Google und ein Bildschirm zur Einwilligung in die Kontoverknüpfung angezeigt. Nachdem der Nutzer seine Einwilligung zur Kontoverknüpfung gegeben hat, wird er zur Google-App zurückgeleitet.

Auf dieser Abbildung sind die Schritte zu sehen, die ein Nutzer ausführen muss, um sein Google-Konto mit Ihrem Authentifizierungssystem zu verknüpfen. Der erste Screenshot zeigt eine vom Nutzer initiierte Verknüpfung auf Ihrer Plattform. Das zweite Bild zeigt die Anmeldung des Nutzers bei Google. Auf dem dritten Bild ist die Einwilligung und Bestätigung des Nutzers zur Verknüpfung seines Google-Kontos mit Ihrer App zu sehen. Der letzte Screenshot zeigt ein erfolgreich verknüpftes Nutzerkonto in der Google App.
Abbildung 1. Kontoverknüpfung, Nutzeranmeldung bei Google und Einwilligungsbildschirme

Voraussetzungen

  1. Du musst angeben, dass das Konto des Nutzers mit Google verknüpft wird und nicht mit einem bestimmten Google-Produkt wie Google Home oder Google Assistant.

Empfehlungen

Wir empfehlen Folgendes:

  1. Datenschutzerklärung von Google anzeigen Fügen Sie im Zustimmungsbildschirm einen Link zur Datenschutzerklärung von Google ein.

  2. Zu teilende Daten: Informieren Sie die Nutzer in einer klaren und prägnanten Sprache darüber, welche Daten von ihnen Google benötigt und warum.

  3. Klarer Call-to-Action Geben Sie auf dem Einwilligungsbildschirm einen klaren Call-to-Action an, z. B. „Zustimmen und verknüpfen“. Nutzer müssen wissen, welche Daten sie mit Google teilen müssen, um ihre Konten zu verknüpfen.

  4. Kündigung möglich. Bieten Sie Nutzern die Möglichkeit, zurückzugehen oder abzubrechen, wenn sie die Verknüpfung nicht herstellen möchten.

  5. Klarer Anmeldevorgang. Achten Sie darauf, dass Nutzer eine eindeutige Methode für die Anmeldung in ihrem Google-Konto haben, z. B. Felder für ihren Nutzernamen und das Passwort oder Über Google anmelden.

  6. Möglichkeit, die Verknüpfung aufzuheben Bieten Sie Nutzern die Möglichkeit, die Verknüpfung aufzuheben, z. B. über eine URL zu ihren Kontoeinstellungen auf Ihrer Plattform. Alternativ können Sie einen Link zum Google-Konto einfügen, über den Nutzer ihr verknüpftes Konto verwalten können.

  7. Berechtigung zum Ändern des Nutzerkontos. Schlage Nutzern eine Methode vor, mit der sie ihr Konto bzw. ihre Konten wechseln können. Das ist besonders hilfreich, wenn Nutzer mehrere Konten haben.

    • Wenn ein Nutzer den Einwilligungsbildschirm schließen muss, um das Konto zu wechseln, senden Sie einen wiederherstellbaren Fehler an Google, damit sich der Nutzer mit der OAuth-Verknüpfung und dem impliziten Ablauf im gewünschten Konto anmelden kann.
  8. Fügen Sie Ihr Logo hinzu. Zeigen Sie Ihr Firmenlogo auf dem Einwilligungsbildschirm an. Verwenden Sie die Stilrichtlinien, um Ihr Logo zu platzieren. Wenn Sie auch das Google-Logo anzeigen lassen möchten, lesen Sie den Hilfeartikel Logos und Marken.

Create the project

To create your project to use account linking:

  1. Go to the Google API Console.
  2. 单击创建项目
  3. 输入名称或接受生成的建议。
  4. 确认或编辑所有剩余字段。
  5. 点击创建

要查看您的项目ID:

  1. Go to the Google API Console.
  2. 在登录页面的表格中找到您的项目。项目ID出现在ID列中。

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.

  1. Open the OAuth consent screen page of the Google APIs console.
  2. If prompted, select the project you just created.
  3. 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

  4. 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

To support the OAuth 2.0 implicit flow, your service makes an authorization endpoint available by HTTPS. This endpoint is responsible for authentication and obtaining consent from users for data access. The authorization endpoint presents a sign-in UI to your users that aren't already signed in and records consent to the requested access.

When a Google application needs to call one of your service's authorized APIs, Google uses this endpoint to get permission from your users to call these APIs on their behalf.

A typical OAuth 2.0 implicit flow session initiated by Google has the following flow:

  1. Google opens your authorization endpoint in the user's browser. The user signs in, if not signed in already, and grants Google permission to access their data with your API, if they haven't already granted permission.
  2. Your service creates an access token and returns it to Google. To do so, redirect the user's browser back to Google with the access token attached to the request.
  3. Google calls your service's APIs and attaches the access token with each request. Your service verifies that the access token grants Google authorization to access the API and then completes the API call.

Handle authorization requests

When a Google application needs to perform account linking via an OAuth 2.0 implicit flow, Google sends the user to your authorization endpoint with a request that includes the following parameters:

Authorization endpoint parameters
client_id The client ID you assigned to Google.
redirect_uri The URL to which you send the response to this request.
state A bookkeeping value that is passed back to Google unchanged in the redirect URI.
response_type The type of value to return in the response. For the OAuth 2.0 implicit flow, the response type is always token.
user_locale The Google Account language setting in RFC5646 format used to localize your content in the user's preferred language.

For example, if your authorization endpoint is available at https://myservice.example.com/auth, a request might look like the following:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE

For your authorization endpoint to handle sign-in requests, do the following steps:

  1. Verify the client_id and redirect_uri values to prevent granting access to unintended or misconfigured client apps:

    • Confirm that the client_id matches the client ID you assigned to Google.
    • Confirm that the URL specified by the redirect_uri parameter has the following form:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
      
  2. Check if the user is signed in to your service. If the user isn't signed in, complete your service's sign-in or sign-up flow.

  3. Generate an access token for Google to use to access your API. The access token can be any string value, but it must uniquely represent the user and the client the token is for and must not be guessable.

  4. Send an HTTP response that redirects the user's browser to the URL specified by the redirect_uri parameter. Include all of the following parameters in the URL fragment:

    • access_token: The access token you just generated
    • token_type: The string bearer
    • state: The unmodified state value from the original request

    The following is an example of the resulting URL:

    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Google's OAuth 2.0 redirect handler receives the access token and confirms that the state value hasn't changed. After Google has obtained an access token for your service, Google attaches the token to subsequent calls to your service APIs.

处理 userinfo 请求

userinfo 端点是受 OAuth 2.0 保护的资源,会返回关联用户的声明。实现和托管 userinfo 端点是可选的,但以下用例除外:

从您的令牌端点成功检索到访问令牌后,Google 会向您的 userinfo 端点发送请求,以检索关联用户的基本个人资料信息。

userinfo 端点请求标头
Authorization header Bearer 类型的访问令牌。

例如,如果您的 userinfo 端点可通过 https://myservice.example.com/userinfo 时,请求可能如下所示:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

为了让 userinfo 端点能够处理请求,请执行以下步骤:

  1. 从 Authorization 标头中提取访问令牌,并返回与访问令牌相关联的用户的信息。
  2. 如果访问令牌无效,则使用 WWW-Authenticate 响应标头返回 HTTP 401 Unauthorized 错误。下面是一个 userinfo 错误响应示例:
    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: error="invalid_token",
    error_description="The Access Token expired"
    
    如果在关联过程中返回 401 未经授权错误或任何其他失败的错误响应,该错误将无法恢复,检索到的令牌将被舍弃,并且用户必须重新开始关联流程。
  3. 如果访问令牌有效,则返回 HTTPS 正文中包含以下 JSON 对象的 HTTP 200 响应 回复:

    {
    "sub": "USER_UUID",
    "email": "EMAIL_ADDRESS",
    "given_name": "FIRST_NAME",
    "family_name": "LAST_NAME",
    "name": "FULL_NAME",
    "picture": "PROFILE_PICTURE",
    }
    
    如果您的 userinfo 端点返回 HTTP 200 成功响应,则系统会针对用户的 Google 账号注册检索到的令牌和声明。

    userinfo 端点响应
    sub 系统中用于识别用户的唯一 ID。
    email 用户的电子邮件地址。
    given_name 可选:用户的名字。
    family_name 可选:用户的姓氏。
    name 可选:用户的全名。
    picture 可选:用户的个人资料照片。

Implementierung validieren

您可以使用 OAuth 2.0 Playground 工具验证您的实现。

在该工具中,执行以下步骤:

  1. 点击配置 以打开 OAuth 2.0 配置窗口。
  2. OAuth flow 字段中,选择 Client-side(客户端)。
  3. OAuth 端点字段中,选择自定义
  4. 在相应字段中指定您的 OAuth 2.0 端点和您分配给 Google 的客户端 ID。
  5. 第 1 步部分,不要选择任何 Google 范围。请将此字段留空或输入对服务器有效的范围(如果您不使用 OAuth 范围,则可以输入任意字符串)。完成后,点击授权 API
  6. Step 2Step 3 部分中,完成 OAuth 2.0 流程,并验证每个步骤是否按预期运行。

您可以使用 Google 账号关联演示版工具验证您的实现。

在该工具中,执行以下步骤:

  1. 点击使用 Google 账号登录按钮。
  2. 选择您要关联的账号。
  3. 输入服务 ID。
  4. (可选)输入您要请求访问权限的一个或多个范围。
  5. 点击开始演示
  6. 当系统提示时,请确认您同意或拒绝关联请求。
  7. 确认您已被重定向到您的平台。