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

    如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (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 颁发的用于调用 Google Cloud API 的 OAuth 2.0 访问令牌。
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 密钥 (JWK) 验证 Cloud OAuth API 返回的 id_token 的加密签名。

通过以下任一方式检索组织的公开 JWK：

  • 直接查询 JSON Web 密钥集 (JWKS) 端点：向 https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/.well-known/jwks.json 发送 HTTP GET 请求。
  • 使用 OIDC 发现文档：向 OIDC 发现端点 (https://auth.cloud.google/oidc/organizations/ORGANIZATION_ID/.well-known/openid-configuration) 发送 HTTP GET 请求，以从 jwks_uri 字段中检索 JWKS 端点网址。

在两个端点网址中，将 ORGANIZATION_ID 替换为您的数字 Google Cloud 组织 ID。

后续步骤