使用 Cloud OAuth API 交換權杖

您可以使用 Cloud OAuth API (cloudoauth.googleapis.com)，將授權碼或更新權杖，換成效期短的 Google CloudOAuth 2.0 存取權杖和 OpenID Connect (OIDC) ID 權杖。在員工身分聯盟整合中，應用程式可以使用組織的公開金鑰驗證傳回的 ID 權杖，並使用存取權杖代表聯合使用者呼叫Google Cloud API。

事前準備

  1. 設定員工身分集區和提供者。詳情請參閱「設定員工身分聯盟」。
  2. 註冊 OAuth 用戶端並建立用戶端憑證。詳情請參閱「管理 OAuth 應用程式」。

  3. 啟用 Cloud OAuth API (如果尚未啟用)。

    啟用 API 所需的角色

    您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「Service Usage 管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    啟用 API

驗證方式

如要使用 Cloud OAuth API 驗證 OAuth 用戶端，請透過下列任一方式傳遞用戶端 ID 和用戶端密鑰：

  • HTTP 基本驗證 (建議)：在 Authorization 標頭中傳遞 base64 編碼的用戶端 ID 和用戶端密鑰：

    -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)"

  • 要求主體參數：在要求主體中傳遞 client_id 和 client_secret 參數。

使用授權碼交換權杖

聯合身分使用者在Google Cloud的統一授權端點 (https://auth.cloud.google/authorize) 透過識別資訊提供者 (IdP) 登入後，授權端點會將使用者重新導向至應用程式的重新導向 URI，並提供授權碼。如要將這個授權碼換成存取權杖、更新權杖和 OIDC ID 權杖，請向組織範圍 (單一租戶) 端點傳送 HTTP POST 要求：

  • HTTP 基本驗證 (建議)：

    curl -X POST https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/token \
-H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code=AUTHORIZATION_CODE" \
--data-urlencode "redirect_uri=REDIRECT_URI"

  • 要求主體參數：

    curl -X POST https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/token \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code=AUTHORIZATION_CODE" \
--data-urlencode "redirect_uri=REDIRECT_URI" \
--data-urlencode "client_id=CLIENT_ID" \
--data-urlencode "client_secret=CLIENT_SECRET"

更改下列內容：

  • ORGANIZATION_ID：您的 Google Cloud組織 ID。
  • BASE64_ENCODED_CREDENTIALS：CLIENT_ID:CLIENT_SECRET 的 Base64 編碼字串。
  • AUTHORIZATION_CODE： Google Cloud的統一授權端點 (https://auth.cloud.google/authorize) 傳回的授權碼。
  • REDIRECT_URI：OAuth 用戶端上設定的重新導向 URI。
  • CLIENT_ID：您註冊的 OAuth 用戶端 ID。
  • CLIENT_SECRET：OAuth 用戶端密鑰。

更新存取權杖

存取權杖到期時，請使用 refresh_token 授權類型，從組織範圍 (單一租戶) 端點取得新的短期存取權杖：

curl -X POST https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/token \
  -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=REFRESH_TOKEN" \
  --data-urlencode "redirect_uri=REDIRECT_URI"

更改下列內容：

  • ORGANIZATION_ID：您的 Google Cloud組織 ID。
  • BASE64_ENCODED_CREDENTIALS：CLIENT_ID:CLIENT_SECRET 的 Base64 編碼字串。
  • REFRESH_TOKEN：權杖端點先前傳回的更新權杖。
  • REDIRECT_URI：OAuth 用戶端上設定的重新導向 URI。

權杖回應欄位

權杖交換成功時，Cloud OAuth API 會傳回 HTTP 200 OK 狀態，其中包含下列欄位：

欄位 類型 說明
access_token string Cloud OAuth API 核發的 OAuth 2.0 存取權杖，用於呼叫 Google Cloud API。
refresh_token string 當目前的權杖到期時，用於取得新存取權杖的更新權杖。
expires_in integer 存取權杖的剩餘生命週期 (以秒為單位，通常為 3599)。
token_type string 權杖類型 (例如 Bearer)。
scope string 與權杖相關聯的範圍清單。
id_token string 包含已驗證身分聲明的 OIDC ID 權杖。

如要瞭解 Cloud OAuth API 傳回的錯誤回應，請參閱「Cloud OAuth API 權杖交換錯誤」。

驗證 OIDC ID 權杖

如果是 Looker OIDC 整合，您可以使用組織的公開 JSON Web Key (JWK)，驗證 Cloud OAuth API 傳回的 id_token 密碼編譯簽章。

透過下列任一方式擷取組織的公開 JWK：

  • 直接查詢 JSON Web Key Set (JWKS) 端點：傳送 HTTP GET 要求至 https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/.well-known/jwks.json。
  • 使用 OIDC 導覽文件：傳送 HTTP GET 要求至 OIDC 導覽端點 (https://auth.cloud.google/oidc/organizations/ORGANIZATION_ID/.well-known/openid-configuration)，從 jwks_uri 欄位擷取 JWKS 端點網址。

在兩個端點網址中，將 ORGANIZATION_ID 替換為數字 Google Cloud 組織 ID。

後續步驟