为员工身份联合获取短期令牌

本指南介绍如何使用员工身份池和员工身份池提供方从 Security Token Service 获取短期有效的令牌。您可以使用令牌访问支持员工身份联合并且您有权访问的 Google Cloud 资源。

您可以按照以下流程获取短期令牌：

从受信任的身份提供商获取凭据。
用凭据从 Security Token Service 交换令牌。

准备工作

配置员工身份联合；有关特定于 IdP 的说明，请参阅以下指南：
- 配置基于 Microsoft Entra ID 的员工身份联合
- 配置基于 Okta 的员工身份联合
您必须知道员工池 ID 或提供方 ID。
确保您拥有 Identity and Access Management (IAM) 权限 serviceusage.services.use。包含此权限的最小特权角色是 Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)。
Enable the IAM and Security Token Service APIs.
Enable the APIs
Install the Google Cloud CLI, then initialize it by running the following command:
```
gcloud init
```
Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

将外部凭据交换为 Google Cloud 访问令牌

本部分介绍如何使用 Security Token Service 将外部凭据交换为可授予 Google Cloud 访问权限的访问令牌。您可以使用 gcloud CLI、REST API 和 Cloud 客户端库执行此操作，如本指南后面部分所述。

如果您需要长期访问权限，则可以配置长时间运行的进程以在该机器上持续刷新凭据。或者，您可以使用返回凭据的端点在后台运行本地服务器。

本部分介绍如何配置 gcloud CLI 以使用基于浏览器的登录流程。为此，创建一个登录配置文件，然后在对 gcloud auth login 的调用中引用该文件，或者激活该文件以便默认使用它。

如需创建登录配置文件，请运行以下命令。您可以选择使用 --activate 标志激活文件，以作为 gcloud CLI 的默认设置。

gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE

替换以下内容：

WORKFORCE_POOL_ID：员工池 ID
PROVIDER_ID：提供方 ID
LOGIN_CONFIG_FILE：您指定的配置文件的路径，例如 login.json

该文件包含 gcloud CLI 用于启用基于浏览器的身份验证流程的端点，并将受众群体设置为您在本指南前面部分中创建的提供方。该文件不含机密信息。

输出类似于以下内容：

{
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "auth_url": "https://auth.cloud.google/authorize",
  "token_url": "https://sts.googleapis.com/v1/oauthtoken",
  "token_info_url": "https://sts.googleapis.com/v1/introspect",
}

如需使用基于浏览器的登录身份验证来验证身份，您可以使用以下方法之一：

如果您在创建配置文件时使用了 --activate 标志，或者使用 gcloud config set auth/LOGIN_CONFIG_FILE 激活了配置文件，gcloud CLI 会自动使用配置文件：
```
gcloud auth login
```
如需通过指定配置文件的位置进行登录，请运行以下命令：
```
gcloud auth login --login-config=LOGIN_CONFIG_FILE
```
如需使用环境变量来指定配置文件的位置，请将 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 设置为配置文件的路径。

如需停止使用登录配置文件，请执行以下操作：

如果您在创建配置文件时使用了 --activate 标志，或者使用 gcloud config set auth/LOGIN_CONFIG_FILE 激活了配置文件，则必须运行以下命令以取消设置：
```
gcloud config unset auth/login_config_file
```
清除 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 环境变量（如果已设置）。

使用配置文件登录

作为基于浏览器的登录的替代方案，本部分介绍了使用凭据配置文件提供对经过身份验证的 Google Cloud 操作的访问权限的不同方法。设置配置文件不需要登录 gcloud CLI。

设置配置文件的方式取决于您的 IdP 使用的是 OIDC 还是 SAML。

OIDC

您可以从以下来源获取用于设置配置文件的凭据：

文件溯源凭据
网址溯源凭据
非交互式可执行文件溯源凭据
交互式可执行文件溯源凭据

文件溯源凭据

令牌从文件加载。其他进程在旧令牌到期前，必须使用新 OIDC 令牌刷新此文件。例如，如果令牌的有效期为 1 小时，您必须在 1 小时之前刷新该文件。

如需使用文件来源凭据生成配置文件，请执行以下命令：

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-file=PATH_TO_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

替换以下内容：

WORKFORCE_POOL_ID：员工池 ID
PROVIDER_ID：提供方 ID
PATH_TO_OIDC_TOKEN：OIDC IdP 凭据文件的路径
WORKFORCE_POOL_USER_PROJECT：与员工池用户项目关联的项目编号或 ID。

主账号必须具有此项目的 serviceusage.services.use 权限。

运行该命令会生成类似于以下内容的 OIDC IdP 配置文件：

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS_FILE"
  }
}

网址溯源凭据

令牌使用响应 HTTP GET 请求的端点从本地服务器加载。响应必须是 OIDC ID 令牌（采用纯文本或 JSON 格式）。

如需使用网址来源凭据生成配置文件，请执行以下命令：

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-url=URL_TO_RETURN_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

请替换以下内容：

WORKFORCE_POOL_ID：员工池 ID。
PROVIDER_ID：提供方 ID。
URL_TO_RETURN_OIDC_ID_TOKEN：要调用以检索 OIDC 凭据的网址（如 OIDC ID 令牌），例如：http://localhost:5000/token。
WORKFORCE_POOL_USER_PROJECT：用于配额限制和结算的项目的编号。主账号需要拥有此项目的 serviceusage.services.use permission。

运行该命令会生成类似于以下内容的 OIDC IdP 配置文件：

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "url": "URL_TO_RETURN_OIDC_ID_TOKEN"
  }
}

非交互式可执行文件溯源凭据

令牌从本地可执行文件加载。可执行文件必须向 stdout 提供一个有效的 JSON 格式的未过期 OIDC ID 令牌：

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

如需获得成功的响应，必须提供这些字段，但 expiration_time 除外。仅当在凭据配置中指定了输出文件时，才需要 expiration_time 字段。

可执行文件必须按以下 JSON 格式向 stdout 显示发生的任何错误：

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

这些字段都是错误响应的必填字段。发生相应的错误时，客户端库会用到这些代码和消息字段。

该命令可以返回以下字段：

version：JSON 输出的版本；仅支持版本 1。
success：响应的状态。当状态为 true 时，可执行文件必须以退出代码 0 退出，并且响应必须包含以下字段：
- token_type：id_token
- 如果在凭据配置中指定了输出文件，则还应包含 expiration_time 字段。
当状态为 false 时，可执行文件必须以非零值退出，并且响应必须包含以下字段：
- code
- message
token_type：第三方主题令牌类型，必须为 urn:ietf:params:oauth:token-type:id_token
id_token：第三方 OIDC 令牌
expiration_time：第三方 OIDC 令牌的到期时间（与 Unix 计时原点之间相隔的秒数）
code：错误代码字符串
message：错误消息

运行可执行文件时，客户端库会填充以下环境变量：

GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE：凭据配置中的目标对象字段。始终存在。
GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE：预期的主题令牌类型。始终存在。
GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE：凭据配置中的输出文件位置。仅当在凭据配置中指定了该位置时存在。

可执行文件可以使用这些环境变量来避免对这些值进行硬编码。

如需使用客户端库启用此凭据溯源方法，必须将 GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 环境变量设置为 1。

如需使用可执行文件溯源凭据生成配置文件，请执行以下命令：

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

请替换以下内容：

WORKFORCE_POOL_ID：员工池 ID。
PROVIDER_ID：提供方 ID。
EXECUTABLE_COMMAND：要运行来检索主题令牌的完整命令（包括参数），如 OIDC ID 令牌，格式如下：--executable-command="/path/to/command --foo=bar"。
EXECUTABLE_TIMEOUT：（可选）等待可执行文件运行的时长（以毫秒为单位），默认为 30 秒。
EXECUTABLE_OUTPUT_FILE：（可选）由可执行文件生成的第三方凭据的文件路径。这对于缓存凭据很有用。身份验证库会首先检查该路径，然后再运行可执行文件。
WORKFORCE_POOL_USER_PROJECT：用于配额和结算的项目编号或 ID。主账号必须在此项目上设置 serviceusage.services.use 权限。

运行该命令会生成类似于以下内容的 OIDC IdP 配置文件：

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

交互式可执行文件溯源凭据

您可以通过 stdin 和 stdout 提供与用户交互的可执行文件。如果用户成功登录，可执行文件会将有效、未过期的凭据写入指定的文件。

如需使用此模式，必须提供以下标志：

--executable-output-file：可执行文件会将凭据信息写入其中的文件
--exeutable-interactive-timeout-millis：一个非零值，表示交互模式并设置超时，例如，6000 表示 60 秒超时

如需获得成功的响应，必须为以下字段提供相应的值，但 expiration_time 除外：

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

可执行文件必须按以下 JSON 格式将任何错误写入在 --executable-output-file 中指定的文件。返回错误响应时，以下字段均为必需字段。

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

code 和 message 字段必须指明适当的错误。发生错误时，客户端库会用到这些字段。

成功执行后，该命令会返回相同的字段，无论使用的是上述交互式还是非交互式可执行文件来源凭据结果。

环境变量也与常规的可执行文件溯源凭据相同。

如需生成交互式可执行文件溯源凭据，请添加参数 --executable-interactive-timeout-millis 和参数 --executable-output-file。

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

请替换以下内容：

WORKFORCE_POOL_ID：员工池 ID。
PROVIDER_ID：提供方 ID。
EXECUTABLE_COMMAND：要运行来检索主题令牌的完整命令（包括参数），格式如下：--executable-command="/path/to/command --arg1=val1 --arg2=val2"
EXECUTABLE_INTERACTIVE_TIMEOUT：等待可执行文件运行的时长（以毫秒为单位）。
EXECUTABLE_OUTPUT_FILE：由可执行文件生成的第三方凭据的文件路径。此路径对于缓存凭据很有用。身份验证库会首先检查该路径，然后再运行可执行文件。
WORKFORCE_POOL_USER_PROJECT：用于配额和结算的项目编号或 ID。主账号必须在此项目上具有 serviceusage.services.use 权限。

运行该命令会生成类似于以下内容的 OIDC IdP 配置文件：

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "interactive_timeout_millis": "EXECUTABLE_INTERACTIVE_TIMEOUT",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE",
    }
  }
}

SAML

您可以从以下来源获取用于设置配置文件的凭据：

文件溯源凭据
网址溯源凭据
可执行文件溯源凭据
gcloud 交互模式的可执行文件溯源凭据

文件溯源凭据

断言会从文件加载。其他进程必须在旧断言到期前使用 base64 编码的新 SAML 断言刷新此文件。例如，如果断言的有效期为 1 小时，您必须在 1 小时之前刷新该文件。

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=federation_config.json \
    --credential-source-file=CREDENTIAL_FILE \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT

替换以下内容：

WORKFORCE_POOL_ID：员工池 ID。
PROVIDER_ID：提供方 ID。
CREDENTIAL_FILE：IdP 生成的凭据文件的路径。
WORKFORCE_POOL_USER_PROJECT：用于配额和结算的项目编号或 ID。主账号必须具有此项目的 serviceusage.services.use permission 权限。

网址溯源凭据

系统会从本地服务器加载断言，该端点使用响应 HTTP GET 请求的端点。响应必须是 base64 编码的 SAML 断言或包含 base64 编码的 SAML 断言的 JSON。

如需使用网址溯源凭据，请使用 --credential-source-url 标志：

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=federation_config.json \
    --credential-source-url=CREDENTIAL_URL \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT

替换以下内容：

WORKFORCE_POOL_ID：员工池 ID。
PROVIDER_ID：提供方 ID。
CREDENTIAL_URL：本地服务器端点的网址。
WORKFORCE_POOL_USER_PROJECT：用于配额和结算的项目编号或 ID。主账号需要拥有此项目的 serviceusage.services.use permission。

可执行文件溯源凭据

断言会从本地可执行文件加载。可执行文件必须以 JSON 格式将未过期的 SAML 断言提供给 stdout。

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}

如需获得成功的响应，必须提供这些字段，但 expiration_time 除外。仅当在凭据配置中指定了输出文件时，才需要包含 expiration_time 字段。

如果发生错误，可执行文件必须按以下 JSON 格式提供给 stdout：

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

这些字段都是错误响应的必填字段。发生相应的错误时，客户端库会用到这些代码和消息字段。

该命令可以返回以下字段：

version：JSON 输出的版本；仅支持版本 1。
success：响应的状态。当状态为 true 时，可执行文件必须以退出代码 0 退出，并且响应必须包含以下字段：
- token_type：saml_response
- 如果在凭据配置中指定了输出文件，则还应包含 expiration_time 字段。
当状态为 false 时，可执行文件必须以非零值退出，并且响应必须包含以下字段： + code + message
token_type：第三方主题令牌类型，必须为 urn:ietf:params:oauth:token-type:saml2
saml_response：第三方 SAML 响应
expiration_time：第三方 SAML 响应的到期时间（与 Unix 计时原点之间相隔的秒数）
code：错误代码字符串
message：错误消息

运行可执行文件时，客户端库会填充以下环境变量：

GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE：凭据配置中的目标对象字段。始终存在。
GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE：预期的主题令牌类型。始终存在。
GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE：凭据配置中的输出文件位置。仅当在凭据配置中指定了该位置时存在。

如需使用客户端库启用此来源的凭据方法，您需要将 GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 环境变量设置为 1。

如需使用可执行文件溯源凭据生成配置文件，请执行以下命令：

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

请替换以下内容：

WORKFORCE_POOL_ID：员工池 ID。
PROVIDER_ID：提供方 ID。
EXECUTABLE_COMMAND：要运行来检索主题令牌的完整命令（包括参数），格式如下：--executable-command="/path/to/command --foo=bar"。
EXECUTABLE_TIMEOUT：（可选）等待可执行文件运行的时长（以毫秒为单位），默认为 30 秒。
EXECUTABLE_OUTPUT_FILE：（可选）可执行文件生成的 3PI 凭据的文件路径。这对于缓存凭据很有用。运行可执行文件之前，身份验证库会先检查其是否存在。
WORKFORCE_POOL_USER_PROJECT：用于配额限制和结算的项目的编号。主账号必须在此项目上具有 serviceusage.services.use 权限。

运行该命令会生成类似于以下内容的 SAML IdP 配置文件：

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

gcloud 交互模式的可执行文件溯源凭据

可执行文件通过命令行与用户交互。

在上一个命令中，替换以下内容：

EXECUTABLE_OUTPUT_FILE：（必需）文件的路径，该文件提供可执行文件生成的凭据。
EXECUTABLE_TIMEOUT：（必需）一个非零超时值，它也指示命令使用交互模式。

    {
      "version": 1,
      "success": true,
      "token_type": "urn:ietf:params:oauth:token-type:saml2",
      "saml_response": "...",
      "expiration_time": 1620499962
    }

如需获得成功的响应，必须提供这些字段，但 expiration_time 除外。如果缺少 expiration_time，则视为指示我们将以任何方式运行可执行文件。

可执行文件必须按以下 JSON 格式向 executable-output-file 显示发生的任何错误：

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

这些字段都是错误响应的必填字段。发生相应的错误时，客户端库会用到这些代码和消息字段。

成功执行的命令返回字段，与上面的常规可执行文件溯源凭据结果完全相同。

环境变量也与常规的可执行文件溯源凭据相同。

如需生成交互式可执行文件溯源凭据，请添加参数 --executable-interactive-timeout-millis。

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

替换以下内容：

WORKFORCE_POOL_ID：员工池 ID。
PROVIDER_ID：提供方 ID。
EXECUTABLE_COMMAND：要运行来检索主题令牌的完整命令（包括参数），格式如下：--executable-command="/path/to/command --foo=bar")。
EXECUTABLE_INTERACTIVE_TIMEOUT：等待可执行文件运行的时长（以毫秒为单位）。
EXECUTABLE_OUTPUT_FILE：由可执行文件生成的第三方凭据的文件路径。这对于缓存凭据很有用。身份验证库会首先检查该路径，然后再运行可执行文件。
WORKFORCE_POOL_USER_PROJECT：用于配额和结算的项目编号或 ID。主账号在此项目上设置 serviceusage.services.use 权限。

运行该命令会生成类似于以下内容的 SAML IdP 配置文件：

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/<var>WORKFORCE_POOL_ID<var>/providers/<var>PROVIDER_ID</var>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "<var>WORKFORCE_POOL_USER_PROJECT</var>",
  "credential_source": {
    "executable": {
      "command": "<var>EXECUTABLE_COMMAND</var>",
      "interactive_timeout_millis": "<var>EXECUTABLE_INTERACTIVE_TIMEOUT</var>",
      "timeout_millis": "<var>EXECUTABLE_TIMEOUT</var>",
      "output_file": "<var>EXECUTABLE_OUTPUT_FILE</var>",
    }
  }
}

如需登录，请运行以下命令：

gcloud auth login --cred-file=/path/to/config.json

请注意，CLI（gcloud、bq）不支持可执行文件溯源凭据类型。

对于无头流，gcloud 会自动使用以下范围：https://www.googleapis.com/auth/cloud-platform。然后，gcloud 会以透明方式将凭据发布到 Security Token Service 端点，之后在该端点交换临时的 Google Cloud 访问令牌。

您现在可以使用 gcloud CLI 执行 gcloud 命令。

使用 Google Cloud 客户端库

如果您使用受支持的客户端库，则可以配置客户端库使其自动生成 Google 凭据。我们建议您尽可能自动生成凭据，这样您就无需自行处理令牌交换过程。

支持员工池的 Google Cloud 客户端库支持以下语言：Node.js、Java、Python、Go 和 C++ (gRPC)。

如需将客户端库与这些服务或语言搭配使用，请执行以下操作：

bq

如需使用员工身份联合进行身份验证，请使用 gcloud auth login 命令：

gcloud auth login --cred-file=FILEPATH.json

其中，FILEPATH 是凭据配置文件的路径。

390.0.0 版及更高版本的 Google Cloud CLI 支持 bq 中的员工身份联合。

C++

大多数 C++ 版 Google Cloud 客户端库通过使用 ChannelCredentials 对象支持员工身份联合，该对象是通过调用 grpc::GoogleDefaultCredentials() 创建的。如要初始化此凭据，必须使用 1.42.0 版或更高版本的 gRPC 构建客户端库。

C++ 版 Cloud Storage 客户端库使用的是 REST API，而不是 gRPC，因此不支持员工身份联合。

auto creds = grpc::GoogleDefaultCredentials();

// Create a channel, stub and make RPC calls (same as in the previous example)
auto channel = grpc::CreateChannel("greeter.googleapis.com", creds);
std::unique_ptr<Greeter::Stub> stub(Greeter::NewStub(channel));
grpc::Status s = stub->sayHello(&context, *request, response);

gcloud

如需使用员工身份联合进行身份验证，请使用 gcloud auth login 命令：

gcloud auth login --cred-file=FILEPATH.json

其中，FILEPATH 是凭据配置文件的路径。

392.0.0 版及更高版本的 Google Cloud CLI 支持 gcloud 中的员工身份联合。

Go

如果 Go 客户端库使用 v0.0.0-20211005180243-6b3c2da341f1 版或更高版本的 golang.org/x/oauth2 模块，则支持员工身份联合。

import (
  "context"
  "fmt"
  "log"

  "cloud.google.com/go/storage"
  "google.golang.org/api/iterator"
  "google.golang.org/api/option"
  "io/ioutil"
)
ctx := context.Background()
client, err := storage.NewClient(ctx)
# Explicit initialization can also be used.
# var jsonPath = "/path/to/3p-credentials.json"
# client, err := storage.NewClient(ctx, option.WithCredentialsFile(jsonPath))
if err != nil {
  log.Fatal(err)
}
fmt.Println("Buckets:")
it := client.Buckets(ctx, projectID)
for {
  battrs, err := it.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(battrs.Name)
}

Java

如果 Java 客户端库使用 1.2.0 版或更高版本的 com.google.auth:google-auth-library-oauth2-http 工件，则支持员工身份联合。

import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
GoogleCredentials sourceCredentials = credentials
    .createScoped(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"));

Storage storageService = StorageOptions.newBuilder().setProjectId("project-id")
    .setCredentials(sourceCredentials).build().getService();

Node.js

Node.js 客户端库支持员工身份联合。您必须使用 7.10.0 版或更高版本的 google-auth-library 软件包。与工作负载身份池不同，员工池与组织相关联，而不是与 Google Cloud 项目相关联。创建 GoogleAuth 对象时，您必须指定项目 ID。如需了解详情，请参阅 google-auth-library 软件包的自述文件。

const auth = new GoogleAuth({
  scopes: 'https://www.googleapis.com/auth/cloud-platform',
  // Specify a project ID.
  projectId: 'CLOUD_RESOURCE_PROJECT_ID',
});

# API request using Auth library.
const client = await auth.getClient();
const url =
    `https://storage.googleapis.com/storage/v1/b?projects=${projectId}`;
const res = await client.request({url});
console.log(res.data);

Python

如果 Python 客户端库使用 2.3.0 版或更高版本的 google-auth 软件包，则支持员工身份联合。

from google.cloud import storage
import google.auth

credentials, project = google.auth.default(
    scopes=['https://www.googleapis.com/auth/devstorage.read_only'])

client = storage.Client(
    project="project-id", credentials=credentials)

在上面的示例中，如果库无法自动发现 project 值，那么该值可以为 None。您可以在使用服务实例时明确传递该值（如存储客户端示例所示），也可以通过环境变量 GOOGLE_CLOUD_PROJECT 设置该值。

如需了解详情，请参阅 google-auth 软件包用户指南。

使用 REST API

您可以调用 Google Cloud Security Token Service API 来将外部凭据交换为 Google Cloud 访问令牌。

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    --data-urlencode "scope=https://www.googleapis.com/auth/cloud-platform" \
    --data-urlencode "subject_token_type=SUBJECT_TOKEN_TYPE" \
    --data-urlencode "subject_token=EXTERNAL_SUBJECT_TOKEN"  \
    --data-urlencode "options={\"userProject\":\"BILLING_PROJECT_NUMBER\"}"

替换以下内容：

AUDIENCE：颁发主体令牌的提供方的完整资源名称。
PROVIDER_ID：提供方 ID
SUBJECT_TOKEN_TYPE：设置为以下某一项：
- urn:ietf:params:oauth:token-type:id_token（对于 OIDC ID 令牌）
- urn:ietf:params:oauth:token-type:saml2（对于 SAML 断言）
EXTERNAL_SUBJECT_TOKEN：IdP 签发的令牌，表示请求访问令牌的主账号的身份。注意：如果您使用 OIDC，则令牌为 JWT 格式。
BILLING_PROJECT_NUMBER：用于配额和结算的项目编号或 ID。主账号需要拥有此项目的 serviceusage.services.use 权限。

响应类似于以下示例：

{
  "access_token": "ya29.dr.AaT61Tc6Ntv1ktbGkaQ9U_MQfiQw...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

使用 gcloud CLI 管理会话

gcloud 从 Security Token Service 端点获取的临时 Google Cloud 令牌会在指定的时间间隔后过期。令牌即将过期时，gcloud 会检查您提供的凭据文件，并检查您从 IdP 收到的凭据的有效性。如果您的凭据仍然有效，则 gcloud 会继续以透明方式获取新的 Google Cloud 访问令牌，并且您的当前会话不会中断。

如果您的凭据已过期，则系统不会颁发新的 Google Cloud 令牌，并且使用这些凭据进行的任何调用都将失败。此时，您必须重新进行身份验证。

您可以通过执行以下命令来终止会话：

gcloud auth revoke

gcloud 支持多个用户会话。如需获取会话列表（包括当前活跃的会话），请执行以下命令：

gcloud auth list

此命令的输出类似如下所示：

Credentialed Accounts
ACTIVE    ACCOUNT
*         bola@example.com
          principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/kalani@example.com

如需切换到其他会话并将其设置为活跃状态，请执行以下命令：

gcloud config set account principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_ID

为员工身份联合获取短期令牌

准备工作

将外部凭据交换为 Google Cloud 访问令牌

使用 gcloud CLI 进行基于浏览器的登录

创建登录配置文件

使用基于浏览器的身份验证登录

停用基于浏览器的登录

使用配置文件登录

OIDC

文件溯源凭据

网址溯源凭据

非交互式可执行文件溯源凭据

交互式可执行文件溯源凭据

SAML

文件溯源凭据

网址溯源凭据

可执行文件溯源凭据

gcloud 交互模式的可执行文件溯源凭据

使用 Google Cloud 客户端库

bq

C++

gcloud

Go

Java

Node.js

Python

使用 REST API

使用 gcloud CLI 管理会话

后续步骤