使用 Cloud OAuth API 交換權杖

本指南說明如何在員工身分聯盟整合中，使用 Cloud OAuth API (cloudoauth.googleapis.com) 換取外部憑證、授權碼或重新整理權杖，取得存取權杖。 Google Cloud

事前準備

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

  3. 啟用 Cloud OAuth API。

    啟用 API 時所需的角色

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

    啟用 API

驗證方法

Cloud OAuth API 支援兩種用戶端驗證方法：

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

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

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

交換授權碼以取得權杖

如要以 Google Cloud 授權碼換取存取權杖和重新整理權杖，請傳送 HTTP POST 要求：

  • 機構範圍 (單一租戶) 端點

    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"

更改下列內容：

  • BASE64_ENCODED_CREDENTIALS：CLIENT_ID:CLIENT_SECRET 的 Base64 編碼字串。
  • AUTHORIZATION_CODE：由Google Cloud核發的授權碼。
  • REDIRECT_URI：在 OAuth 用戶端上設定的重新導向 URI。
  • ORGANIZATION_ID：您的數字 Google Cloud 組織 ID。
  • 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"

將 REFRESH_TOKEN 替換為權杖端點先前傳回的更新權杖。

權杖回應欄位

權杖交換成功後，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 權杖交換錯誤」。

後續步驟