设置应用默认凭据

本页面介绍了如何设置应用默认凭据 (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 提供凭据

选择运行代码的环境：

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

• Google Kubernetes Engine

• 本地或其他云服务提供商

本地开发环境

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

用户凭据

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

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

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

• 本地 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. Install the Google Cloud CLI, then initialize it by running the following command:

   gcloud init

2. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

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

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

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

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

1. After installing the Google Cloud CLI, configure the gcloud CLI to use your federated identity and then initialize it by running the following command:

   gcloud init

2. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

   If an authentication error is returned, confirm that you have configured the gcloud CLI to use Workforce Identity Federation.

   登录屏幕随即出现。在您登录后，您的凭据会存储在 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. 按照创建服务账号密钥中的说明，创建一个具有您的应用所需的角色的服务账号，并为该服务账号创建密钥。

   Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

   Example: Linux or macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

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

   Example: Windows

   For PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

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

   For command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   注意：当您设置 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 Run functions）支持将用户管理的服务账号关联到某些类型的资源。通常，当服务的资源可以运行或包含应用代码时支持关联服务账号。将服务账号关联到资源后，该资源上运行的代码可以使用该服务账号作为其身份。

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

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

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

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

Set up authentication:

1. Create the service account:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

   Replace SERVICE_ACCOUNT_NAME with a name for the service account.

2. To provide access to your project and your resources, grant a role to the service account:

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

   Replace the following:

   • SERVICE_ACCOUNT_NAME: the name of the service account
   • PROJECT_ID: the project ID where you created the service account
   • ROLE: the role to grant
   Note: The --role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
3. To grant another role to the service account, run the command as you did in the previous step.

4. Grant the required role to the principal that will attach the service account to other resources.

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

   Replace the following:

   • SERVICE_ACCOUNT_NAME: the name of the service account
   • PROJECT_ID: the project ID where you created the service account
   • USER_EMAIL: the email address for a Google Account

GKE

对 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. 按照创建服务账号密钥中的说明，创建一个具有您的应用所需的角色的服务账号，并为该服务账号创建密钥。

   Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

   Example: Linux or macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

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

   Example: Windows

   For PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

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

   For command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

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

后续步骤

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