本主题介绍了如何以服务帐号身份对应用进行身份验证。 如需了解有关向 Google Cloud API 进行身份验证的一般信息(包括常见的身份验证场景和策略),请参阅身份验证概览。如需详细了解服务帐号,请参阅 Identity and Access Management 文档中的服务帐号。
自动查找凭据
如果您的应用在 Google Cloud 环境中运行,并且您已经向该环境附加服务帐号,则您的应用可以检索该服务帐号的凭据。然后,应用可以使用这些凭据来调用 Google Cloud API。
您可以将服务帐号附加到许多不同 Google Cloud 服务的资源,包括 Compute Engine、Google Kubernetes Engine、App Engine、Cloud Run 和 Cloud Functions。我们建议使用此策略,因为这种做法比手动传递凭据更便捷、更安全。
此外,我们建议您在应用中使用 Google Cloud 客户端库。Google Cloud 客户端库使用名为“应用默认凭据”(ADC) 的库来自动查找您的服务帐号凭据。ADC 会按以下顺序查找服务帐号凭据:
如果设置了环境变量
GOOGLE_APPLICATION_CREDENTIALS
,则 ADC 使用该变量指向的服务帐号密钥或配置文件。如果未设置环境变量
GOOGLE_APPLICATION_CREDENTIALS
,则 ADC 使用关联到运行代码的资源的服务帐号。此服务帐号可能是 Compute Engine、Google Kubernetes Engine、App Engine、Cloud Run 或 Cloud Functions 提供的默认服务帐号,也可能是您创建的用户管理的服务帐号。
如果 ADC 无法使用上述任何凭据,则会引发错误。
以下代码示例展示了如何在应用代码中使用 ADC 库。要运行此示例,您必须安装 Cloud Storage 客户端库。
C#
Go
Java
Node.js
PHP
Python
Ruby
手动传递凭据
如果您的应用在未关联服务帐号的环境(例如本地或其他云服务商)中运行,您应该使用工作负载身份联合。
如果您无法使用工作负载身份联合,则必须创建一个服务帐号以及一个或多个服务帐号密钥,这些密钥是与该服务帐号关联的凭据。您可以手动将服务帐号密钥传递到您的应用。
请务必查看管理服务帐号密钥的最佳实践。
创建服务帐号
以下步骤介绍了如何创建服务帐号(如果您没有该帐号):
控制台
创建服务帐号:
-
在控制台中,打开创建服务帐号页面。
打开“创建服务帐号” - 选择您的项目。
-
在服务帐号名称字段中,输入一个名称。控制台会根据此名称填充服务帐号 ID 字段。
在服务帐号说明字段中,输入说明。例如,
Service account for quickstart
。 - 点击创建并继续。
-
如需提供对项目的访问权限,请向服务帐号授予以下角色:Project > Owner。
在选择角色列表中,选择一个角色。
如需添加其他角色,请点击
添加其他角色,然后添加其他各个角色。 - 点击继续。
-
点击完成以完成服务帐号的创建过程。
不要关闭浏览器窗口。您将在下一步骤中用到它。
创建服务帐号密钥:
- 在控制台中,点击您创建的服务帐号的电子邮件地址。
- 点击密钥。
- 点击添加密钥,然后点击创建新密钥。
- 点击创建。JSON 密钥文件将下载到您的计算机上。
- 点击关闭。
gcloud
设置身份验证:
-
创建服务帐号:
gcloud iam service-accounts create NAME
将
NAME
替换为服务帐号的名称。 -
向服务帐号授予角色。对以下每个 IAM 角色运行以下命令一次:
roles/owner
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
:您在其中创建服务帐号的项目的 IDROLE
:要授予的角色
-
生成密钥文件:
gcloud iam service-accounts keys create FILE_NAME.json --iam-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
替换以下内容:
FILE_NAME
:密钥文件的名称SERVICE_ACCOUNT_NAME
:服务帐号的名称PROJECT_ID
:您在其中创建服务帐号的项目的 ID
通过环境变量传递凭据
通过设置环境变量 GOOGLE_APPLICATION_CREDENTIALS
向应用代码提供身份验证凭据。此变量仅适用于当前的 Shell 会话。如果您希望变量应用于未来的 Shell 会话,请在 shell 启动文件中设置变量,例如在 ~/.bashrc
或 ~/.profile
文件中。
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 文件的路径。
完成上述步骤后,ADC 可以自动查找您的凭据,如以上部分所述。我们建议您使用 ADC,因为需要使用的代码更少且代码可在不同的环境中移植。
使用代码传递凭据
如以下示例中所示,您可以选择在代码中明确指向服务帐号文件。必须安装 Cloud Storage 客户端库才能运行以下示例。
C#
Go
Java
Node.js
PHP
Python
Ruby
排查 API 错误
如需详细了解如何对失败的 API 请求进行问题排查,请参阅 Cloud API 错误。
后续步骤
- 查看管理服务帐号和服务帐号密钥的最佳实践
- 详细了解保护服务帐号的最佳做法
- 了解如何向 Google Cloud API 验证身份
- 了解如何以最终用户身份进行身份验证
- 了解如何使用 API 密钥