Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

为 gcloud CLI 进行身份验证

本文档仅介绍 Google Cloud CLI 对Google Cloud 资源的身份验证。如果您需要使用 Cloud 客户端库或 Google API 客户端库对工作负载进行身份验证，请参阅应用默认凭据的工作方式。

准备工作

如果您是 Google Cloud 新手，并且只想在本地开发环境中开始使用 gcloud CLI 命令，可以使用以下命令初始化 gcloud CLI：

gcloud init

初始化会引导您完成身份验证流程，设置 gcloud CLI 配置，并授权 gcloud CLI 代表您执行操作。无需执行单独的身份验证步骤。

本文档的其余部分将介绍更复杂的场景，例如将 gcloud CLI 与不同的主账号类型搭配使用、适用于不同环境的适当身份验证方法、切换主账号以及管理存储的凭据。

身份验证方法

所有 gcloud CLI 命令都需要向 Google CloudAPI 进行身份验证。您可以通过以下方式进行身份验证：

授权和存储凭据：适合人类在本地开发环境中使用。您可以使用 gcloud auth login 命令授权 gcloud CLI 代表主账号执行操作。完成初始身份验证后，此命令会将凭据存储在 gcloud CLI 配置目录中。gcloud CLI 会使用这些存储的凭据自动对后续命令进行身份验证，直到会话过期或您撤消授权。
使用凭据文件进行身份验证：适用于在 Google Cloud外部运行的工作负载。您可以使用环境变量或 gcloud CLI 配置属性来指定用于自动身份验证的凭据文件。此文件可以是以下文件之一：
- 工作负载身份联合凭据配置文件。
- 服务账号密钥。
提供访问令牌：适合高度隔离的自动化工作流或共享机器上的无状态会话。您可以直接向 gcloud CLI 提供访问令牌，从而绕过凭据存储。为此，您可以将特定环境变量设置为原始访问令牌字符串，也可以将 gcloud CLI 指向包含访问令牌的文件。

完成身份验证后，您可以选择通过提供服务账号的电子邮件地址，让 gcloud CLI 模拟服务账号。

您可以在单个环境中使用多种身份验证方法。不过，任何给定的 gcloud 命令都只能使用一个主账号。为了确定要使用哪个主账号，gcloud CLI 会遵循优先级顺序。

无需进行身份验证的情况

在以下情况下，您无需对 gcloud CLI 进行身份验证：

在您初始化 gcloud CLI 后立即执行。身份验证和授权 gcloud CLI 代表您执行操作都包含在初始化过程中。如果您需要使用其他主账号访问不同的资源，或者需要重新验证主账号，则可能仍需再次进行身份验证。
从公开 Compute Engine 元数据服务器的资源使用 gcloud CLI 时。这包括 Compute Engine 虚拟机实例、Cloud Run 服务和 Cloud Build build 等资源。gcloud CLI 使用附加到虚拟机的服务账号进行身份验证，并且可以在已应用的任何访问权限范围的限制范围内访问与该服务账号相同的资源。
使用 Cloud Shell 时。gcloud CLI 会自动使用您登录 Google Cloud 控制台时所用的主账号进行身份验证。当您在新的 Cloud Shell 会话中首次运行 gcloud CLI 命令时，系统会提示您使用该主账号为 Cloud Shell 授权。

为任务选择合适的主账号

对于人工使用和自动化工作负载，有不同类型的主账号。您需要使用的主账号类型会影响您的身份验证方式。

用户账号：这些是供人类用户执行交互式工作的 Google 账号，例如执行临时管理任务、以非程序化方式配置 Google Cloud 服务、进行测试、实验和可观测性分析。

您可以使用用户凭据（例如密码和一次性验证码）以用户账号身份进行身份验证。
服务账号：这些账号是 Google Cloud 特有的账号，工作负载可以使用这些账号来访问服务或资源。您通常不会直接以服务账号身份进行身份验证。而是将服务账号附加到 Compute Engine 虚拟机等资源，或使用服务账号模拟。
联合正文：这些身份引用外部身份提供方中的用户账号或服务账号。 Google Cloud支持两种联合身份，这两种身份的名称相似：
- 员工身份联合：可让人类用户使用由外部身份提供方管理的身份登录 Google Cloud 。如果贵组织已设置单点登录 (SSO)，您可以使用此类身份向 Google Cloud进行身份验证。
  
  您的身份提供方必须支持 OpenID Connect (OIDC) 或 SAML 2.0，才能使用员工身份联合。
- 工作负载身份联合：使在 Google Cloud 外部运行的工作负载能够操作 Google Cloud 资源。
  
  您可以将工作负载身份联合与以下工作负载搭配使用：使用 X.509 客户端证书进行身份验证；在 Amazon Web Services (AWS) 或 Azure 上运行；使用本地 Active Directory；使用部署服务（例如 GitHub 和 GitLab）；以及使用支持 OpenID Connect (OIDC) 或安全声明标记语言 (SAML) V2.0 的任何身份提供方。

像人类一样使用 gcloud CLI

对于交互式任务，您通常通过以下方式之一进行身份验证：

用户账号
使用员工身份联合的联合用户身份

用户账号

您如何使用用户账号向 gcloud CLI 进行身份验证，取决于您的设备上是否安装了 Web 浏览器。

我的设备有网络浏览器

如需在具有 Web 浏览器的设备上使用用户账号进行身份验证，请完成以下步骤：

运行以下命令以启动该进程：
```
gcloud auth login
```
按照基于浏览器的流程操作，以便对 gcloud CLI 进行身份验证和授权，使其能够代表您访问资源以执行未来的命令。

gcloud auth login 命令会将访问凭据存储在您的主目录中。经过身份验证的主账号将成为活跃 gcloud CLI 配置中的活跃主账号。除非被替换，否则 gcloud CLI 会使用这些存储的凭据来访问 Google Cloud。

我的设备没有网络浏览器

如果您需要在没有网络浏览器的设备上使用 gcloud CLI，可以在另一台可信设备上使用您的用户账号进行身份验证。此流程因其他可信设备上安装的软件而异。

使用其他受信任的设备进行身份验证

选择另一部可信设备上可用的软件。

gcloud CLI 和网络浏览器

使用 --no-browser 标志在安装了网络浏览器和 gcloud CLI 的其他设备上完成身份验证过程：

在要使用 gcloud CLI 的原始设备上运行以下命令：
Linux 和 macOS
gcloud auth login \ --no-browser
Windows (PowerShell)
gcloud auth login ` --no-browser
复制以 gcloud auth login --remote-bootstrap=" 开头的 gcloud 命令，以便在另一部设备上使用。
前往另一台可信设备，该设备既有网络浏览器，也安装了 gcloud CLI 372.0.0 版或更高版本。
在终端中，运行您之前复制的以 gcloud auth login --remote-bootstrap=" 开头的命令，并完成基于浏览器的流程。
在终端中，复制以 https://localhost 开头的网址，以便在原始设备上使用。
返回到原设备。
在终端中，在提示符处粘贴您之前复制的 https://localhost 网址。按键盘上的 Enter 或 Return 键完成该流程。

仅限网络浏览器

使用 --no-launch-browser 标志通过其他设备的网络浏览器完成身份验证流程：

在要使用 gcloud CLI 的原始设备上运行以下命令：

Linux 和 macOS

gcloud auth login \
    --no-launch-browser

Windows (PowerShell)

gcloud auth login `
    --no-launch-browser

复制以 https://accounts.google.com/o/oauth2/auth 开头的网址，以便在其他设备上使用。
前往已安装 Web 浏览器的其他可信设备。
打开网络浏览器，前往您之前复制的网址，然后完成基于浏览器的流程。
复制验证码以在原始设备上使用。
返回到原设备。
在终端的提示符处，粘贴您之前复制的验证码。按键盘上的 Enter 键或 Return 键完成该流程。

联合用户身份

您可以将 gcloud CLI 与在外部身份提供方 (IdP) 中管理的联合用户身份搭配使用。您可以使用员工身份联合来实现此目的。

在开始之前，请确保您已设置员工身份联合池和提供方，以便与您的 IdP 搭配使用。如需了解详情，请参阅配置员工身份联合。

如需使用联合用户身份登录 gcloud CLI，请完成以下步骤：

创建登录配置文件：

运行以下命令以创建登录配置文件：
Linux 和 macOS
gcloud iam workforce-pools create-login-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \ --output-file=LOGIN_CONFIG_PATH
Windows (PowerShell)
gcloud iam workforce-pools create-login-config ` locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID ` --output-file=LOGIN_CONFIG_PATH
注意：您可以选择添加 --activate 标志来激活登录配置文件，将其作为 gcloud CLI 的默认设置。然后，您就可以运行 gcloud auth login 来授权 gcloud CLI，而无需每次都指定登录配置文件路径。

替换以下内容：
- WORKFORCE_POOL_ID：员工身份联合身份池 ID。
- WORKFORCE_PROVIDER_ID：员工身份联合提供方 ID。
- LOGIN_CONFIG_PATH：要写入登录配置文件的路径。例如 login-config.json。
登录配置文件包含 gcloud CLI 用于启用基于浏览器的身份验证流程的端点，并将受众群体设置为在员工身份池提供方中配置的 IdP。该文件不含机密信息。

登录配置文件内容类似于以下内容：
```
{
  "universe_domain": "googleapis.com",
  "universe_cloud_web_domain": "cloud.google",
  "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"
}
```
注意：我们建议您先确保此文件的内容正确无误，然后保护该文件（例如，将其设为只读并使用 ACL 限制访问权限）。该文件未经过验证；怀有恶意的操作者如果拥有该文件写入权限，就可以更改端点和拦截凭据。
使用基于浏览器的身份验证登录：

通过环境变量、有效 gcloud CLI 配置中的属性指向登录配置文件，或直接将其与 gcloud auth login 命令搭配使用：
环境变量

如需使用环境变量来使用登录配置文件，请完成以下说明：
1. 将 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 环境变量设置为登录配置文件的路径。
2. 运行以下命令：
  
  gcloud auth login
3. gcloud CLI 会引用该环境变量来查找登录配置文件，然后启动身份验证流程。按照基于浏览器的流程操作，以便对 gcloud CLI 进行身份验证和授权，使其能够代表您访问资源以供日后执行命令。
如需停止为 gcloud auth login 命令使用登录配置文件，请清除 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 环境变量。
gcloud CLI 配置

如需将登录配置文件与 gcloud CLI 配置属性搭配使用，请完成以下说明：
1. 使用以下命令将有效 gcloud CLI 配置的 auth/login_config_file 属性设置为登录配置文件的路径：
  
  gcloud config set auth/login_config_file LOGIN_CONFIG_PATH
2. 运行以下命令：
  
  gcloud auth login
3. gcloud CLI 会引用配置属性来查找登录配置文件，然后启动身份验证流程。按照基于浏览器的流程操作，以便对 gcloud CLI 进行身份验证和授权，使其能够代表您访问资源以供日后执行命令。
如需停止将登录配置文件用于 gcloud auth login 命令，请使用以下命令取消设置相应属性：
gcloud config unset auth/login_config_file
gcloud auth login

如需直接将登录配置文件与 gcloud auth login 命令搭配使用，请完成以下说明：
- 如果您在创建登录配置文件时使用了 --activate 标志，请运行以下命令：
  
  gcloud auth login
- 如果您在创建登录配置文件时未使用 --activate 标志，请运行以下命令：
  
  Linux 和 macOS
  
  gcloud auth login \ --login-config=LOGIN_CONFIG_PATH
  
  Windows (PowerShell)
  
  gcloud auth login ` --login-config=LOGIN_CONFIG_PATH
  
  将 LOGIN_CONFIG_PATH 替换为登录配置文件的路径。
gcloud auth login 命令会将访问凭据存储在您的主目录中。经过身份验证的主账号将成为活跃 gcloud CLI 配置中的活跃主账号。除非被替换，否则 gcloud CLI 会使用这些存储的凭据来访问 Google Cloud。

警告：有权访问文件系统的任何用户都可以使用 gcloud auth login 创建的已存储的访问凭据。为减少系统被入侵的后果，请严格区分人工使用和工作负载使用，并且不要在具有持久性存储的远程系统上为自动化工作负载使用 gcloud auth login。请尽可能将 Secret 管理器与环境变量搭配使用。

如需详细了解如何强化远程系统，请参阅缓解 Google Cloud CLI 的 OAuth 令牌被盗用。

如需了解详情，请参阅使用联合身份登录 gcloud CLI。

为 gcloud CLI 进行身份验证 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

身份验证方法

无需进行身份验证的情况

为任务选择合适的主账号

像人类一样使用 gcloud CLI

用户账号

我的设备有网络浏览器

我的设备没有网络浏览器

使用其他受信任的设备进行身份验证

gcloud CLI 和网络浏览器

Linux 和 macOS

Windows (PowerShell)

仅限网络浏览器

Linux 和 macOS

Windows (PowerShell)

联合用户身份

Linux 和 macOS

Windows (PowerShell)

环境变量

gcloud CLI 配置

gcloud auth login

Linux 和 macOS

Windows (PowerShell)

将 gcloud CLI 与工作负载搭配使用

为 gcloud CLI 进行身份验证