Google Account Linking API

本參考頁面記錄了應用程式在以 OAuth 為基礎的帳戶連結程序中使用的 Google 端點和介面。

必要條件和標準

如要順利與這些 Google 端點互動，整合服務必須遵守下列標準：

  • OAuth 2.0：符合 RFC 6749 規範。
  • JSON Web Token (JWT)：符合 RFC 7519 (適用於簡化連結和 RISC)。
  • 安全性事件權杖：符合 RFC 8417 (適用於 RISC)。
  • HTTPS：所有要求都必須透過安全的 HTTPS 連線發出。

OAuth 重新導向 URI

服務在驗證和同意程序完成後，將使用者瀏覽器重新導向的端點。YOUR_PROJECT_ID 路徑參數是您在註冊時設定的 ID。

  • 網址： https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

  • 沙箱網址： https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

  • 方法： GET (使用瀏覽器重新導向)

要求參數

將使用者重新導向回 Google 時，必須在網址中附加參數。視使用的 OAuth 流程而定，這些參數會格式化為查詢字串 (授權碼流程) 或網址片段 (隱含流程)。

參數 說明
code (授權碼流程的必要參數) 服務產生的授權碼。
state (必要) 最初從 Google 收到的未修改狀態值。
access_token (隱含流程的必要條件) 服務產生的長期存取權杖。
token_type (隱含流程的必要條件) 必須為 bearer。

錯誤回應

如果對 OAuth 重新導向 URI 的要求格式錯誤，您會收到 HTTP 400 Bad Request 錯誤。回應主體會包含 JSON 物件，結構如下：

欄位 說明
sendPostBody 決定 JS 是否應使用 POST 重新導向至 redirectUri。通常是 false。
errorMessage 無法完成重新導向時，要向用戶端顯示的錯誤訊息。如果是缺少的片段，則為 "A URI fragment or query string must be set."

OAuth 2.0 錯誤回應

如果使用者拒絕授權，或服務發生錯誤，服務必須使用標準 OAuth 2.0 錯誤參數 (例如 error=access_denied)，將使用者重新導向至 OAuth 重新導向 URI。Google 會處理這些參數，並向使用者顯示適當的錯誤畫面。

RISC API (選用)

當使用者透過 RISC 通訊協定取消連結平台上的帳戶時，服務會主動通知 Google，確保兩個平台保持同步。

  • 網址： https://risc.googleapis.com/v1/events:publish
  • 方法： POST
  • 驗證：需要具備適當權限的 Google 服務帳戶權杖。
  • Content-Type: application/json

安全事件權杖聲明

您用來通知 Google 權杖撤銷事件的安全事件權杖，必須符合下表中的規定：

權杖附加資訊 說明
iss 發行者聲明：這是您代管的網址，註冊時會提供給 Google。
aud 目標對象聲明：這項聲明會將 Google 識別為 JWT 接收者。必須設為 google_account_linking。
jti JWT ID 聲明：這是您為每個安全事件權杖產生的專屬 ID。
iat 簽發時間聲明：這是 NumericDate 值，代表建立這個安全事件權杖的時間。
toe 事件聲明時間：這是選用的 NumericDate 值，代表權杖遭撤銷的時間。
exp 到期時間聲明：「請勿」加入這個欄位，因為導致這則通知的事件已發生。
events 安全事件聲明：這是 JSON 物件，且必須只包含單一權杖撤銷事件，內含下列欄位：

  • subject_type：必須設為 oauth_token。
  • token_type：這是要撤銷的權杖類型，可以是 access_token 或 refresh_token。
  • token_identifier_alg：這是用來編碼權杖的演算法，必須為 hash_SHA512_double。
  • token：這是遭撤銷的權杖 ID。

如要進一步瞭解欄位類型和格式，請參閱「JSON Web Token (JWT)」一文。

應用程式快速連結「向後收折式」介面

如果是應用程式翻轉，行動應用程式必須將授權碼或存取權杖傳回 Google 應用程式。

Android (意圖結果)

應用程式是透過 Intent 開啟。同意後，系統會完成程序，並將結果回報給 Google。詳情請參閱 Android 導入指南。

  • 動作： com.google.android.gms.auth.CODE_AVAILABLE
  • 其他： code、state、access_token、token_type。

應用程式會使用自訂網址通訊協定或 HTTPS 通用連結開啟 Google。詳情請參閱 iOS 導入指南。

  • 格式： <return_url>?code=AUTHORIZATION_CODE&state=STATE_STRING