使用 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 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (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 员工身份池中经过身份验证的用户的唯一主账号标识符。
name string 用户的全名（如果身份提供方提供）。
email string 经过身份验证的用户的电子邮件地址。
groups array of strings （仅限非 SCIM）用户的企业群组成员资格列表。
_claim_names object （仅限启用 SCIM 的应用）一个 JSON 对象，用于将分布式声明名称（例如 groups）映射到 _claim_sources 中的源标识符。
_claim_sources object （仅限启用 SCIM）一个 JSON 对象，用于定义每个分布式声明标识符的来源端点。

如需了解 /userinfo 端点返回的错误响应，请参阅 Cloud OAuth 用户信息和群组错误。

后续步骤