向 gcloud CLI 授权

要访问 Google Cloud，您通常必须向 Google Cloud CLI 授权。本页面演示了可用的授权选项，并向您展示如何管理用于授权的账号。如果您使用的是 Compute Engine 实例或 Cloud Shell，则无需为 gcloud CLI 授权。

账号类型

如需向 gcloud CLI 授予访问Google Cloud的权限，您可以使用用户账号或服务账号。

用户账号是指 Google Cloud 账号，它允许最终用户向您的应用进行身份验证。在大多数常见用例中，特别是通过交互方式使用 gcloud CLI 时，最佳做法是使用用户账号。

服务账号是与您的Google Cloud 项目关联的 Google Cloud 账号，它并不代表某个特定用户。您可以在使用 Cloud Run 函数、App Engine、Compute Engine 或 Google Kubernetes Engine 时使用可用的内置服务账号。建议使用服务账号在多台机器上运行 gcloud CLI 脚本。

选择授权类型

您必须向 Google Cloud CLI 授权，才能管理 Google Cloud资源。Google Cloud CLI 和 Google Cloud 都使用 OAuth2 进行身份验证和授权。

选择以下其中一个授权类型：

类型 说明
用户账号 如果您要通过命令行使用 gcloud CLI，或者您要使用 gcloud CLI 编写脚本以便在单台机器上使用，则建议您选择此授权类型。
服务账号 如果您要在生产环境下的机器部署过程中安装和设置 gcloud CLI，或者用于 Compute Engine 虚拟机实例（其中所有用户都有 root 访问权限），建议您选择此授权类型。

如需详细了解身份验证和 Google Cloud，请参阅身份验证概览。

使用用户账号进行授权

本部分介绍了如何使用用户账号进行授权。

使用 Google 账号进行身份验证

如需使用用户账号授予访问权限，您可以使用以下 gcloud CLI 命令：

命令 说明
gcloud init 授予访问权限并执行其他常见的设置步骤。
gcloud auth login 仅授予访问权限。

在授权期间，这些命令会从Google Cloud 获取账号凭据并将其存储在本地系统上。指定的账号将成为您的配置中的活动账号。gcloud CLI 会使用存储的凭据访问Google Cloud。对于单个 gcloud CLI 安装，您可以拥有任意数量的具有存储凭据的账号，但任何时候都只能有一个账号处于活动状态。

运行 gcloud init

gcloud init 可授予访问权限并执行其他常见的设置步骤。gcloud init 使用基于 Web 的授权流程来对用户账号执行身份验证并授予访问权限。

如需授予访问权限并执行其他常见设置步骤，请执行以下操作：

  1. 运行 gcloud init：

    gcloud init

    或者，为了防止此命令自动打开网络浏览器，请运行以下命令：

    gcloud init --console-only

    如果您是使用 ssh 在远程系统上运行该命令，并且无权访问该系统上的浏览器，那么 --console-only 标志会非常有用。然后，您必须在本地系统的浏览器中手动打开提供的网址以完成授权过程。

  2. 按照基于浏览器的授权流程操作，以便对账号进行身份验证并授予访问权限。

如需详细了解 gcloud init，请参阅初始化 gcloud CLI。

运行 gcloud auth login

运行 gcloud auth login 仅对用户账号授权。如需授予访问权限而不执行其他设置步骤，请使用以下选项之一。

  • 如果您想在安装了浏览器的机器上为 gcloud CLI 授权，请按以下步骤操作。

    1. 向 gcloud CLI 授权：

      gcloud auth login

    2. 按照基于浏览器的授权流程操作，以便对账号进行身份验证并授予访问权限。

  • 如果您想在没有浏览器的机器上为 gcloud CLI 授权，并且可以在另一台安装了浏览器的机器上安装 gcloud CLI，请使用 --no-browser 标志。

    1. 向 gcloud CLI 授权：

      gcloud auth login --no-browser

    2. 复制以 gcloud auth login --remote-bootstrap=" 开头的长命令。

    3. 在另一台可信机器的命令行中粘贴并运行此命令。该机器必须已本地安装网络浏览器和 gcloud CLI 工具 372.0 或更高版本。

    4. 使用网络浏览器从机器复制长网址输出。

    5. 将长网址粘贴回第一台机器上的“Enter the output of the above command”（输入上述命令的输出）提示下，然后按 Enter 键完成授权。

  • 如果您想在没有浏览器的机器上为 gcloud CLI 授权，但无法在其他安装了浏览器的机器上安装 gcloud CLI，请使用 --no-launch-browser 标志。--no-launch-browser 标志可防止该命令自动打开网络浏览器。

    1. 向 gcloud CLI 授权：

      gcloud auth login --no-launch-browser

    2. 复制以 https://accounts.google.com/o/oauth2/auth... 开头的长网址

    3. 将此网址粘贴到另一台安装了网络浏览器的可信机器的浏览器中。

    4. 使用网络浏览器从机器复制授权代码。

    5. 在系统提示“输入验证码”时，将授权码粘贴回第一台机器，然后按 Enter 键完成授权。

  • 如果您已拥有访问令牌，请使用以下方法之一将访问令牌传递给 gcloud CLI：

    • 将访问令牌存储在文件中，并通过 --access-token-file 标志设置其路径。
    • 将访问令牌存储在文件中，并在 auth/access_token_file 属性中设置其路径。
    • 将 CLOUDSDK_AUTH_ACCESS_TOKEN 环境变量设置为访问令牌值。

使用员工身份联合进行身份验证

本部分介绍了如何使用员工身份联合登录 gcloud CLI。

基于浏览器的 gcloud CLI 登录

如需使用基于浏览器的登录流程登录 gcloud CLI，请执行以下操作：

  1. 创建登录配置文件。

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

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

    替换以下内容：

    • WORKFORCE_POOL_ID：员工身份池 ID
    • WORKFORCE_PROVIDER_ID：员工身份池提供方 ID
    • LOGIN_CONFIG_FILE：您指定的登录配置文件的路径，例如 login.json

    该文件包含 gcloud CLI 用于启用基于浏览器的身份验证流程的端点，并将受众群体设置为在员工身份池提供方中配置的 IdP。该文件不含机密信息。

    输出类似于以下内容：

    {
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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",
}

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

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

    • 如果您在创建配置文件时使用了 --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 环境变量（如果已设置）。

gcloud CLI 无头登录

如需使用无头流登录 gcloud CLI，请执行以下操作：

OIDC

  1. 让用户登录您的 IdP 应用并获取 OIDC 令牌。

    如需了解如何获取令牌，请参阅您的 IdP 的 OIDC 文档。

  2. 将 IdP 返回的 OIDC 令牌保存在本地机器上的安全位置。

  3. 通过运行以下命令生成配置文件：

    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：与员工池用户项目关联的项目编号

主账号必须具有此项目的 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"
  }
}

SAML

  1. 让用户登录您的 IdP 应用并获取 SAML 断言。

    如需了解如何从 IdP 获取 SAML 断言，请参阅 IdP 的 SAML 文档。

  2. 将 IdP 返回的 SAML 响应保存到本地机器上的安全位置，然后存储该路径，如下所示：

    SAML_ASSERTION_PATH=SAML_ASSERTION_PATH

  3. 如需生成配置文件，请运行以下命令：

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

    替换以下内容：

    • WORKFORCE_PROVIDER_ID：您在本指南前面部分创建的员工提供方 ID。
    • WORKFORCE_POOL_ID：您在本指南前面部分创建的员工池 ID。
    • SAML_ASSERTION_PATH：SAML 断言文件的路径。
    • PROJECT_ID：项目 ID

    生成的配置文件类似于以下内容：

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

如需使用令牌交换登录 gcloud，请运行以下命令：

gcloud auth login --cred-file="config.json"

然后，gcloud 会以透明方式将您的 IdP 凭据交换为临时的 Google Cloud 访问令牌，以便您对 Google Cloud进行其他 gcloud 调用。

输出类似于以下内容：

Authenticated with external account user credentials for:
[principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/USER_ID].

如需列出凭据账号和当前活跃的账号，请运行以下命令：

gcloud auth list

使用服务账号进行授权

gcloud auth login 命令可以使用存储在本地文件系统中的凭据文件，通过服务账号授予访问权限。此凭据可以是具有模拟服务账号权限的用户凭据、工作负载身份联合的凭据配置文件，或服务账号密钥。

使用服务账号模拟功能为服务账号授权

如需授权 gcloud CLI 使用被模拟的服务账号，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往“服务账号”页面。

    转到“服务账号”

  2. 选择现有账号，或点击创建服务账号来创建一个新账号。

  3. 为了确保主账号具有模拟服务账号的必要权限，请让您的管理员为主账号授予服务账号的 Service Account Token Creator (roles/iam.serviceAccountTokenCreator) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

    此预定义角色包含 iam.serviceAccounts.getAccessToken 权限，模拟服务账号需要此权限。

    您的管理员也可以使用自定义角色或其他预定义角色为主账号授予此权限。

  4. 运行 gcloud auth login，使用您的用户身份向 gcloud CLI 授权。

  5. 如需设置 gcloud CLI 以默认使用服务账号提供的身份和访问权限，请使用 gcloud CLI 配置命令：

    gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL

  6. 如需默认停止在 gcloud CLI 中使用被冒充的服务账号凭据，请使用 gcloud CLI 配置命令取消设置该标志：

    gcloud config unset auth/impersonate_service_account

使用 Workload Identity 联合对服务账号进行授权

如需使用来自 Workload Identity Federation 的外部凭据向服务账号授权 gcloud CLI，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往“服务账号”页面。

    转到“服务账号”

  2. 选择现有账号，或点击创建服务账号来创建一个新账号。

  3. 按照受支持的身份提供方的说明为工作负载身份联合创建凭据配置文件。

  4. 如需激活您的服务账号，请运行带有 --cred-file 标志的 gcloud auth login：

    gcloud auth login --cred-file=CONFIGURATION_FILE

    将 CONFIGURATION_FILE 替换为工作负载身份联合的凭据配置文件的路径。

使用服务账号密钥向服务账号授权

如需使用服务账号密钥向 gcloud CLI 授权服务账号账号，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往“服务账号”页面。

    转到“服务账号”

  2. 选择现有账号，或点击创建服务账号来创建一个新账号。

  3. 如需创建服务账号密钥，请参阅创建服务账号密钥的 IAM 说明。

  4. 如需激活您的服务账号，请运行带有 --cred-file 标志的 gcloud auth login：

    gcloud auth login --cred-file=KEY_FILE

    将 KEY_FILE 替换为服务账号密钥文件的路径。

列出账号

如需列出其凭据存储在本地系统上的账号，请运行 gcloud auth list：

gcloud auth list

gcloud CLI 会列出账号并显示哪个账号处于活跃状态：

Credentialed accounts:
 - user-1@gmail.com (active)
 - user-2@gmail.com

切换当前所用账号

如需切换活跃账号，请运行 gcloud config set：

gcloud config set account ACCOUNT

其中，[ACCOUNT] 是该账号的完整电子邮件地址。

要切换账号，您也可以创建一个单独的配置（指定了其他账号）并在配置之间切换：

gcloud config configurations activate CONFIGURATION

如果您想要在每次调用时切换 gcloud CLI 使用的账号，请使用 --account 标志替换活跃账号。

设置已获授权的会话时长

作为管理员，您可以控制不同用户在访问 gcloud CLI 多长时间后需要重新进行身份验证。例如，相对于普通用户，您可以强制更频繁地对拥有更高权限的用户重新执行身份验证。

如需了解详情，请参阅为 Google Cloud 服务设置会话时长。

撤消账号的凭据

如果您想禁止已获得某个特定账号授权的 gcloud CLI 的访问权限，可以撤消凭据。您无需撤消凭据即可在账号之间切换。

如需撤消凭据，请运行 gcloud auth revoke：

gcloud auth revoke ACCOUNT

如需撤消 所有机器上的 gcloud CLI 的所有访问权限，请从有权访问您账号的应用列表中移除 gcloud CLI。

使用凭据文件

查找凭据文件

如需查找凭据文件的位置，请运行 gcloud info：

gcloud info

gcloud CLI 会输出有关安装的信息。凭据文件存储在用户配置目录中：

User Config Directory: [/home/USERNAME/.config/gcloud]

设置应用默认凭据

gcloud CLI 支持使用 gcloud auth application-default 命令组管理应用默认凭据 (ADC)。如需向 ADC 提供用户凭据，请运行 gcloud auth application-default login：

gcloud auth application-default login

gcloud CLI 不会使用这些凭据。如需了解设置 ADC 的更多方法，请参阅设置应用默认凭据。

unset GOOGLE_APPLICATION_CREDENTIALS
gcloud config unset auth/impersonate_service_account
gcloud auth application-default login

后续步骤