使用 Cloud OAuth API 擷取使用者資訊

本指南說明如何使用 Cloud OAuth API (cloudoauth.googleapis.com) 中的 /userinfo 端點，擷取已驗證員工使用者的 OpenID Connect (OIDC) 標準宣告、自訂目錄宣告和群組成員資格。

事前準備

  1. 設定員工身分集區和提供者。詳情請參閱「設定員工身分聯盟」。
  2. 註冊 OAuth 用戶端，並將授權碼換成存取權杖。詳情請參閱「使用 Cloud OAuth API 交換權杖」。
  3. 確認存取權杖包含 openid 範圍。

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

    啟用 API 所需的角色

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

    啟用 API

組織範圍端點

Cloud OAuth API 提供組織範圍 (單一租戶) 端點，當用戶端應用程式和資源僅限特定Google Cloud 組織使用時，您可以使用這個端點：

Cloud OAuth API 的 organizations.userinfo 方法會擷取特定組織中已驗證使用者的 OpenID Connect (OIDC) 標準宣告、自訂宣告和群組成員資格。

使用任何要求資料之前，請先修改下列項目的值：

  • TOKEN：從權杖交換端點取得的短期 OAuth 2.0 存取權杖。
  • ORGANIZATION_ID：您的數字 Google Cloud 組織 ID。

HTTP 方法和網址：

GET https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/userinfo

請展開以下其中一個選項，以傳送要求：

如果員工身分集區未啟用 SCIM 佈建功能，端點會傳回內嵌的設定檔屬性、自訂憑證附加資訊和群組成員資格：

{
  "sub": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
  "email": "user@example.com",
  "custom_claim1": "engineering",
  "custom_claim2": "us-west",
  "groups": [
    "looker-developers",
    "analytics-viewers"
  ]
}

使用者權杖附加資訊和 SCIM 分散式群組

要求成功時，/userinfo 端點會傳回 HTTP 200 OK 狀態，以及包含已驗證使用者憑證資訊的 JSON 物件。

要求格式取決於工作團隊身分集區提供者是否使用 SCIM 佈建：

內嵌宣告 (非 SCIM 身分集區)

如果員工身分集區未啟用 SCIM 佈建功能，端點會傳回設定檔屬性、自訂宣告和群組成員資格：

{
  "sub": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
  "email": "user@example.com",
  "custom_claim1": "engineering",
  "custom_claim2": "us-west",
  "groups": [
    "looker-developers",
    "analytics-viewers"
  ]
}

分散式權杖附加資訊 (已啟用 SCIM 的身分集區)

如果員工身分集區已啟用 SCIM 佈建功能，群組成員資格會以分散式憑證的形式傳回。回應包含參照 /groups 端點的 _claim_names 和 _claim_sources：

{
  "sub": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
  "name": "Jane Doe",
  "email": "user@example.com",
  "_claim_names": {
    "groups": "src1"
  },
  "_claim_sources": {
    "src1": {
      "endpoint": "https://cloudoauth.googleapis.com/v1/common/groups"
    }
  }
}

宣告欄位

回應包含下列標準和分散式聲明欄位：

欄位 類型 說明
sub string 員工身分集區中，已驗證使用者的專屬主體 ID。
name string 使用者的全名 (如果識別資訊提供者有提供)。
email string 已驗證使用者的電子郵件地址。
groups array of strings (僅限非 SCIM) 使用者的企業群組成員清單。
_claim_names object (僅限啟用 SCIM) JSON 物件，可將分散式聲明名稱 (例如 groups) 對應至 _claim_sources 中的來源 ID。
_claim_sources object (僅限啟用 SCIM) 定義每個分散式聲明 ID 來源端點的 JSON 物件。

如要瞭解 /userinfo 端點傳回的錯誤回應，請參閱「Cloud OAuth 使用者資訊和群組錯誤」。

後續步驟