设置应用默认凭据

本页面介绍了如何设置应用默认凭据 (ADC)，以供 Cloud 客户端库、Google API 客户端库以及 REST 和远程过程调用 (RPC) API 在各种环境中使用。您可以通过在代码运行的环境中向 ADC 提供凭据来设置 ADC。

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

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

如果您使用的是 API 密钥，则无需设置 ADC。如需了解详情，请参阅使用 API 密钥。

如何向 ADC 提供凭据

选择运行代码的环境：

• 本地开发环境
• Cloud Shell 或其他 Google Cloud 云端开发环境
• Compute Engine 或其他支持关联服务账号的 Google Cloud 服务
• Google Kubernetes Engine 或 Anthos
• 本地或其他云服务提供商

本地开发环境

您可以在本地开发环境中向 ADC 提供用户凭据或服务账号凭据。

用户凭据

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

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

1. 安装并初始化 gcloud CLI。

2. 创建凭据文件：

   gcloud auth application-default login

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

如果您提供用户凭据来创建本地 ADC 文件，请注意以下事项：

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

• 本地 ADC 包含访问令牌和刷新令牌。有权访问文件系统的任何用户都可以使用这些凭据。如果您不再需要这些本地凭据，可以使用 gcloud auth application-default revoke 命令将其撤消。

• 如果您的 Google 账号在项目中没有所需的 Identity and Access Management (IAM) 角色，则您的代码可能无法访问某些资源。如果发生这种情况，必须有人为您授予所需的角色。

• 您的本地 ADC 文件与您的用户账号而非 gcloud CLI 配置相关联。改用其他 gcloud CLI 配置不会影响您的本地 ADC 文件或提供给 ADC 的凭据。

服务账号凭据

您可以使用服务账号模拟或服务账号密钥来设置来自服务账号的 ADC。

服务账号模拟

您可以使用服务账号模拟来设置本地应用默认凭据 (ADC) 文件。支持模拟的客户端库可以自动使用这些凭据。使用模拟创建的本地 ADC 文件支持以下语言：

• Go
• Java
• Node.js
• Python

您必须具有要模拟的服务账号的 Service Account Token Creator (roles/iam.serviceAccountTokenCreator) IAM 角色。如需了解详情，请参阅必需的角色。

使用服务账号模拟创建本地 ADC 文件：

gcloud auth application-default login --impersonate-service-account SERVICE_ACCT_EMAIL

服务账号密钥

如果您无法使用用户凭据或服务账号模拟进行本地开发，可以使用服务账号密钥。

注意：如果服务账号密钥未正确管理，则会带来安全风险。您应该尽可能选择更安全的服务账号密钥替代方案。如果必须使用服务账号密钥进行身份验证，您将负责私钥的安全性和其他管理操作（如密钥轮替）。如需了解详情，请参阅管理服务账号密钥的最佳实践。

如需创建服务账号密钥并将其提供给 ADC，请执行以下操作：

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

2. 将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为包含您的服务帐号密钥的 JSON 文件的路径。 此变量仅适用于当前的 shell 会话，因此，如果您打开新的会话，请重新设置该变量。

   示例：Linux 或 macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   将 KEY_PATH 替换为包含您的服务帐号密钥的 JSON 文件的路径。

   例如：

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   示例：Windows

   对于 PowerShell：

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   将 KEY_PATH 替换为包含您的服务帐号密钥的 JSON 文件的路径。

   例如：

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   对于命令提示符：

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   将 KEY_PATH 替换为包含您的服务帐号密钥的 JSON 文件的路径。

注意：当您设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量时，ADC 会先检查此位置，然后仅在必要时检查其他位置。

Google Cloud 云端开发环境

当您使用 Cloud Shell 或 Cloud Code 等 Google Cloud 云端开发环境时，该工具会使用您登录时提供的凭据，并管理所有必要的授权。 在这些环境中，您无法使用 gcloud CLI 向 ADC 提供凭据。如果您需要向 ADC 提供不同的用户账号，或者使用服务账号提供凭据，请使用本地开发环境或 Google Cloud 计算资源作为开发环境。

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

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

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

注意：其中许多 Google Cloud 服务还提供默认服务账号。不建议使用默认服务账号，因为默认情况下，默认服务账号具有较高的权限，这违反了最小权限原则。

如需有关确定需要向服务账号提供的角色的帮助，请参阅选择预定义角色。

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

设置身份验证：

1. 创建服务帐号：

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

   将 SERVICE_ACCOUNT_NAME 替换为服务帐号的名称。

2. 如需提供对项目和资源的访问权限，请向服务帐号授予角色：

   gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

   请替换以下内容：

   • SERVICE_ACCOUNT_NAME：服务帐号的名称
   • PROJECT_ID：您在其中创建服务帐号的项目的 ID
   • ROLE：要授予的角色
   注意：--role 标志会影响服务帐号可以访问项目中的哪些资源。您可以撤消这些角色或稍后授予其他角色。在生产环境中，请勿授予 Owner、Editor 或 Viewer 角色。应授予满足您的需求的预定义角色或自定义角色。
3. 要向服务帐号授予其他角色，请按照上一步中的说明运行命令。

4. 为您的 Google 帐号授予一个可让您使用服务帐号的角色并将服务帐号关联到其他资源的角色：

   gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

   替换以下内容：

   • SERVICE_ACCOUNT_NAME：服务帐号的名称
   • PROJECT_ID：您在其中创建服务帐号的项目的 ID
   • USER_EMAIL：您的 Google 帐号的电子邮件地址

GKE 或 Anthos

对 GKE 或 Anthos 上运行的容器化应用进行身份验证时，本地测试环境与 Google Cloud 环境的处理方式不同。

在本地测试容器化应用

如需在本地工作站上测试容器化应用，您可以将容器配置为使用本地凭据文件进行身份验证。如需测试容器，请使用本地 Kubernetes 实现，例如 minikube 和 GCP Auth minikube 插件。

在 Google Cloud 上运行容器化应用

根据具体情况，为 Google Cloud 容器化环境设置身份验证：

• 对于 Anthos，请参阅身份验证概览和使用舰队 Workload Identity。
• 对于 GKE，请参阅使用 Workload Identity for GKE。
• 对于 Cloud Run for Anthos，请参阅为 Cloud Run for Anthos 使用 Workload Identity。

本地或其他云服务提供商

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

工作负载身份联合

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

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

服务账号密钥

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

注意：如果服务账号密钥未正确管理，则会带来安全风险。您应该尽可能选择更安全的服务账号密钥替代方案。如果必须使用服务账号密钥进行身份验证，您将负责私钥的安全性和其他管理操作（如密钥轮替）。如需了解详情，请参阅管理服务账号密钥的最佳实践。

如需创建服务账号密钥并将其提供给 ADC，请执行以下操作：

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

   将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为包含您的服务帐号密钥的 JSON 文件的路径。 此变量仅适用于当前的 shell 会话，因此，如果您打开新的会话，请重新设置该变量。

   示例：Linux 或 macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   将 KEY_PATH 替换为包含您的服务帐号密钥的 JSON 文件的路径。

   例如：

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   示例：Windows

   对于 PowerShell：

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   将 KEY_PATH 替换为包含您的服务帐号密钥的 JSON 文件的路径。

   例如：

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   对于命令提示符：

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   将 KEY_PATH 替换为包含您的服务帐号密钥的 JSON 文件的路径。

   注意：当您设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量时，ADC 会先检查此位置，然后仅在必要时检查其他位置。

后续步骤

• 详细了解 ADC 如何查找凭据。
• 使用 Cloud 客户端库时进行身份验证。
• 探索在 Google 进行身份验证。