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

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

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

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

须知事项

  1. 配置员工身份联合;有关特定于 IdP 的说明,请参阅以下指南:

  2. 您必须知道员工池 ID 或提供方 ID。

  3. 确保您拥有 Identity and Access Management (IAM) 权限 serviceusage.services.use。包含此权限的最小特权角色是 Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)。

  4. Enable the IAM and Security Token Service APIs.

    Enable the APIs

  5. Install the Google Cloud CLI, then initialize it by running the following command:

    gcloud init

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

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

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

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

本部分介绍如何配置 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_typeid_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"
    }
  }
}

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

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

如需使用此模式,必须提供以下标志:

  • --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."
}

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

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

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

如需生成交互式可执行文件溯源凭据,请添加参数 --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

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

文件溯源凭据

断言会从文件加载。其他进程必须在旧断言到期前使用 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_typesaml_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、gsutil)目前不支持可执行文件溯源凭据类型。

对于无头流,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)
}

gsutil

如需使用员工身份联合进行身份验证,请使用以下方法之一:

将 gsutil 与 gcloud 搭配使用时,请照常登录:

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

将 gsutil 用作独立的命令行应用时,请修改 .boto 文件以包含以下部分:

[Credentials]
gs_external_account_file = FILEPATH

在这两种情况下,FILEPATH 都是凭据配置文件的文件路径。

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

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

后续步骤