为应用默认凭据提供凭据

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

本页面介绍了如何向应用默认凭据 (ADC) 提供凭据,以供 Cloud 客户端库和 Google API 客户端库在各种环境中使用。

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

如需详细了解 ADC 查找凭据的位置和顺序,请参阅应用默认凭据的工作原理

如果您使用的是 API 密钥,就无需使用 ADC 提供凭据。如需有关确定 API 是否接受 API 密钥的帮助,请参阅使用 API 密钥

如何向 ADC 提供凭据

向 ADC 提供凭据的方式取决于您的代码运行位置:

本地开发环境

用户凭据

当您的代码在本地开发环境(例如开发工作站)中运行时,最好的方法是使用与您的 Google 帐号关联的凭据(也称为“用户凭据”)。

如需将用户凭据提供给 ADC,您可以使用 Google Cloud CLI:

  1. 安装并初始化 gcloud CLI(如果尚未这样做)。

  2. 创建凭据文件:

    gcloud auth application-default login

    系统会显示登录屏幕。在您登录后,您的凭据将存储在 ADC 使用的本地凭据文件中。

使用 gcloud CLI 向 ADC 提供凭据存在以下限制:

  • 用户凭据不适用于某些方法和 API,例如 Cloud Translation API 或 Cloud Vision API。如果您看到错误消息,说明 API 未在项目中启用或者没有可用的配额项目,请参阅排查 ADC 设置问题

  • 此方法会将凭据存储在文件系统上的文件中。有权访问文件系统的任何用户都可以使用这些凭据。如果您不再需要这些凭据,则应撤销它们:

    gcloud auth application-default revoke
  • 如果您的 Google 帐号在项目中没有所需的 Identity and Access Management (IAM) 角色,则您的代码可能无法访问某些资源。如果发生这种情况,请让您的安全管理员授予您所需的角色。

gcloud 凭据的类型

gcloud auth application-default login 命令可让您将 Google 帐号的凭据存储在熟知的位置以供 ADC 使用,但这些凭据仅由客户端库和 ADC 使用。在 gcloud CLI 中运行命令时,您使用的是通过 gcloud auth login 命令登录 gcloud CLI 时提供的凭据。

通常,您使用同一帐号登录 gcloud CLI 并向 ADC 提供用户凭据,但如果需要,您可以使用不同的帐号。

如需了解如何登录 gcloud CLI,请参阅初始化 gcloud CLI

服务帐号密钥

如果您无法使用用户凭据进行本地开发,可以使用服务帐号密钥。服务帐号密钥会产生不必要的风险,应尽可能避免使用。

如果您的组织政策具有阻止创建服务帐号密钥的限制条件,则您无法使用此方法。

如需创建服务帐号密钥并将其提供给 ADC,请执行以下操作:

  1. 按照创建服务帐号密钥中的说明,创建一个具有您的应用所需的角色的服务帐号,并为该服务帐号创建密钥。

  2. GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为该密钥的位置。

Google Cloud 云端开发环境

当您使用 Cloud Shell 或 Cloud Code 等 Google Cloud 云端开发环境时,该工具会使用您登录时提供的凭据,并管理所有必要的授权。

容器化开发环境

如果您是在容器化环境中进行本地开发,必须将个人凭据文件提供给容器。为此,您可以使用 GCP 身份验证 minikube 插件

支持进行服务帐号关联的 Google Cloud 服务

某些 Google Cloud 服务(例如 Compute Engine、App Engine 和 Cloud Functions)支持将用户管理的服务帐号关联到某些类型的资源。通常,当服务的资源可以运行或包含应用代码时支持关联服务帐号。将服务帐号关联到资源后,该资源上运行的代码可以使用该服务帐号作为其身份。

关联用户管理的服务帐号是针对 Google Cloud 上运行的生产代码向 ADC 提供凭据的首选方式。

如需有关创建服务帐号的帮助,请参阅创建和管理服务帐号。如需有关确定需要向服务帐号提供的角色的帮助,请参阅选择预定义角色

如需了解可以将服务帐号关联到的资源,以及有关将服务帐号关联到资源的帮助,请参阅有关关联服务帐号的 IAM 文档

如果您的组织政策具有限制创建服务帐号的限制条件,则无法使用此方法为 ADC 设置凭据。

Google Cloud 容器化环境

如果您计划使用 Google Kubernetes Engine 或 Anthos 将应用容器化,则可以通过 gcloud CLI 使用 ADC 进行本地开发,也可以使用本地容器

当您准备好迁移到 Google Cloud 容器化环境时,您需要了解您的环境如何支持身份验证和服务帐号。

本地或其他云服务提供商

如果您在 Google Cloud 之外运行应用,则需要提供 Google Cloud 可识别的凭据才能使用 Google Cloud 服务。

工作负载身份联合

使用不同身份提供商的凭据进行 Google Cloud 身份验证的首选方法是使用工作负载身份联合创建凭据配置文件;您创建一个凭据配置文件并将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设为指向它。此方法比创建服务帐号密钥更安全。

如需有关为 ADC 设置工作负载身份联合的帮助,请参阅配置工作负载身份联合使用身份联合获取短期有效的凭据

服务帐号密钥

如果您无法配置工作负载身份联合,则必须创建一个服务帐号,为其授予您的应用所需的 IAM 角色,并为该服务帐号创建密钥。

如果您的组织政策具有阻止创建服务帐号密钥的限制条件,则您无法使用此方法。

如需创建服务帐号密钥并将其提供给 ADC,请执行以下操作:

  1. 按照创建服务帐号密钥中的说明,创建一个具有您的应用所需的角色的服务帐号,并为该服务帐号创建密钥。

  2. GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为该密钥的位置。

排查 ADC 设置问题

使用 ADC 时可能会遇到的一些常见问题包括以下情况:

用户凭据不起作用

如果您的 API 请求返回有关 API 不支持最终用户凭据、项目中未启用 API 或未设置配额项目的错误消息,请查看以下信息。

Google Cloud API 有两种类型:

  • 基于资源的 API,此 API 使用与所访问的资源关联的项目进行结算和配额计算。

  • 基于客户端的 API,此 API 使用与访问资源的帐号关联的项目进行结算和配额计算。

将 Google 帐号凭据与基于客户端的 API 结合使用时,与该帐号关联的默认项目不能用于结算。

如需解决此问题,您必须更新 ADC 以使用其他项目作为结算项目:

gcloud auth application-default set-quota-project YOUR_PROJECT

您必须拥有项目的 serviceusage.services.use IAM 权限才能将其指定为结算项目。Service Usage Consumer IAM 角色可提供 serviceusage.services.use 权限。如果您没有任何项目的 serviceusage.services.use 权限,请与您的安全管理员或项目所有者联系,他们可以为您授予项目的 Service Usage Consumer 角色。

结算项目不包含在 ADC 返回的 REST 请求令牌中。如果您是通过 REST 请求使用 ADC,请参阅通过 REST 请求设置配额项目

凭据不正确

如果您的凭据似乎没有提供您预期的访问权限,或者找不到您的凭据,请检查 ADC 可用的凭据,按照 ADC 查找凭据的顺序,了解可能存在的问题。以下是需要检查的一些事项:

  • 确保仅当您使用服务帐号密钥或 ADC 的其他 JSON 文件时才设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量。该环境变量指向的凭据优先于其他凭据,包括用于 Workload Identity 的凭据。

  • 确认发出请求的主帐号具有所需的 IAM 角色。如果您使用的是用户凭据,则必须向与 Google 帐号关联的电子邮件地址授予这些角色。如果您使用的是服务帐号,该服务帐号必须具有所需的角色。

  • 如果您在 API 请求中提供 API 密钥,则 API 密钥在任何位置都优先于 ADC。如果您已设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量并且使用的是 API 密钥,则 API 可能会返回一条警告,告知您提供给 ADC 的凭据将予以忽略。如需停止警告,请取消设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量。

凭据类型无法识别

如果 API 请求返回包含“从 JSON 创建凭据时出错。凭据类型无法识别”的错误,请确保您使用的是有效凭据。系统不支持使用客户端 ID 文件为 ADC 提供凭据。

后续步骤