Google 帳戶連結功能可讓 Google 帳戶持有人快速、順暢且安全地連結至您的服務,並與 Google 分享資料。
已連結帳戶登入功能可讓已將 Google 帳戶連結至您服務的使用者使用 One Tap 登入 Google。這樣一來,使用者就能透過單鍵登入,不必重新輸入使用者名稱和密碼,進而改善使用體驗。這麼做也可以降低使用者在您的服務中建立重複帳戶的可能性。
需求條件
如要導入「已連結帳戶登入」功能,您必須符合下列規定:
- 您已實作 Google 帳戶 OAuth 連結,支援 OAuth 2.0 授權碼流程。OAuth 實作項目必須包含下列端點:
- 授權端點,用於處理授權要求。
- 權杖端點:處理存取和更新權杖的要求。
- userinfo 端點:擷取已連結使用者的基本帳戶資訊,並在連結帳戶登入程序期間向使用者顯示。
- 您有 Android 應用程式。
運作方式
前置條件:使用者先前已將自己的 Google 帳戶連結至您服務中的帳戶。
- 您可以選擇在 One Tap 登入流程中顯示已連結的帳戶。
- 系統會向使用者顯示「One Tap 登入」提示,讓他們選擇以已連結的帳戶登入服務。
- 如果使用者選擇繼續使用已連結的帳戶,Google 會向您的符記端點傳送要求,以便儲存授權碼。這項要求包含服務核發的使用者存取權杖和 Google 授權碼。
- 您可以將 Google 授權碼換成 Google ID 權杖,其中包含使用者 Google 帳戶的相關資訊。
- 流程結束後,應用程式也會收到 ID 權杖,並與伺服器收到的 ID 權杖中的使用者 ID 比對,以便將使用者登入應用程式。
![已連結帳戶登入。](https://developer.android.com/static/identity/legacy/one-tap/images/linked-account-signin.png?hl=zh-tw)
在 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 物件來回應這項要求,其中包含短期存取權杖和重新整理權杖。
回應包含下列欄位:
回應範例
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