使用 OAuth 連結 Google 帳戶

帳戶是透過業界標準的 OAuth 2.0 隱含和授權碼流程連結。

您的服務必須支援符合 OAuth 2.0 規範的授權和權杖交換端點。

In the implicit flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from Google.

In the authorization code flow, you need two endpoints:

  • The authorization endpoint, which presents the sign-in UI to your users that aren't already signed in. The authorization endpoint also creates a short-lived authorization code to record users' consent to the requested access.

  • The token exchange endpoint, which is responsible for two types of exchanges:

    1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
    2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Choose an OAuth 2.0 flow

Although the implicit flow is simpler to implement, Google recommends that access tokens issued by the implicit flow never expire. This is because the user is forced to link their account again after a token expires with the implicit flow. If you need token expiration for security reasons, we strongly recommend that you use the authorization code flow instead.

Design guidelines

This section describes the design requirements and recommendations for the user screen that you host for OAuth linking flows. After it's called by Google's app, your platform displays a sign in to Google page and account linking consent screen to the user. The user is directed back to Google's app after giving their consent to link accounts.

This figure shows the steps for a user to link their Google account to your authentication system. The first screenshot shows user-initiated linking from your platform. The second image shows user sign-in to Google, while the third shows the user consent and confirmation for linking their Google account with your app. The final screenshot shows a successfully linked user account in the Google app.
Figure 1. Account linking user sign in to Google and consent screens.

Requirements

  1. You must communicate that the user's account will be linked to Google, not a specific Google product like Google Home or Google Assistant.

Recommendations

We recommend that you do the following:

  1. Display Google's Privacy Policy. Include a link to Google's Privacy Policy on the consent screen.

  2. Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.

  3. Clear call-to-action. State a clear call-to-action on your consent screen, such as "Agree and link." This is because users need to understand what data they're required to share with Google to link their accounts.

  4. Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.

  5. Clear sign-in process. Ensure that users have clear method for signing in to their Google Account, such as fields for their username and password or Sign in with Google.

  6. Ability to unlink. Offer a mechanism for users to unlink, such as a URL to their account settings on your platform. Alternatively, you can include a link to Google Account where users can manage their linked account.

  7. Ability to change user account. Suggest a method for users to switch their account(s). This is especially beneficial if users tend to have multiple accounts.

    • If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the selected account with OAuth linking and the implicit flow.

  8. Include your logo. Display your company logo on the consent screen. Use your style guidelines to place your logo. If you want or need to also display Google's logo, see Logos and trademarks.

Create the project

To create your project to use account linking:

  1. Go to the Google API Console.
  2. Click Create project.
  3. Enter a name or accept the generated suggestion.
  4. Confirm or edit any remaining fields.
  5. Click Create.

To view your project ID:

  1. Go to the Google API Console.
  2. Find your project in the table on the landing page. The project ID appears in the ID column.

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 伺服器

n

如要支援 OAuth 2.0 隱含流程，您的服務會透過 HTTPS 提供授權端點。這個端點負責驗證，並取得使用者同意授權資料存取權。授權端點會向尚未登入的使用者顯示登入 UI，並記錄對所要求存取權的同意聲明。

當 Google 應用程式需要呼叫您服務的授權 API 時，Google 會使用這個端點取得使用者授權，代表他們呼叫這些 API。

Google 帳戶連結：OAuth 隱含流程

下方的序列圖詳細說明使用者、Google 和服務端點之間的互動。

使用者 Google 應用程式/瀏覽器 您的驗證端點 1. 使用者啟動連結程序 2. 重新導向至驗證端點 (GET) client_id、redirect_uri、state、scope 3. 顯示登入和同意畫面 4. 使用者驗證身分並授予同意聲明 5. 使用權杖重新導向回 Google (GET) access_token、state 6. 儲存使用者權杖 7. 存取使用者資源
圖 1. OAuth 2.0 隱含流程中的事件順序，適用於 Google 帳戶連結。

角色與職責

下表定義 Google 帳戶連結 (GAL) OAuth 隱含流程中參與者的角色和職責。請注意，在 GAL 中，Google 會擔任 OAuth 用戶端，而您的服務則擔任身分/服務供應商。

執行者 / 元件 GAL 角色 職責
Google 應用程式 / 伺服器 OAuth 用戶端 啟動流程、透過瀏覽器重新導向接收存取權杖，並安全地儲存權杖，以便存取服務的 API。
您的授權端點 授權伺服器 驗證使用者身分、取得使用者同意聲明，並直接向 Google 發放長期存取權杖。
Google 重新導向 URI 回呼端點 從授權服務接收使用者重新導向，網址片段中包含 access_token 和 state 值。

Google 啟動的一般 OAuth 2.0 隱含流程工作階段如下：

  1. Google 會在使用者瀏覽器中開啟授權端點。使用者登入 (如果尚未登入)，並授權 Google 透過您的 API 存取資料 (如果尚未授權)。
  2. 您的服務會建立存取權杖，並傳回給 Google。如要這麼做，請將使用者的瀏覽器重新導向回 Google，並在要求中附加存取權杖。
  3. Google 會呼叫服務的 API，並在每個要求中附加存取權杖。服務會驗證存取權杖是否授權 Google 存取 API，然後完成 API 呼叫。

處理授權要求

當 Google 應用程式需要使用 OAuth 2.0 隱含流程執行帳戶連結時，Google 會將使用者傳送至授權端點，並在要求中加入下列參數：

授權端點參數
client_id 您指派給 Google 的用戶端 ID。
redirect_uri 您用來傳送此要求回覆的網址。
state 會傳回給 Google 的記帳值，且在重新導向 URI 中不會變更。
response_type 要在回應中傳回的值類型。如果是 OAuth 2.0 隱含流程，回應類型一律為 token。
user_locale Google 帳戶語言設定 (RFC5646 格式)，用於以使用者偏好的語言顯示內容。

舉例來說，如果授權端點位於 https://myservice.example.com/auth，要求可能如下所示：

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

如要讓授權端點處理登入要求，請按照下列步驟操作：

  1. 驗證 client_id 和 redirect_uri 值，避免將存取權授予非預期或設定錯誤的用戶端應用程式：

    • 確認 client_id 與您指派給 Google 的用戶端 ID 相符。
    • 確認 redirect_uri 參數指定的網址符合下列格式：
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

  2. 確認使用者是否已登入您的服務。如果使用者未登入，請完成服務的登入或註冊流程。

  3. 產生存取權杖，供 Google 用來存取您的 API。存取權杖可以是任何字串值，但必須代表使用者和權杖所屬的用戶端，且不得可供猜測。

  4. 傳送 HTTP 回應，將使用者的瀏覽器重新導向至 redirect_uri 參數指定的網址。在網址片段中加入下列所有參數：

    • access_token：您剛產生的存取權杖
    • token_type：字串 bearer
    • state：原始要求中未修改的狀態值

    以下是產生的網址範例： 

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

Google 的 OAuth 2.0 重新導向處理常式會接收存取權杖，並確認 state 值未變更。Google 取得服務的存取權杖後，會將權杖附加至後續對服務 API 的呼叫。

Handle userinfo requests

The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:

After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.

userinfo endpoint request headers
Authorization header The access token of type Bearer.

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

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

For your userinfo endpoint to handle requests, do the following steps:

  1. Extract access token from the Authorization header and return information for the user associated with the access token.
  2. If the access token is invalid, return an HTTP 401 Unauthorized error with using the WWW-Authenticate Response Header. Below is an example of a userinfo error response: 
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again.

  3. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response: 

    {
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}
     If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.

    userinfo endpoint response
    sub A unique ID that identifies the user in your system.
    email Email address of the user.
    given_name Optional: First name of the user.
    family_name Optional: Last name of the user.
    name Optional: Full name of the user.
    picture Optional: Profile picture of the user.

驗證實作

您可以使用 OAuth 2.0 Playground 工具驗證實作成果。

在工具中執行下列步驟：

  1. 點選「設定」 開啟「OAuth 2.0 設定」視窗。
  2. 在「OAuth flow」欄位中，選取「用戶端」。
  3. 在「OAuth Endpoints」(OAuth 端點) 欄位中，選取「Custom」(自訂)。
  4. 在對應欄位中，指定 OAuth 2.0 端點和您指派給 Google 的用戶端 ID。
  5. 在「步驟 1」部分，請勿選取任何 Google 範圍。請將這個欄位留空，或輸入適用於伺服器的範圍 (如果您未使用 OAuth 範圍，則輸入任意字串)。完成後，請按一下「授權 API」。
  6. 在「步驟 2」和「步驟 3」部分，請完成 OAuth 2.0 流程，並確認每個步驟都能正常運作。

您可以使用 Google 帳戶連結示範工具驗證實作項目。

在工具中執行下列步驟：

  1. 按一下「使用 Google 帳戶登入」按鈕。
  2. 選擇要連結的帳戶。
  3. 輸入服務 ID。
  4. 選擇性輸入您要要求存取的一或多個範圍。
  5. 按一下「開始試用」。
  6. 系統顯示提示時，確認您要同意或拒絕連結要求。
  7. 確認系統會將你重新導向至平台。