連結帳戶登入

Google 帳戶連結功能可讓 Google 帳戶持有人快速、順暢且安全地連結至您的服務,並與 Google 分享資料。

已連結帳戶登入功能可讓已將 Google 帳戶連結至您服務的使用者使用 One Tap 登入 Google。這樣一來,使用者就能透過單鍵登入,不必重新輸入使用者名稱和密碼,進而改善使用體驗。這麼做也可以降低使用者在您的服務中建立重複帳戶的可能性。

需求條件

如要導入「已連結帳戶登入」功能,您必須符合下列規定:

  • 您已實作 Google 帳戶 OAuth 連結,支援 OAuth 2.0 授權碼流程。OAuth 實作項目必須包含下列端點:
    • 授權端點,用於處理授權要求。
    • 權杖端點:處理存取和更新權杖的要求。
    • userinfo 端點:擷取已連結使用者的基本帳戶資訊,並在連結帳戶登入程序期間向使用者顯示。
  • 您有 Android 應用程式。

運作方式

前置條件:使用者先前已將自己的 Google 帳戶連結至您服務中的帳戶。

  1. 您可以選擇在 One Tap 登入流程中顯示已連結的帳戶。
  2. 系統會向使用者顯示「One Tap 登入」提示,讓他們選擇以已連結的帳戶登入服務。
  3. 如果使用者選擇繼續使用已連結的帳戶,Google 會向您的符記端點傳送要求,以便儲存授權碼。這項要求包含服務核發的使用者存取權杖和 Google 授權碼。
  4. 您可以將 Google 授權碼換成 Google ID 權杖,其中包含使用者 Google 帳戶的相關資訊。
  5. 流程結束後,應用程式也會收到 ID 權杖,並與伺服器收到的 ID 權杖中的使用者 ID 比對,以便將使用者登入應用程式。
已連結帳戶登入。
圖 1. 已連結帳戶登入流程。如果使用者在裝置上登入了多個帳戶,系統可能會顯示帳戶選擇器,只有在使用者選取已連結的帳戶時,系統才會導向「已連結帳戶登入」檢視畫面。

在 Android 應用程式中實作已連結帳戶登入功能

如要在 Android 應用程式中支援已連結帳戶登入功能,請按照 Android 導入指南中的操作說明進行。

處理來自 Google 的授權碼要求

Google 會向您的權杖端點提出 POST 要求,以儲存您用來交換使用者 ID 權杖的授權碼。要求中包含使用者的存取權杖和 Google 核發的 OAuth2 授權碼。

儲存授權碼前,您必須驗證存取權存證是否由您授予 Google,並由 client_id 識別。

HTTP 要求

要求範例

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

code=GOOGLE_AUTHORIZATION_CODE
&grant_type=urn:ietf:params:oauth:grant-type:reciprocal
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&access_token=ACCESS_TOKEN

您的權杖交換端點必須能夠處理下列要求參數:

權杖端點參數
code 必要 Google OAuth2 授權碼
client_id 必填 您核發給 Google 的用戶端 ID
client_secret 必填 您向 Google 核發的用戶端密鑰
access_token 必填您核發給 Google 的存取權杖。您將使用這個參數取得使用者的背景
grant_type 必填:值必須設為 urn:ietf:params:oauth:grant-type:reciprocal

您的權杖交換端點應透過以下方式回應 POST 要求:

  • 確認 access_token 已授予 client_id 所識別的 Google。
  • 如果要求有效且已成功將驗證碼換成 Google ID 權杖,請傳回 HTTP 200 (OK) 回應;如果要求無效,則傳回 HTTP 錯誤代碼。

HTTP 回應

成功

傳回 HTTP 狀態碼 200 OK

成功回應範例
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{}

錯誤

如果發生無效的 HTTP 要求,請回應下列其中一項 HTTP 錯誤代碼:

HTTP 狀態碼 內文 說明
400 {"error": "invalid_request"} 要求缺少參數,因此伺服器無法繼續處理要求。如果要求包含不支援的參數或重複參數,系統也會傳回此錯誤
401 {"error": "invalid_request"} 用戶端驗證失敗,例如要求包含無效的用戶端 ID 或密鑰
401 {"error": "invalid_token"}

在回應標頭中加入「WWW-Authentication: Bearer」驗證挑戰

合作夥伴存取權杖無效。
403 {"error": "insufficient_permission"}

在回應標頭中加入「WWW-Authentication: Bearer」驗證挑戰

合作夥伴存取權權杖不含執行對等 OAuth 所需的範圍
500 {"error": "internal_error"} 伺服器錯誤

錯誤回應應包含下列欄位:

錯誤回應欄位
error 必填錯誤字串
error_description 使用者可理解的錯誤說明
error_uri 提供錯誤詳細資訊的 URI
錯誤 400 回應範例
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error": "invalid_request",
  "error_description": "Request was missing the 'access_token' parameter."
}

將授權碼換成 ID 權杖

您必須將收到的授權碼換成 Google ID 權杖,其中包含使用者 Google 帳戶的相關資訊。

如要將授權碼換成 Google ID 權杖,請呼叫 https://oauth2.googleapis.com/token 端點並設定下列參數:

要求欄位
client_id 必填從 API 控制台的「憑證」頁面取得的用戶端 ID。這通常是名稱為「Google 應用程式的新動作」的憑證
client_secret 必填 從 API 控制台的「憑證」頁面取得的用戶端密鑰
code 必填 在初始要求中傳送的授權碼
grant_type 必填 如 OAuth 2.0 規格所定義,這個欄位的值必須設為 authorization_code
要求範例
POST /oauth2/v4/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=GOOGLE_AUTHORIZATION_CODE
&grant_type=authorization_code
&client_id=GOOGLE_CLIENT_ID
&client_secret=GOOGLE_CLIENT_SECRET

Google 會傳回 JSON 物件來回應這項要求,其中包含短期存取權杖和重新整理權杖。

回應包含下列欄位:

回應欄位
access_token 應用程式傳送給 Google API 要求的 Google 核發存取憑證,用於授權要求
id_token ID 權杖包含使用者的 Google 帳戶資訊。「驗證回應」部分包含如何解碼及驗證 ID 權杖回應的詳細資訊
expires_in 存取權杖的剩餘生命週期 (以秒為單位)
refresh_token 您可以使用這項權杖取得新的存取權杖。重新整理權杖在使用者撤銷存取權之前有效
scope 在「已連結帳戶登入」用途中,這個欄位的值一律會設為 openid
token_type 傳回的符記類型。此時,這個欄位的值一律會設為 Bearer
回應範例
HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8

{
  "access_token": "Google-access-token",
  "id_token": "Google-ID-token",
  "expires_in": 3599,
  "token_type": "Bearer",
  "scope": "openid",
  "refresh_token": "Google-refresh-token"
}


POST /oauth2/v4/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=Google authorization code
&grant_type=authorization_code
&client_id=Google client id
&client_secret=Google client secret

驗證 ID 權杖回應