Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

为 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 后立即执行。身份验证和授权包含在初始化流程中。如果您需要使用其他主账号访问不同的资源，或者需要重新验证主账号，则可能仍需再次进行身份验证。
从公开 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 与联合工作负载身份搭配使用。您可以使用工作负载身份联合来实现此目的。

工作负载可以直接访问 Google Cloud 资源，方法是充当由工作负载身份池定义的主账号，或者模拟附加到工作负载身份池的服务账号。

我们建议您使用直接访问方法，以避免服务账号权限过高，并使用联合主账号的标识符记录资源访问权限。只有在 Google Cloud API 不支持工作负载身份联合时，才使用服务账号模拟。

以下说明假定您已设置工作负载身份联合池和提供方，以便与您的 IdP 搭配使用。

按照适用于您的受支持身份提供方的说明，为工作负载身份联合创建凭据配置文件。
在环境变量中、作为有效 gcloud CLI 配置中的属性或使用 gcloud auth login 命令定义凭据配置文件的路径：
环境变量
将 CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 环境变量设置为凭据配置文件的路径。gcloud CLI 每次运行命令时都会引用该文件，并从您的 IdP 获取凭据。此凭据会换成 Google Cloud的访问令牌。

如需停止使用凭据配置文件，请清除 CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 环境变量。
gcloud CLI 配置
使用以下命令将有效 gcloud CLI 配置的 auth/credential_file_override 属性设置为凭据配置文件路径：
gcloud config set auth/credential_file_override CONFIGURATION_PATH
将 CONFIGURATION_PATH 替换为凭据配置文件的路径。

如需停止默认使用凭据配置文件来执行 gcloud 命令，请使用以下命令取消设置相应属性：
gcloud config unset auth/credential_file_override
gcloud auth login
使用 --cred-file 标志运行以下命令：
Linux 和 macOS
gcloud auth login \ --cred-file=CONFIGURATION_PATH

Windows (PowerShell)
gcloud auth login ` --cred-file=CONFIGURATION_PATH
将 CONFIGURATION_PATH 替换为凭据配置文件的路径。

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

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

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

服务账号

您可以通过以下方式将 gcloud CLI 与服务账号搭配使用：

在公开 Compute Engine 元数据服务器的资源上，例如 Compute Engine 虚拟机实例或 Cloud Run 服务。gcloud CLI 默认使用附加到资源的服务账号进行身份验证。
通过使用其他主账号来模拟服务账号。
使用服务账号密钥。

服务账号模拟

对于您的正文通常无法获得的资源访问权限，我们建议您使用 Privileged Access Manager 管理提权，而不是使用服务账号模拟。

如果 Privileged Access Manager 不适合您的使用情形，请完成以下步骤，以将 gcloud CLI 与服务账号搭配使用：

如需模拟服务账号，请确保已在项目中启用 Service Account Credentials API。

启用 API 所需的角色
如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。
启用 API
选择要用于模拟服务账号的主账号。
为了确保主账号具有模拟服务账号的必要权限，请让您的管理员为主账号授予服务账号的 Service Account Token Creator (roles/iam.serviceAccountTokenCreator) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含 iam.serviceAccounts.getAccessToken 权限，模拟服务账号需要此权限。
您的管理员也可以使用自定义角色或其他预定义角色为主账号授予此权限。
使用您之前选择的主账号（无论是用户账号、联合身份用户、联合身份工作负载还是其他服务账号）对 gcloud CLI 进行身份验证。
选择要模拟的服务账号。查找现有服务账号，或创建新服务账号。
复制服务账号电子邮件地址。
选择是为所有命令还是仅为单个命令模拟服务账号：
所有命令
如需在未来的命令中使用 gcloud CLI 进行服务账号模拟，您可以设置环境变量，也可以在有效的 gcloud CLI 配置中设置属性：
- 环境变量：将 CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT 环境变量设置为服务账号电子邮件地址。
  
  如需停止使用服务账号，请清除 CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT 环境变量。
- gcloud CLI 配置：使用以下命令设置有效 gcloud CLI 配置的 auth/impersonate_service_account 属性：
  
  gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_EMAIL
  
  将 SERVICE_ACCOUNT_EMAIL 替换为服务账号的电子邮件地址。
  
  如需停止默认对 gcloud 命令使用服务账号模拟，请使用以下命令取消设置相应属性：
  
  gcloud config unset auth/impersonate_service_account
单个命令
如需将服务账号模拟与 gcloud CLI 搭配使用，以执行单个命令，您可以向 gcloud CLI 服务命令添加 --impersonate-service-account 标志。

例如，如需使用服务账号模拟列出 Compute Engine 虚拟机实例，请运行以下命令：
Linux 和 macOS
gcloud compute instances list \ --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

Windows (PowerShell)
gcloud compute instances list ` --impersonate-service-account=SERVICE_ACCOUNT_EMAIL
将 SERVICE_ACCOUNT_EMAIL 替换为服务账号的电子邮件地址。

服务账号密钥

我们建议您为在 Google Cloud外部运行的大多数工作负载使用工作负载身份联合。只有当您的工作负载在不支持工作负载身份联合的隔离外部环境中运行时，才使用服务账号密钥。

工作负载身份联合具有以下优势：

通过 Identity and Access Management (IAM) 授予对资源的访问权限，并将工作负载视为各个主账号。这意味着，您无需为多种使用情形过度授予服务账号权限。
您可以审核工作负载正在执行的任务；操作不会隐藏在服务账号电子邮件地址后面。
工作负载身份联合使用短期有效的访问令牌来降低数据渗漏风险。服务账号密钥不会过期，除非手动撤消。

如需在未来的命令中使用 gcloud CLI 服务账号，请执行以下操作：

创建服务账号，并将其作为文件存储在您环境中的安全位置。
在环境变量中、作为有效 gcloud CLI 配置中的属性或使用 gcloud auth login 命令定义服务账号密钥文件的路径：
- 环境变量：将 CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 环境变量设置为服务账号密钥文件的路径。
  
  如需停止使用服务账号密钥，请清除 CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 环境变量。
- gcloud CLI 配置：使用以下命令将有效 gcloud CLI 配置的 auth/credential_file_override 属性设置为服务账号密钥的路径：
```
gcloud config set auth/credential_file_override KEY_PATH
```
  将 KEY_PATH 替换为服务账号密钥文件的路径。
  
  如需停止默认使用服务账号密钥来执行 gcloud 命令，请使用以下命令取消设置相应属性：
```
gcloud config unset auth/credential_file_override
```
- gcloud auth login：使用 --cred-file 标志运行以下命令：
  Linux 和 macOS
  gcloud auth login \ --cred-file=KEY_PATH
  Windows (PowerShell)
  gcloud auth login ` --cred-file=KEY_PATH
  将 KEY_PATH 替换为服务账号密钥文件的路径。
  
  gcloud auth login 命令会将访问凭据存储在您的主目录中。经过身份验证的主账号将成为活跃 gcloud CLI 配置中的活跃主账号。除非被替换，否则 gcloud CLI 会使用这些存储的凭据来访问 Google Cloud。
  
  警告：有权访问文件系统的任何用户都可以使用 gcloud auth login 创建的已存储的访问凭据。为减少系统被入侵的后果，请严格区分人工使用和工作负载使用，并且不要在具有持久性存储的远程系统上为自动化工作负载使用 gcloud auth login。请尽可能将 Secret 管理器与环境变量搭配使用。
  
  如需详细了解如何强化远程系统，请参阅缓解 Google Cloud CLI 的 OAuth 令牌被盗用。
  
  注意：对于 P12 旧版格式的服务账号密钥，请使用 gcloud auth activate-service-account 命令。

将 gcloud CLI 与访问令牌搭配使用

如果您已在其他设备上针对 gcloud CLI 完成身份验证，则可以使用以下命令获取相应设备上有效主账号的访问令牌：

gcloud auth print-access-token

然后，您可以在另一部设备上使用此访问令牌来访问 Google Cloud资源。使用访问令牌无需设置有效正文，并且会替换有效 gcloud CLI 配置中设置的任何有效正文。

用户账号的访问令牌的默认有效期为 1 小时。

您可以将访问令牌与 gcloud CLI 搭配使用，以用于未来的命令，也可以仅用于单个命令。

所有命令

如需在未来的命令中使用 gcloud CLI 的访问令牌，您可以设置环境变量，也可以在有效的 gcloud CLI 配置中设置属性：

环境变量：将 CLOUDSDK_AUTH_ACCESS_TOKEN 环境变量设置为访问令牌字符串。

如需停止使用访问令牌，请清除 CLOUDSDK_AUTH_ACCESS_TOKEN 环境变量。
gcloud CLI 配置：将访问令牌存储在一个文件中，然后使用以下命令将有效 gcloud CLI 配置的 auth/access_token_file 属性设置为该文件的路径：
```
gcloud config set auth/access_token_file ACCESS_TOKEN_PATH
```
将 ACCESS_TOKEN_PATH 替换为访问令牌文件的路径。

如需停止默认使用访问令牌来执行 gcloud 命令，请使用以下命令取消设置相应属性：
```
gcloud config unset auth/access_token_file
```

单个命令

如需将访问令牌与 gcloud CLI 搭配使用以执行单个命令，您可以向 gcloud CLI 服务命令添加 --access-token-file 标志：

将访问令牌存储在文件中。
将 --access-token-file 标志与任何 gcloud 服务命令搭配使用。

例如，如需使用访问令牌列出 Compute Engine 虚拟机实例，请运行以下命令：
Linux 和 macOS
gcloud compute instances list \ --access-token-file ACCESS_TOKEN_PATH
Windows (PowerShell)
gcloud compute instances list ` --access-token-file ACCESS_TOKEN_PATH
将 ACCESS_TOKEN_PATH 替换为访问令牌文件的路径。

凭据优先级

由于一个环境中可能会使用多种身份验证方法，因此 gcloud CLI 会按特定顺序评估这些方法，以确定要使用哪个主账号。gcloud CLI 会先使用提供的凭据，然后评估是否已请求服务账号模拟。

所提供凭据的评估顺序如下：

CLOUDSDK_AUTH_ACCESS_TOKEN 环境变量，设置为访问令牌字符串。
访问令牌文件。用于定义访问令牌文件路径的方法按以下顺序进行评估：
1. --access-token-file 命令行标志，可与任何 gcloud CLI 命令搭配使用。
2. CLOUDSDK_AUTH_ACCESS_TOKEN_FILE 环境变量。
3. 有效 gcloud CLI 配置中的 auth/access_token_file 属性。
凭据文件。用于定义凭据文件路径的方法按以下顺序进行评估：
1. CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 环境变量。
2. 有效 gcloud CLI 配置中的 auth/credential_file_override 属性。
通过 gcloud auth login 命令或设置 core/account 属性设置的有效正文。

服务账号模拟优先级

如果已请求服务账号模拟，则 gcloud CLI 会在为执行模拟的主账号提供凭据后检查要模拟哪个服务账号。用于定义要模拟的服务账号的方法按以下顺序进行评估：

--impersonate-service-account 命令行标志。
CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT 环境变量。
有效配置中由 auth/impersonate_service_account 属性定义的服务账号。

将 Google 云端硬盘添加到您的范围中

除了 Google Cloud之外，还可以扩大 gcloud CLI 范围，以包含 Google 云端硬盘访问权限。这意味着您可以使用 Google Cloud 访问令牌访问 Google 云端硬盘。

如需扩大范围以涵盖 Google 云端硬盘，请在授权 gcloud CLI 时添加 --enable-gdrive-access 标志：

Linux 和 macOS

gcloud auth login \
    --enable-gdrive-access

Windows (PowerShell)

gcloud auth login `
    --enable-gdrive-access

然后，您可以使用 gcloud CLI 调用 Google Drive API 来提供访问令牌。例如，如需列出 Google 云端硬盘中的所有文件，您可以发出以下请求：

Linux 和 macOS

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://www.googleapis.com/drive/v3/files"

Windows (PowerShell)

Invoke-WebRequest `
  -Method GET `
  -Headers @{ "Authorization" = "Bearer $(gcloud auth print-access-token)" } `
  -ContentType "application/json; charset=utf-8" `
  -UseBasicParsing `
  -Uri "https://www.googleapis.com/drive/v3/files" | Select-Object -Expand Content

然后，您可以例如使用上一个命令的响应中的文件 ID 从 Google 文档文件中提取文本：

Linux 和 macOS

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=text/plain"

Windows (PowerShell)

Invoke-WebRequest `
  -Method GET `
  -Headers @{ "Authorization" = "Bearer $(gcloud auth print-access-token)" } `
  -ContentType "application/json; charset=utf-8" `
  -UseBasicParsing `
  -Uri "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=text/plain" | Select-Object -Expand Content

Google 云端硬盘访问权限的常见用例是将 BigQuery 与存储在 Google 表格中的数据搭配使用。

如需详细了解 Google Drive API，请参阅 Google Drive API 概览。

将 gcloud CLI 添加为 Docker 的凭据帮助程序

如需从 Artifact Registry 容器注册表中拉取内容，您可以将 gcloud CLI 添加为凭据帮助程序到 Docker 配置中。

为此，请运行 gcloud auth configure-docker 命令：

gcloud auth configure-docker REGION-docker.pkg.dev

管理正文和凭据

您可以使用 gcloud auth login 命令在同一环境中对多个主账号进行身份验证，并授权 gcloud CLI 代表这些主账号访问资源。不过，任何时候都只能有一个委托人处于有效状态。以下部分介绍了如何管理 gcloud CLI 配置中的正文，包括列出正文、在正文之间切换以及撤消正文的凭据。

列出主账号

如需列出访问凭据存储在本地系统上的主账号（即已使用 gcloud auth login 进行身份验证的主账号），请运行 gcloud auth list 命令：

gcloud auth list

gcloud CLI 会列出正文并显示哪个正文处于有效状态：

Credentialed Accounts
ACTIVE  ACCOUNT
        alex@altostrat.com
*       bola@altostrat.com
        principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/cruz@cymbalgroup.com

此列表中不包含有效主账号的替换项。其中包括以下环境变量：

CLOUDSDK_AUTH_ACCESS_TOKEN
CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE
CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT

如需检查是否已设置这些环境变量，请针对您的操作系统运行以下命令：

Linux 和 macOS

echo "$ENVIRONMENT_VARIABLE"

Windows (PowerShell)

echo $env:ENVIRONMENT_VARIABLE

将 ENVIRONMENT_VARIABLE 替换为您要检查的环境变量。

有效主账号的替换项还包括以下配置属性：

auth/access_token_file
auth/credential_file_override
auth/impersonate_service_account

如需检查是否已设置这些配置属性，请运行以下命令：

gcloud config list

切换有效正文

如需切换到具有已存储凭据（即之前已完成 gcloud auth login 流程）的有效正文，请运行 gcloud config set：

gcloud config set account PRINCIPAL_IDENTIFIER

将 PRINCIPAL_IDENTIFIER 替换为主账号的完整标识符。

您还可以通过以下方式切换委托人：

创建单独的配置，指定其他有效正文，然后激活该配置。
使用 --account 命令行标志为单个命令指定主账号。
使用替换项，例如命令行标志、环境变量或配置属性。

设置会话时长

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

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

撤消主账号的凭据

您可以撤消已通过 gcloud auth login 进行身份验证的主账号的凭据，这样 gcloud CLI 就无法代表这些主账号执行操作。撤消操作会使 Google 授权服务器上的凭据失效，并从有效的 gcloud CLI 配置中移除相应的主账号。

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

gcloud auth revoke PRINCIPAL_IDENTIFIER

将 PRINCIPAL_IDENTIFIER 替换为主账号的完整标识符。

如需撤消 gcloud CLI 对与您的 Google 账号关联的所有设备的访问权限，请前往 Google 账号设置中的第三方应用和服务，然后删除与 Google Cloud SDK 的所有关联。

管理存储的凭据

gcloud CLI 会将其使用的凭据文件存储在 gcloud CLI 配置目录中。如需查找凭据文件的位置，请运行 gcloud info：

gcloud info

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

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

对于 Linux 和 macOS，gcloud CLI 配置目录通常为 /home/USERNAME/.config/gcloud。对于 Windows，该目录为 %APPDATA%\gcloud。

后续步骤

如需详细了解如何自定义 gcloud CLI，请参阅 gcloud CLI 属性。
如需详细了解如何管理 gcloud CLI 属性的命名集，请参阅 gcloud CLI 配置。
如需对使用 Cloud 客户端库或 Google API 客户端库的基于代码的工作负载进行身份验证，请参阅应用默认凭证的工作原理。

为 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 配置

gcloud auth login

Linux 和 macOS

Windows (PowerShell)

服务账号

服务账号模拟

所有命令

单个命令

Linux 和 macOS

Windows (PowerShell)

服务账号密钥

Linux 和 macOS

Windows (PowerShell)

将 gcloud CLI 与访问令牌搭配使用

所有命令

单个命令

Linux 和 macOS

Windows (PowerShell)

凭据优先级

服务账号模拟优先级

将 Google 云端硬盘添加到您的范围中

Linux 和 macOS

Windows (PowerShell)

Linux 和 macOS

Windows (PowerShell)

Linux 和 macOS

Windows (PowerShell)

将 gcloud CLI 添加为 Docker 的凭据帮助程序

管理正文和凭据

列出主账号

Linux 和 macOS

Windows (PowerShell)

切换有效正文

设置会话时长

撤消主账号的凭据

管理存储的凭据

后续步骤

为 gcloud CLI 进行身份验证