应用默认凭据的工作原理

本页面介绍了应用默认凭据(ADC)查找凭据的位置。了解 ADC 的工作原理有助于您了解 ADC 正在使用的凭据以及 ADC 查找凭据的方式。

Application Default Credentials (ADC) 是身份验证库使用的一种策略,可根据应用环境自动查找凭据。身份验证库会将这些凭据提供给 Cloud 客户端库和 Google API 客户端库。使用 ADC 时,您的代码可以在开发或生产环境中运行,而无需更改应用向 Google Cloud 服务和 API 进行身份验证的方式。

如需了解如何向 ADC 提供凭据,请参阅设置应用默认凭据

搜索顺序

ADC 在以下位置搜索凭据:

  1. GOOGLE_APPLICATION_CREDENTIALS 环境变量
  2. 使用 Google Cloud CLI 设置的用户凭据
  3. 元数据服务器返回的关联服务账号

ADC 检查凭据的位置顺序与每个位置的相对优势无关。如需有关了解向 ADC 提供凭据的最佳方式的帮助,请参阅设置应用默认凭据

GOOGLE_APPLICATION_CREDENTIALS 环境变量

您可以使用 GOOGLE_APPLICATION_CREDENTIALS 环境变量提供凭据 JSON 文件的位置。此 JSON 文件可以是以下类型的文件之一:

  • 用于员工身份联合的凭据配置文件

    借助员工身份联合,您可以使用外部身份提供方 (IdP) 对用户进行身份验证和授权,以便访问 Google Cloud 资源。如需了解详情,请参阅 Identity and Access Management (IAM) 文档中的员工身份联合

  • 用于工作负载身份联合的凭据配置文件

    借助工作负载身份联合,您可以使用外部 IdP 对工作负载进行身份验证和授权,以便访问 Google Cloud 资源。如需了解详情,请参阅 Identity and Access Management (IAM) 文档中的使用客户端库、gcloud CLI 或 Terraform 进行身份验证

  • 服务账号密钥

    服务账号密钥会产生安全风险,因此不建议使用。与其他凭据文件类型不同,被破解的服务账号密钥可能被恶意用户利用,而无需他们提供任何额外信息。如需了解详情,请参阅使用和管理服务账号密钥的最佳实践

使用 gcloud CLI 提供的用户凭据

您可以通过运行 gcloud auth application-default login 命令向 ADC 提供用户凭据。此命令会将包含您提供的凭据(通常来自您的用户账号)的 JSON 文件置于文件系统上的熟知位置。该位置取决于您的操作系统:

  • Linux、macOS:$HOME/.config/gcloud/application_default_credentials.json
  • Windows:%APPDATA%\gcloud\application_default_credentials.json

您使用 gcloud CLI 提供给 ADC 的凭据与您的 gcloud 凭据不同,gcloud 凭据是 gcloud CLI 用于向 Google Cloud 进行身份验证的凭据。如需详细了解这两组凭据,请参阅 gcloud CLI 身份验证配置和 ADC 配置

默认情况下,如果访问令牌是从使用用户凭据创建的本地 ADC 文件生成的,则访问令牌会包含云范围 https://www.googleapis.com/auth/cloud-platform。如需明确指定范围,请将 –-scopes 标志gcloud auth application-default login 命令结合使用。

如需为 Google Cloud 外部的服务(例如 Google 云端硬盘)添加范围,创建 OAuth 客户端 ID,然后使用 –-client-id-file 标志将其提供给 gcloud auth application-default login 命令,并使用 -–scopes 标志指定范围。

关联的服务账号

许多 Google Cloud 服务可让您关联服务账号,该账号可用于为访问 Google Cloud API 提供凭据。如果 ADC 未找到可在 GOOGLE_APPLICATION_CREDENTIALS 环境变量或本地 ADC 凭据的熟知位置使用的凭据,则会使用元数据服务器获取代码运行的服务的凭据。

如需查找 Google Cloud 上生产环境中的凭据,首选方法是使用关联的服务账号中的凭据。如需使用关联的服务账号,请按照以下步骤操作:

  1. 创建用户管理的服务账号。
  2. 尽可能向该服务账号授予最小权限 IAM 角色。
  3. 将服务账号与运行代码的资源相关联。

如需有关创建服务账号的帮助,请参阅创建和管理服务账号。 如需有关关联服务账号的帮助,请参阅将服务账号关联到资源。如需有关确定服务账号所需的 IAM 角色的帮助,请参阅选择预定义角色

后续步骤