设置应用默认凭据

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

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

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

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

如何向 ADC 提供凭据

选择运行代码的环境：

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

本地开发环境

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

用户凭据

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

使用用户账号配置 ADC 时，您应该注意以下事项：

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

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

• 您的本地 ADC 文件与您的用户账号而非 gcloud CLI 配置相关联。改用其他 gcloud CLI 配置可能会更改 gcloud CLI 使用的身份，但不会影响本地 ADC 文件或 ADC 配置。

使用用户账号配置 ADC 的方式取决于用户账号是由 Google 管理（换句话说，它是 Google 账号）还是由其他身份提供方 (IdP) 管理，并且用户账号通过使用员工身份联合进行联合。

使用 Google 账号配置 ADC

如需使用 Google 账号配置 ADC，您可以使用 Google Cloud CLI：

1. 安装并初始化 gcloud CLI。

   初始化 gcloud CLI 时，请务必指定您在其中有权访问应用所需的资源的 Google Cloud 项目。

2. 配置 ADC：

   gcloud auth application-default login

   登录屏幕随即出现。在您登录后，您的凭据会存储在 ADC 使用的本地凭据文件中。

使用由外部 IdP 管理的账号配置 ADC

如需为由外部 IdP 管理并与员工身份联合进行联合的用户账号配置 ADC，请执行以下操作：

1. 配置员工身份联合。

   如需了解详情，请参阅配置员工身份联合。

2. 配置 gcloud CLI 以使用员工身份联合。

   如需了解详情，请参阅将外部凭据交换为 Google Cloud 访问令牌。

3. 配置 ADC：

   gcloud auth application-default login

   登录屏幕随即出现。在您登录后，您的凭据会存储在 ADC 使用的本地凭据文件中。

服务账号凭据

您可以使用服务账号模拟或服务账号密钥，通过服务账号的凭据来配置 ADC。

服务账号模拟

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

• C#
• 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 文件后一样，通过受支持的语言使用客户端库。身份验证库会自动查找凭据。如需了解详情，请参阅使用客户端库时进行身份验证。

服务账号密钥

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

注意：如果服务账号密钥未得到适当的管理，则会带来安全风险。您应该尽可能选择更安全的服务账号密钥替代方案。如果必须使用服务账号密钥进行身份验证，您将负责私钥的安全性以及管理服务账号密钥的最佳实践中所述的其他操作。如果系统阻止您创建服务账号密钥，您的组织可能会停用服务账号密钥创建功能。如需了解详情，请参阅管理默认安全的组织资源。

如需创建服务账号密钥并将其提供给 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，或使用服务账号配置 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 或 GKE Enterprise

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

在本地测试容器化应用

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

在 Google Cloud 上运行容器化应用

为 Google Cloud 容器化环境设置身份验证的方式因环境而异：

• 对于 GKE Enterprise，请参阅身份验证概览和使用舰队适用于 GKE 的工作负载身份联合。
• 对于 GKE，请参阅从 GKE 工作负载访问 Google Cloud API。
• 对于 Knative serving，请参阅将适用于 GKE 的工作负载身份联合用于 Knative serving。

本地或其他云服务提供商

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

工作负载身份联合

使用不同 IdP 的凭据进行 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 客户端库时进行身份验证。
• 探索身份验证方法。