使用 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 時所需的角色

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

    啟用 API

特定組織適用的端點

如果用戶端應用程式和資源僅限於特定Google Cloud 機構，您可以使用 Cloud OAuth API 提供的機構範圍 (單一租戶) 端點：

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 的情況) JSON 物件，可定義每個分散式聲明 ID 的來源端點。

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

後續步驟