使用 Cloud OAuth API 交换令牌

本指南介绍了如何在员工身份联合集成中使用 Cloud OAuth API (cloudoauth.googleapis.com) 将外部凭据、授权代码或刷新令牌交换为 Google Cloud 访问令牌。

准备工作

  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 支持两种客户端身份验证方法：

  • 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 签发的用于调用 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 令牌交换错误。

后续步骤