Cloud OAuth API 總覽

Cloud OAuth API (cloudoauth.googleapis.com) 為員工身分聯盟提供 OAuth 2.0 和 OpenID Connect (OIDC) 權杖交換和驗證。

Cloud OAuth API 會驗證 Google Cloud 使用者。這個 API 可讓應用程式將使用者重新導向至授權端點 (https://auth.cloud.google/authorize)，以取得授權碼。接著，應用程式可以將外部憑證、授權碼或更新權杖，交換為短期 OAuth 2.0 存取權杖和 OIDC ID 權杖。

這個 API 是以 OAuth 2.0 權杖交換 (RFC 8693) 和 OAuth 2.0 授權架構 (RFC 6749) 規格為基礎。

與 Security Token Service 的比較

過去， Google Cloud的Security Token Service (sts.googleapis.com) 會處理員工身分聯盟和 Workload Identity Federation 的權杖交換作業。

Cloud OAuth API 支援與 Security Token Service 相同的權杖交換，但專用於員工身分聯盟流量。這種分離方式可將員工權杖交換與工作負載流量隔離，有助於防止跨服務中斷，並讓員工容量獨立於 Security Token Service 擴充。請根據整合狀態，按照下列指南操作：

  • 新整合：將使用者重新導向至授權端點 (https://auth.cloud.google/authorize)，並使用 Cloud OAuth API (cloudoauth.googleapis.com) 交換權杖。
  • 現有整合：如果您使用 Security Token Service (sts.googleapis.com/v1/oauthtoken 或 sts.googleapis.com/v1/token)，請轉換至 cloudoauth.googleapis.com。

支援的端點

下表列出 Cloud OAuth API 整合中使用的端點。這些端點大多屬於組織範圍 (單一租戶) 端點，可在用戶端應用程式和資源受限於單一 Google Cloud組織時，提供獨立的金鑰管理和探索功能。

在組織範圍的端點網址中，將 ORGANIZATION_ID 替換為您的 Google Cloud組織 ID 數字：

端點 方法 網址 說明
OpenID Connect 探索 GET https://auth.cloud.google/oidc/organizations/ORGANIZATION_ID/.well-known/openid-configuration 傳回組織的 OpenID Connect Discovery 1.0 供應商設定中繼資料 (導覽文件)。
授權 GET https://auth.cloud.google/authorize 將聯合身分使用者重新導向至識別資訊提供者 (IdP) 登入頁面，並將授權碼傳回應用程式的重新導向 URI。
權杖交換 POST https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/token 將授權碼或更新權杖，換成 OAuth 2.0 存取權杖和 OIDC ID 權杖。
JSON Web Key Set (JWKS) GET https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/.well-known/jwks.json 傳回公開 JSON Web Key (JWK)，用於驗證為組織核發的 OIDC ID 權杖簽章。
使用者資訊 GET https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/userinfo 擷取已驗證使用者的 OIDC 標準宣告、自訂目錄宣告和群組成員資格。
企業群組 GET https://cloudoauth.googleapis.com/v1/common/groups 擷取已驗證使用者的分頁企業群組成員資格。

授權端點

在 OAuth 2.0 和 OIDC 授權碼流程中，應用程式會將聯合使用者重新導向至 Google Cloud的統一授權端點 (https://auth.cloud.google/authorize)，以便使用 IdP 登入。驗證成功後，授權端點會將使用者重新導向至應用程式的重新導向 URI，並提供授權碼。接著，應用程式會在權杖交換端點將這組授權碼換成權杖。

OIDC 探索和 JWKS 端點

如果是 Looker OIDC 整合，Cloud OAuth API 會提供公開、未經驗證的組織範圍端點，用於用戶端設定和權杖驗證：

  • OpenID Connect 探索端點：提供組織的 OpenID Connect Discovery 1.0 provider 設定中繼資料 (導覽文件)。導覽文件包含組織的 issuer 識別碼和端點網址 (authorization_endpoint、token_endpoint、userinfo_endpoint 和 jwks_uri)，也會列出支援的範圍、憑證、簽署演算法 (RS256) 和 Proof Key for Code Exchange (PKCE) 程式碼驗證方法 (S256)。
  • JSON Web Key Set (JWKS) 端點：提供組織的公開 JSON Web Key Set (JWKS)。應用程式會使用 keys 陣列中的公開 JSON Web Key (JWK)，驗證 Cloud OAuth API 核發的 OIDC ID 權杖 (id_token) 加密編譯簽章。

在一般的 OIDC 整合中，應用程式會依下列順序使用這些端點：

  1. 擷取導覽文件：傳送 GET 要求至 OpenID Connect 探索端點 (/.well-known/openid-configuration)，並讀取端點網址 (authorization_endpoint、token_endpoint、jwks_uri 和 userinfo_endpoint)。
  2. 要求授權碼：將使用者重新導向至 authorization_endpoint (https://auth.cloud.google/authorize)，讓他們使用 IdP 登入，並在應用程式的重新導向 URI 接收授權碼。
  3. 將授權碼換成權杖：傳送 POST 要求至 token_endpoint (/token)，將授權碼換成 OAuth 2.0 存取權杖和 OIDC ID 權杖 (id_token)。
  4. 驗證 ID 權杖：從 jwks_uri (/.well-known/jwks.json) 擷取組織的公開金鑰，並使用這些金鑰驗證 id_token 的加密編譯簽章。
  5. 選用：擷取使用者資訊：將含有存取權杖的 GET 要求傳送至 userinfo_endpoint (/userinfo)，擷取其他使用者個人資料宣告和群組成員資格。

後續步驟