您的帳戶連結 API

本參考頁面記錄了服務必須實作的 API 端點，才能支援與 Google 帳戶連結。包括以 OAuth 為基礎的帳戶連結、簡化的帳戶連結和應用程式切換。

必要條件和標準

如要順利實作這些端點，服務必須遵守下列標準：

  • OAuth 2.0：符合 RFC 6749 規範。
  • 權杖撤銷：符合 RFC 7009 規範。
  • JSON Web Token (JWT)：符合 RFC 7519 規定 (簡化連結的必要條件)。
  • HTTPS：所有端點都必須透過安全的 HTTPS 連線提供服務。

授權端點

授權端點負責驗證使用者身分，並取得使用者同意，將帳戶連結至 Google。

  • 網址：在 Actions 或 Google Cloud 控制台中設定。
  • 方法： GET

要求參數

參數 說明
client_id 您指派給 Google 的用戶端 ID。
redirect_uri 您用來傳送此要求回覆的網址。
state 傳回給 Google 的記帳值，在重新導向 URI 中不會變更。
response_type 授權碼流程必須為 code。
scope (選用) 以空格分隔的 Google 要求資料範圍清單。
user_locale (選用) Google 帳戶語言設定，使用 BCP-47 語言代碼指定 (例如 en-US)。

權杖交換端點

這個端點負責將授權碼換成權杖，以及更新過期的存取權杖。

  • 網址：在 Actions 或 Google Cloud 控制台中設定。
  • 方法： POST
  • Content-Type: application/x-www-form-urlencoded

交換憑證的授權碼

初始權杖交換要求會使用下列參數。

要求參數

參數 說明
client_id 您指派給 Google 的用戶端 ID。
client_secret 您指派給 Google 的用戶端密鑰。
grant_type 必須為 authorization_code。
code 從授權端點收到的授權碼。
redirect_uri 與初始要求中使用的重新導向 URI 相同。

以重新整理權杖換取存取權杖

更新存取權杖時會使用下列參數。

要求參數

參數 說明
client_id 您指派給 Google 的用戶端 ID。
client_secret 您指派給 Google 的用戶端密鑰。
grant_type 必須為 refresh_token。
refresh_token 先前發給 Google 的重新整理權杖。

回應 (JSON)

傳回成功的回應，並在 HTTPS 回應主體中加入 JSON 物件。

  • HTTP 狀態： 200 OK
  • Content-Type: application/json;charset=UTF-8
欄位 說明
token_type 必要。必須為 bearer。
access_token 必要。用於存取服務 API 的短期權杖。
refresh_token authorization_codegrant_type 的必要條件。用於取得新存取權杖的長期權杖。
expires_in 必要。存取權杖的剩餘生命週期 (以秒為單位)。

錯誤回應

如果對權杖端點的要求失敗，請傳回 HTTP 400 Bad Request 錯誤，以及包含下列欄位的 JSON 回應：

  • HTTP 狀態： 400 Bad Request
  • Content-Type: application/json;charset=UTF-8
錯誤欄位 (JSON) 說明
error 必要。必須為 invalid_grant。
error_description (選用) 提供額外資訊的文字，方便使用者閱讀。

處理簡化的連結意圖

如果服務支援簡化帳戶連結 (使用 Google 登入的 OAuth)，權杖交換端點也必須支援 JSON Web Token (JWT) 聲明，並實作 check、create 和 get 意圖。

這些要求會使用下列參數：

要求參數

參數 說明
intent 要求的特定簡化連結意圖：check、get 或 create。
grant_type 對於這類要求，這個參數的值一律為 urn:ietf:params:oauth:grant-type:jwt-bearer。
assertion JSON Web Token (JWT)，提供 Google 使用者身分的已簽署聲明。JWT 包含使用者 Google 帳戶 ID、名稱和電子郵件地址等資訊。

您的伺服器必須使用「JWT 驗證」一節中列出的條件驗證這個 JWT。
client_id 您指派給 Google 的用戶端 ID。
client_secret 您指派給 Google 的用戶端密鑰。
scope 選用：您已設定 Google 向使用者要求的任何範圍。通常會在 get 和 create 意圖中出現。
response_type create 意圖的必要條件：必須設為 token。

JWT 驗證

為確保簡化連結的安全性，伺服器必須使用下列條件驗證 assertion (JWT)：

  • 簽章：使用 Google 的公開金鑰 (可透過 Google 的 JWK 端點取得) 驗證簽章。
  • 發卡機構 (iss)：必須為 https://accounts.google.com。
  • 目標對象 (aud)：必須與指派給整合的 Google API 用戶端 ID 相符。
  • 到期日 (exp)：必須是未來的日期。

對 check 意圖的回應

使用 intent=check 的要求會驗證 Google 帳戶 (由已解碼 JWT 聲明中的 sub 或 email 憑證附加資訊識別) 是否存在於使用者資料庫中。

  • HTTP 狀態： 200 OK (找到帳戶) 或 404 Not Found (找不到帳戶)
  • Content-Type: application/json;charset=UTF-8
欄位 說明
account_found 必要。如果帳戶存在，則為 true，否則為 false。

對 get 意圖的回應

intent=get 的要求會為現有 Google 帳戶要求存取權杖。

  • HTTP 狀態： 200 OK
  • Content-Type: application/json;charset=UTF-8

成功的回應 JSON 物件與標準權杖交換回應 (傳回 access_token、refresh_token 等) 的結構完全相同。

如果帳戶無法連結，系統會傳回 HTTP 401 錯誤。

  • HTTP 狀態： 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
錯誤欄位 (JSON) 說明
error 必要。必須為 linking_error。
login_hint (選用) 要傳遞至備用 OAuth 連結流程的使用者電子郵件地址。

對 create 意圖的回應

要求使用 JWT 中提供的資訊建立新的使用者帳戶。intent=create

  • HTTP 狀態： 200 OK
  • Content-Type: application/json;charset=UTF-8

成功的回應 JSON 物件與標準權杖交換回應 (傳回 access_token、refresh_token 等) 的結構完全相同。

如果使用者已存在，系統會傳回 HTTP 401 錯誤，提示使用者連結現有帳戶。

  • HTTP 狀態： 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
錯誤欄位 (JSON) 說明
error 必要。必須為 linking_error。
login_hint 要傳遞至備用 OAuth 連結流程的使用者電子郵件地址。

UserInfo 端點 (選用)

用於擷取連結使用者的基本設定檔資訊，如 OpenID Connect Core 1.0 規格所述。這是使用「簡化連結」或「一鍵登入」等功能的必要條件。

  • 方法： GET
  • 驗證： Authorization: Bearer ACCESS_TOKEN

回應 (JSON)

傳回成功的回應，並在 HTTPS 回應主體中加入 JSON 物件。

  • HTTP 狀態： 200 OK
  • Content-Type: application/json;charset=UTF-8

回應欄位

欄位 說明
sub 必要。您系統中可識別使用者的專屬 ID。
email 必要。使用者的電子郵件地址。
email_verified 必要。布林值，指出電子郵件地址是否已通過驗證。
given_name (選用) 使用者的名字。
family_name (選用) 使用者的姓氏。
name (選用) 使用者全名。
picture (選用) 使用者個人資料相片的網址。

錯誤回應

如果存取權杖無效或已過期，請傳回 HTTP 401 Unauthorized 錯誤。您也應加入 WWW-Authenticate 回應標頭。

在連結程序中傳回的任何不成功回應 (4xx 或 5xx) 都視為無法復原。在這些情況下，Google 會捨棄所有擷取的權杖，使用者必須重新啟動帳戶連結程序。

權杖撤銷端點 (選填)

允許 Google 在使用者取消連結帳戶與 Google 服務時，通知您的服務。這個端點必須符合 RFC 7009 所述的規定。

  • 方法： POST
  • Content-Type: application/x-www-form-urlencoded

要求參數

參數 說明
client_id 這個字串可將要求來源識別為 Google。這個字串必須在系統中註冊為 Google 的專屬 ID。
client_secret 你向 Google 註冊的服務專用密鑰。
token 要撤銷的權杖。
token_type_hint (選用) 遭撤銷的符記類型提示，可以是 access_token 或 refresh_token。如未指定，則會預設為 access_token。

回應

如果權杖已成功刪除或無效，請傳回成功回應。

  • HTTP 狀態： 200 OK
  • Content-Type: application/json;charset=UTF-8

錯誤回應

如果因任何原因 (例如資料庫無法使用) 無法刪除權杖，請傳回 HTTP 503 錯誤。Google 會在稍後或 Retry-After 標頭指定的時間重試要求。

  • HTTP 狀態： 503 Service Unavailable
  • Content-Type: application/json;charset=UTF-8
  • 標題： Retry-After: <HTTP-date / delay-seconds>