本指南介绍如何使用员工身份池和员工身份池提供方从 Security Token Service 获取短期有效的令牌。您可以使用令牌访问支持员工身份联合并且您有权访问的 Google Cloud 资源。
您可以按照以下流程获取短期令牌:
- 从受信任的身份提供商获取凭据。
- 用凭据从 Security Token Service 交换令牌。
须知事项
配置员工身份联合;有关特定于 IdP 的说明,请参阅以下指南:
您必须知道员工池 ID 或提供方 ID。
确保您拥有 Identity and Access Management (IAM) 权限
serviceusage.services.use
。包含此权限的最小特权角色是 Service Usage Consumer (roles/serviceusage.serviceUsageConsumer
)。Enable the IAM and Security Token Service APIs.
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
:员工池 IDPROVIDER_ID
:提供方 IDLOGIN_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
:员工池 IDPROVIDER_ID
:提供方 IDPATH_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
您可以从以下来源获取用于设置配置文件的凭据:
文件溯源凭据
断言会从文件加载。其他进程必须在旧断言到期前使用 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、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
:提供方 IDSUBJECT_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 产品支持员工身份联合
- 设置用户对控制台(联合)的访问权限