本页面介绍了如何使用 Google Cloud Console、gcloud
命令行工具、Identity and Access Management API 或某种 Google Cloud 客户端库来创建和管理服务帐号密钥。
本指南的前提条件
所需权限
若要允许用户管理服务帐号密钥,请授予 Service Account Key Admin 角色 (roles/iam.serviceAccountKeyAdmin
)。如需了解详情,请参阅服务帐号角色。
IAM 基本角色还包含管理服务帐号密钥的权限。您不应在生产环境中授予基本角色,但可以在开发或测试环境中授予这些角色。
创建服务帐号密钥
如要在 Google Cloud 之外(例如在其他平台上或在本地)使用服务帐号,您必须首先确定服务帐号的身份。为确保安全地实现此目标,您可以使用公钥/私钥对。
您可以使用 Cloud Console、gcloud
工具、serviceAccounts.keys.create()
方法或某种客户端库创建服务帐号密钥。
一个服务帐号最多可以有 10 个密钥。
在下面的示例中,sa-name
是您的服务帐号的名称,而 project-id
是您的 Google Cloud 项目的 ID。您可以从 Cloud Console 中的服务帐号页面检索 sa-name@project-id.iam.gserviceaccount.com
字符串。
控制台
在 Cloud Console 中,转到服务帐号页面。
点击选择项目,然后选择一个项目并点击打开。
找到您要为其创建密钥的服务帐号对应的行。在该行中,点击
,然后点击创建密钥。 按钮选择一种密钥类型,然后点击创建。
点击创建即会下载服务帐号密钥文件。下载密钥文件后,您无法再次下载。
务必要安全存储密钥文件,因为它能够以服务帐号的身份进行身份验证。您可以根据需要移动并重命名此文件。
gcloud
执行 gcloud iam service-accounts keys create
命令来创建服务帐号密钥。
命令:
gcloud iam service-accounts keys create ~/key.json \ --iam-account sa-name@project-id.iam.gserviceaccount.com
输出:
created key [e44da1202f82f8f4bdd9d92bc412d1d8a837fa83] of type [json] as [/usr/home/username/key.json] for [sa-name@project-id.iam.gserviceaccount.com]
现在,服务帐号密钥文件已下载到您的机器上。下载密钥文件后,您无法再次下载。
务必要安全存储密钥文件,因为它能够以服务帐号的身份进行身份验证。您可以根据需要移动并重命名此文件。
REST
projects.serviceAccounts.keys.create
方法可为服务帐号创建密钥。
在使用下面的请求数据之前,请先进行以下替换:
project-id
:您的 Google Cloud 项目 ID。sa-name
:您要为其创建密钥的服务帐号的名称。private-key-type
:可选。私钥的输出格式。默认值为TYPE_GOOGLE_CREDENTIALS_FILE
,它是一个采用 base64 编码的 JSON 密钥文件。如需查看所有可能值的列表,请参阅ServiceAccountPrivateKeyType
参考文档。key-algorithm
:可选。用于密钥的密钥算法。默认值(随时可能更改)为 2048 位 RSA 密钥。如需查看所有可能值的列表,请参阅ServiceAccountKeyAlgorithm
参考文档。
HTTP 方法和网址:
POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com/keys
请求 JSON 正文:
{ "privateKeyType": "private-key-type", "keyAlgorithm": "key-algorithm" }
如需发送您的请求,请展开以下选项之一:
该响应包含您的服务帐号的密钥,例如:
{ "name":"projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/90c48f61c65cd56224a12ab18e6ee9ca9c3aee7c", "privateKeyType": "TYPE_GOOGLE_CREDENTIALS_FILE", "privateKeyData":"MIIJqAIB . . .", "validAfterTime": "2020-05-17T18:48:27Z", "validBeforeTime": "9999-12-31T23:59:59Z", "keyAlgorithm": "KEY_ALG_RSA_2048", "keyOrigin": "GOOGLE_PROVIDED", "keyType": "USER_MANAGED" }
务必要安全存储密钥数据,因为它能够以服务帐号的身份进行身份验证。
C#
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 C# 设置说明进行操作。如需了解详情,请参阅 IAM C# API 参考文档。
Go
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 IAM Go API 参考文档。
Java
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Java 设置说明进行操作。如需了解详情,请参阅 IAM Java API 参考文档。
Python
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 IAM Python API 参考文档。
请注意,返回的 privateKeyData
是 TYPE_GOOGLE_CREDENTIALS_FILE
值(JSON 或 P12 密钥/凭据)的 base64 编码字符串表示形式。
创建密钥时,系统会生成新的公钥/私钥对并将其下载到您的计算机,它充当私钥的唯一副本。您负责安全地存储私钥。请记下它的位置并确保您的应用可以访问该密钥,应用需要该密钥来调用需经过身份验证才可调用的 API。
密钥的格式可能因其生成方式而异。使用 Cloud Console 或 gcloud
命令行工具创建的密钥如下所示:
{ "type": "service_account", "project_id": "project-id", "private_key_id": "key-id", "private_key": "-----BEGIN PRIVATE KEY-----\nprivate-key\n-----END PRIVATE KEY-----\n", "client_email": "service-account-email", "client_id": "client-id", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://accounts.google.com/o/oauth2/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/service-account-email" }
而使用 REST API 或客户端库生成的密钥如下所示:
{ "name": "projects/project-id/serviceAccounts/service-account-email/keys/key-id", "privateKeyType": "TYPE_GOOGLE_CREDENTIALS_FILE", "privateKeyData": "private-key", "validAfterTime": "date", "validBeforeTime": "date", "keyAlgorithm": "KEY_ALG_RSA_2048" }
请再次注意,返回的 privateKeyData
是 TYPE_GOOGLE_CREDENTIALS_FILE
值(JSON 或 P12 密钥/凭据)的 base64 编码字符串表示形式。 您可以将采用 base64 解码的 privateKeyData
存储在具有相应扩展名(.p12
或 .json
)的文件中,并将其用作客户端库的输入或 gcloud auth activate-service-account
命令的输入。
由于每种方法产生的格式有所不同,因此,最简单的方法是按照您计划在日后进行 API 调用时使用的相同方法生成密钥。例如,如果您要使用 gcloud
,则也请使用 gcloud
生成密钥。若要将通过某种方法生成的密钥与另外的方法搭配使用(例如将 REST 生成的密钥与 gcloud
搭配使用),您需要修改密钥以匹配相应格式。
Google 将确保所有服务帐号的所有公钥都可供任何人公开访问,并可用于验证使用私钥创建的签名。可通过以下网址公开访问公钥:
- x.509 证书:https://www.googleapis.com/service_accounts/v1/metadata/x509/sa-name@project-id.iam.gserviceaccount.com
- JSON Web 密钥 (JWK):https://www.googleapis.com/service_accounts/v1/jwk/sa-name@project-id.iam.gserviceaccount.com
- 原始端点:https://www.googleapis.com/service_accounts/v1/metadata/raw/sa-name@project-id.iam.gserviceaccount.com
列出服务帐号密钥
您可以使用 Cloud Console、gcloud
工具,serviceAccount.keys.list()
方法或某种 客户端库列出服务帐号的密钥。
serviceAccount.keys.list()
方法通常用于审核服务帐号和密钥,或者构建用于管理服务帐号的自定义工具。
要了解您的密钥属于哪个项目,您可以以 JSON 文件的格式下载该密钥并查看该文件。
您可能会发现有些列出的密钥并不是由您创建的。这些密钥是供 Google Cloud 服务(例如 App Engine 和 Compute Engine)使用且由 Google Cloud 管理的密钥。如需详细了解用户管理的密钥和 Google Cloud 管理的密钥之间的差异,请参阅了解服务帐号。
控制台
在 Cloud Console 中,转到服务帐号页面。
点击选择项目,然后选择一个项目并点击打开。控制台会列出项目的所有服务帐号及其对应的密钥。
gcloud
执行 gcloud iam service-accounts keys list
命令来列出服务帐号密钥。
命令:
gcloud iam service-accounts keys list \ --iam-account sa-name@project-id.iam.gserviceaccount.com
输出:
KEY_ID | CREATED_AT | EXPIRES_AT |
8e6e3936d7024646f8ceb39792006c07f4a9760c | 2021-01-01T21:01:42Z | 9999-12-31T23:59:59Z |
937c98f870f5c8db970af527aa3c12fd88b1c20a | 2021-01-01T20:55:40Z | 9999-12-31T23:59:59Z |
REST
projects.serviceAccounts.keys.list
方法可列出服务帐号的所有服务帐号密钥。
在使用下面的请求数据之前,请先进行以下替换:
project-id
:您的 Google Cloud 项目 ID。sa-name
:您要列出其密钥的服务帐号的名称。key-types
:可选。您想要在响应中包含的密钥类型的英文逗号分隔列表。密钥类型会指出密钥是由用户管理 (USER_MANAGED
) 还是由系统管理 (SYSTEM_MANAGED
)。如果留空,则返回所有密钥。
HTTP 方法和网址:
GET https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com/keys?keyTypes=key-types
如需发送您的请求,请展开以下选项之一:
您应该会收到类似以下内容的 JSON 响应:
{ "keys": [ { "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/90c48f61c65cd56224a12ab18e6ee9ca9c3aee7c", "validAfterTime": "2020-03-04T17:39:47Z", "validBeforeTime": "9999-12-31T23:59:59Z", "keyAlgorithm": "KEY_ALG_RSA_2048", "keyOrigin": "GOOGLE_PROVIDED", "keyType": "USER_MANAGED" }, { "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/e5e3800831ac1adc8a5849da7d827b4724b1fce8", "validAfterTime": "2020-03-31T23:50:09Z", "validBeforeTime": "9999-12-31T23:59:59Z", "keyAlgorithm": "KEY_ALG_RSA_2048", "keyOrigin": "GOOGLE_PROVIDED", "keyType": "USER_MANAGED" }, { "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/b97699f042b8eee6a846f4f96259fbcd13e2682e", "validAfterTime": "2020-05-17T18:58:13Z", "validBeforeTime": "9999-12-31T23:59:59Z", "keyAlgorithm": "KEY_ALG_RSA_2048", "keyOrigin": "GOOGLE_PROVIDED", "keyType": "USER_MANAGED" } ] }
C#
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 C# 设置说明进行操作。如需了解详情,请参阅 IAM C# API 参考文档。
Go
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 IAM Go API 参考文档。
Java
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Java 设置说明进行操作。如需了解详情,请参阅 IAM Java API 参考文档。
Python
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 IAM Python API 参考文档。
获取服务帐号密钥
首次创建服务帐号密钥时,您只能获取该密钥的私钥数据。
您可以使用 projects.serviceAccounts.keys.get()
REST API 方法获取密钥的基本信息,例如密钥的 ID、算法和公钥数据。系统不支持使用 Cloud Console 或 gcloud
命令行工具来执行此操作。
上传服务帐号的公钥
您可以将用户管理的密钥对的公钥部分上传到服务帐号。上传公钥后,该公钥将与服务帐号永久关联,其使用方式与任何其他用户管理的服务帐号密钥相同。如需停用为项目上传密钥的功能,请参阅限制服务帐号密钥上传。
如果您选择使用用户管理的密钥对,而不是 Google 管理的密钥对,请务必保留该密钥对并定期进行轮替。
您上传的密钥必须是封装在 X.509 v3 证书中并以 base64 编码的 RSA 公钥。您可以使用 OpenSSL 等工具生成此格式的密钥和证书。例如,以下命令会生成 2048 位 RSA 密钥对,并将公钥封装在有效期为 365 天的自签名证书中:
openssl req -x509 -nodes -newkey rsa:2048 -days 365 \
-keyout /path/to/private_key.pem \
-out /path/to/public_key.pem \
-subj "/CN=unused"
然后,您可以上传 public_key.pem
文件作为服务帐号的公钥。
gcloud
执行 gcloud iam service-accounts keys upload
命令来上传用于签署服务帐号密钥的公钥。
命令:
gcloud iam service-accounts keys upload /path/to/public_key.pem \ --iam-account sa-name@project-id.iam.gserviceaccount.com
输出包含所上传密钥的唯一标识符:
Name: projects/project-id/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com/keys/c7b74879da78e4cdcbe7e1bf5e129375c0bfa8d0
如需确定该命令是否成功运行,请执行 gcloud iam service-accounts keys list
命令:
gcloud iam service-accounts keys list \ --iam-account sa-name@project-id.iam.gserviceaccount.com
输出将包含创建密钥后返回的相同唯一标识符:
KEY_ID | CREATED_AT | EXPIRES_AT |
c7b74879da78e4cdcbe7e1bf5e129375c0bfa8d0 | 2019-06-26T21:01:42Z | 9999-12-31T23:59:59Z |
REST
projects.serviceAccounts.keys.upload
方法可上传用户管理的密钥对中的公钥,并将此公钥添加到服务帐号。
在使用下面的请求数据之前,请先进行以下替换:
project-id
:您的 Google Cloud 项目 ID。sa-name
:要与密钥关联的服务帐号的名称。public-key-data
:密钥对的公钥数据。必须是封装在 X.509 v3 证书中的 RSA 公钥。使用 base64 对公钥数据进行编码,包括第一行-----BEGIN CERTIFICATE-----
和最后一行-----END CERTIFICATE-----
。
HTTP 方法和网址:
POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com/keys:upload
请求 JSON 正文:
{ "publicKeyData": "public-key-data" }
如需发送您的请求,请展开以下选项之一:
您应会收到如下所示的 JSON 响应:
{ "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/c7b74879da78e4cdcbe7e1bf5e129375c0bfa8d0", "validAfterTime": "2020-05-17T19:31:19Z", "validBeforeTime": "2021-05-17T19:31:19Z", "keyAlgorithm": "KEY_ALG_RSA_2048", "keyOrigin": "USER_PROVIDED", "keyType": "USER_MANAGED" }
删除服务帐号密钥
您可以使用 Cloud Console、gcloud
工具、serviceAccount.keys.delete()
方法或某种客户端库删除服务帐号密钥。
在您删除密钥后,您的应用将无法再使用该密钥访问 Google Cloud 资源。安全性方面的最佳做法是定期轮替您的服务帐号密钥。要轮替密钥,只需创建新密钥,让应用改用新密钥,然后删除旧密钥即可。您可以结合使用 serviceAccount.keys.create()
方法和 serviceAccount.keys.delete()
方法自动执行轮替。
控制台
在 Cloud Console 中,转到服务帐号页面。
点击选择项目,然后选择一个项目并点击打开。控制台会列出项目的所有服务帐号及其对应的密钥。
找到您要为其创建密钥的服务帐号对应的行。在该行中,点击
,然后点击修改。 按钮从密钥列表中,针对您想删除的每个密钥点击删除
。
gcloud
执行 gcloud iam service-accounts keys delete
命令来删除服务帐号密钥。
命令:
gcloud iam service-accounts keys delete key-id \ --iam-account sa-name@project-id.iam.gserviceaccount.com
输出:
Deleted key [8e6e3936d7024646f8ceb39792006c07f4a9760c] for service account [sa-name@project-id.iam.gserviceaccount.com]
REST
projects.serviceAccounts.keys.delete
方法可删除服务帐号密钥。
在使用下面的请求数据之前,请先进行以下替换:
project-id
:您的 Google Cloud 项目 ID。sa-name
:您要删除其密钥的服务帐号的名称。key-id
:您要删除的密钥的 ID。
HTTP 方法和网址:
DELETE https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com/keys/key-id
如需发送您的请求,请展开以下选项之一:
您应该会收到类似以下内容的 JSON 响应:
{ }
C#
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 C# 设置说明进行操作。如需了解详情,请参阅 IAM C# API 参考文档。
Go
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 IAM Go API 参考文档。
Java
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Java 设置说明进行操作。如需了解详情,请参阅 IAM Java API 参考文档。
Python
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 IAM Python API 参考文档。
亲自尝试
如果您是 Google Cloud 新手,请创建一个帐号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金,用于运行、测试和部署工作负载。
免费开始使用