迁移到 Service Account Credentials API

Service Account Credentials API 用于为 Identity and Access Management (IAM) 服务账号创建短期有效的凭据。您还可以使用此 API 为 JSON Web 令牌 (JWT) 以及包含其他类型令牌的二进制数据的 blob 签名。

IAM API 也包含用于为 JWT 和二进制 blob 签名的方法。自 2020 年 7 月 1 日起，REST API 中以及 IAM API 的所有客户端库中会弃用这些方法。此外，如果您使用 Google Cloud CLI 为 JWT 签名，则可能需要向 JWT 声明集添加新声明。您仍然可以使用已弃用的方法，但它们不支持 HTTP 请求批处理等高级功能。我们建议您改用 Service Account Credentials API。

与 IAM API 相比，Service Account Credentials API 可让您更灵活地设置已签名 JWT 的到期时间。此外，Service Account Credentials API 还添加了多个新的 API 方法，以生成模拟令牌。

本页面介绍了如何更新现有代码以使用 Service Account Credentials API。如果您对这项变更有任何反馈，可以填写反馈表单。您还可以使用电子邮件地址 [e-mail] 来请求支持并提供详细的反馈。

准备工作

• Enable the Service Account Credentials API.

  Enable the API

启用审核日志

如果您希望针对为 JWT 和 blob 签名的请求接收审核日志，则必须为 IAM API 启用数据访问审核日志。为 IAM API 启用数据访问审核日志也会为 Service Account Credentials API 启用这些审核日志。

这两个 API 生成的日志条目之间存在一些显著差异：

审核日志条目之间的差异
方法名称	IAM API 方法名称 (protoPayload.methodName) 是以下名称之一： google.iam.admin.v1.SignBlob google.iam.admin.v1.SignJwt Service Account Credentials API 方法名称是以下名称之一： SignBlob SignJwt
请求类型	IAM API 请求类型 (protoPayload.request.@type) 是以下类型之一： type.googleapis.com/google.iam.admin.v1.SignBlobRequest type.googleapis.com/google.iam.admin.v1.SignJwtRequest Service Account Credentials API 请求类型是以下类型之一： type.googleapis.com/google.iam.credentials.v1.SignBlobRequest type.googleapis.com/google.iam.credentials.v1.SignJwtRequest
服务名称	IAM API 服务名称 (protoPayload.serviceName) 是 iam.googleapis.com。 Service Account Credentials API 服务名称是 iamcredentials.googleapis.com。

数据访问审核日志会计入您每月的免费日志记录数据注入配额。如果超出此配额，您将需要支付日志注入费用。如需了解详情，请参阅 Google Cloud Observability 的价格。

迁移用于为 JWT 签名的代码

本部分介绍了如何将用于为 JWT 签名的代码迁移到 Service Account Credentials API。

使用 REST API 为 JWT 签名

下表展示了使用 IAM REST API 为 JWT 签名与使用 Service Account Credentials API 为 JWT 签名之间的差异。请更新您的代码以反映这些差异：

不同 JWT 签名方式的差异
HTTP 端点	IAM API IAM API 使用以下 HTTP 方法和端点： POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signJwt 在此网址中，project-id 是项目 ID，sa-email 是服务账号的电子邮件地址。 POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt 在此网址中，通配符 - 替换的是项目 ID，sa-email 是服务账号的电子邮件地址。 Service Account Credentials API 使用以下 HTTP 方法和端点。请勿将通配符替换为项目 ID： POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt 在此网址中，sa-email 是服务账号的电子邮件地址。
请求正文	IAM API 请求正文中包含一个 payload 字段。它的值是需要签名的 JWT 载荷。载荷必须是 JSON 对象，序列化为包含 JWT 声明集的字符串。 如果您提供到期时间 (exp) 声明，则它不得长于未来的 12 小时。如果您省略 exp 声明，系统会自动添加该声明并将其设置为未来 1 小时。 Service Account Credentials API 请求正文中包含一个 payload 字段，除到期时间 (exp) 声明的行为以外，与 IAM API 中的该字段完全相同： 如果您提供 exp 声明，则它不得长于未来的 12 小时。 如果您省略 exp 声明，系统不会自动添加该声明。如果您使用已签名的 JWT 向 Google API 或需要 exp 声明的其他 API 进行身份验证，则必须提供该声明。
响应正文	这两个 API 在响应正文中使用相同的字段。

使用客户端库为 JWT 签名

Service Account Credentials API 的客户端库与 IAM API 的客户端库是相互独立的。

如需使用 Service Account Credentials API，请将其客户端库添加到您的应用，然后更新您的代码以使用新的客户端库：

C#

将 C# 版 Service Account Credentials 客户端库添加到您的应用。使用 SignJwt() 方法生成签名。

服务账号的名称必须使用通配符 - 来表示项目 ID：

有效：采用通配符的名称

projects/-/serviceAccounts/[e-mail]

无效：采用项目 ID 的名称

projects/my-project/serviceAccounts/[e-mail]

如果您不再使用 C# 版 IAM 客户端库，可以将其从应用中移除。

Go

将 Go 版 Service Account Credentials 客户端库添加到您的应用。使用 IamCredentialsClient.SignJwt() function 生成签名。

服务账号的名称必须使用通配符 - 来表示项目 ID：

有效：采用通配符的名称

projects/-/serviceAccounts/[e-mail]

无效：采用项目 ID 的名称

projects/my-project/serviceAccounts/[e-mail]

如果您不再使用 Go 版 IAM 客户端库，可以将其从应用中移除。

Java

将 Java 版 Service Account Credentials 客户端库添加到您的应用。使用 IamCredentialsClient#signJwt() 方法生成签名。

服务账号的名称必须使用通配符 - 来表示项目 ID：

有效：采用通配符的名称

projects/-/serviceAccounts/[e-mail]

无效：采用项目 ID 的名称

projects/my-project/serviceAccounts/[e-mail]

如果您不再使用 Java 版 IAM 客户端库，可以将其从应用中移除。

Node.js

将 Node.js 版 Service Account Credentials 客户端库添加到您的应用。使用 signJwt() 方法生成签名。

服务账号的名称必须使用通配符 - 来表示项目 ID：

有效：采用通配符的名称

projects/-/serviceAccounts/[e-mail]

无效：采用项目 ID 的名称

projects/my-project/serviceAccounts/[e-mail]

如果您不再使用 Node.js 版 IAM 客户端库，可以将其从应用中移除。

PHP

将 PHP 版 Service Account Credentials 客户端库添加到您的应用。使用 signJwt() 方法生成签名。

服务账号的名称必须使用通配符 - 来表示项目 ID：

有效：采用通配符的名称

projects/-/serviceAccounts/[e-mail]

无效：采用项目 ID 的名称

projects/my-project/serviceAccounts/[e-mail]

如果您不再使用 PHP 版 IAM 客户端库，可以将其从应用中移除。

Python

将 Python 版 Service Account Credentials 客户端库添加到您的应用。使用 sign_jwt() 方法生成签名。

服务账号的名称必须使用通配符 - 来表示项目 ID：

有效：采用通配符的名称

projects/-/serviceAccounts/[e-mail]

无效：采用项目 ID 的名称

projects/my-project/serviceAccounts/[e-mail]

如果您不使用 iam_credentials 客户端库，可以将其从应用中移除。

Ruby

将 Ruby 版 Service Account Credentials 客户端库添加到您的应用。使用 sign_service_account_jwt() 方法生成签名。

服务账号的名称必须使用通配符 - 来表示项目 ID：

有效：采用通配符的名称

projects/-/serviceAccounts/[e-mail]

无效：采用项目 ID 的名称

projects/my-project/serviceAccounts/[e-mail]

如果您不再使用 Ruby 版 IAM 客户端库，可以将其从应用中移除。

迁移用于为二进制 blob 签名的代码

本部分介绍了如何将用于为二进制 blob 签名的代码迁移到 Service Account Credentials API。

使用 REST API 为二进制 blob 签名

下表展示了使用 IAM REST API 为二进制 blob 签名与使用 Service Account Credentials API 为二进制 blob 签名之间的差异。 请更新您的代码以反映这些差异：

不同二进制 blob 签名方式的差异
HTTP 端点	IAM API IAM API 使用以下 HTTP 方法和端点： POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signBlob 在此网址中，project-id 是项目 ID，sa-email 是服务账号的电子邮件地址。 POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob 在此网址中，通配符 - 替换的是项目 ID，sa-email 是服务账号的电子邮件地址。 Service Account Credentials API 使用以下 HTTP 方法和端点。请勿将通配符替换为项目 ID： POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob 在此网址中，sa-email 是服务账号的电子邮件地址。
请求正文	IAM API 请求正文中包含一个 bytesToSign 字段。它的值是一个 base64 编码的字符串，表示需要签名的二进制 blob。 Service Account Credentials API 请求正文中包含一个 payload 字段，其值与 IAM API 中 bytesToSign 字段的值相同。
响应正文	IAM API 响应正文中包含一个 keyId 字段（标识用于为 blob 签名的密钥）和一个 signature 字段（包含表示签名的 base64 编码的字符串）。 Service Account Credentials API 响应正文中包含一个 keyId 字段（与 IAM API 中的 keyId 字段完全相同）和一个 signedBlob 字段（与 IAM API 中的 signature 字段完全相同）。 注意：signedBlob 字段仅包含签名，不包含原始 blob。

使用客户端库为二进制 blob 签名

Service Account Credentials API 的客户端库与 IAM API 的客户端库是相互独立的。

如需使用 Service Account Credentials API，请将其客户端库添加到您的应用，然后更新您的代码以使用新的客户端库：

C++

如果您使用 Cloud Storage C++ 客户端库为 blob 签名（直接使用或用作其他客户端库的依赖项）：

请升级到 google-cloud-cpp 0.9.0 版或更高版本。

如果您使用其他客户端库为 blob 签名：

请与 [e-mail] 联系以寻求支持。

C#

如果您使用 C# 版 IAM 客户端库（直接使用或用作其他客户端库的依赖项）：

将 C# 版 Service Account Credentials 客户端库添加到您的应用。使用 SignBlob() 方法生成签名。

服务账号的名称必须使用通配符 - 来表示项目 ID：

有效：采用通配符的名称

projects/-/serviceAccounts/[e-mail]

无效：采用项目 ID 的名称

projects/my-project/serviceAccounts/[e-mail]

如果您不再使用 C# 版 IAM 客户端库，可以将其从应用中移除。

如果您使用 Firebase Admin DotNet SDK（直接使用或用作其他客户端库的依赖项）：

请升级到 firebase-admin-dotnet 1.17.1 版或更高版本。

如果您使用其他客户端库为 blob 签名：

请与 [e-mail] 联系以寻求支持。

Go

如果您使用 Go 版 IAM 客户端库（直接使用或用作其他客户端库的依赖项）：

将 Go 版 Service Account Credentials 客户端库添加到您的应用。使用 IamCredentialsClient.SignBlob() function 生成签名。

服务账号的名称必须使用通配符 - 来表示项目 ID：

有效：采用通配符的名称

projects/-/serviceAccounts/[e-mail]

无效：采用项目 ID 的名称

projects/my-project/serviceAccounts/[e-mail]

如果您不再使用 Go 版 IAM 客户端库，可以将其从应用中移除。

如果您使用 Firebase Admin Go SDK（直接使用或用作其他客户端库的依赖项）：

请升级到 firebase-admin-go 4.1.0 版或更高版本。

如果您使用其他客户端库为 blob 签名：

请与 [e-mail] 联系以寻求支持。

Java

如果您使用 Java 版 IAM 客户端库（直接使用或用作其他客户端库的依赖项）：

将 Java 版 Service Account Credentials 客户端库添加到您的应用。使用 IamCredentialsClient#signBlob() 方法生成签名。

服务账号的名称必须使用通配符 - 来表示项目 ID：

有效：采用通配符的名称

projects/-/serviceAccounts/[e-mail]

无效：采用项目 ID 的名称

projects/my-project/serviceAccounts/[e-mail]

如果您不再使用 Java 版 IAM 客户端库，可以将其从应用中移除。

如果您使用 Java 版 Google 身份验证库（直接使用或用作其他客户端库的依赖项）：

请升级到 google-auth-library-java 0.14.0 版或更高版本。

如果您使用 Firebase Admin Java SDK（直接使用或用作其他客户端库的依赖项）：

请升级到 firebase-admin-java 7.0.1 版或更高版本。

如果您使用其他客户端库为 blob 签名：

请与 [e-mail] 联系以寻求支持。

Node.js

如果您使用 Node.js 版 IAM 客户端库（直接使用或用作其他客户端库的依赖项）：

将 Node.js 版 Service Account Credentials 客户端库添加到您的应用。使用 signBlob() 方法生成签名。

服务账号的名称必须使用通配符 - 来表示项目 ID：

有效：采用通配符的名称

projects/-/serviceAccounts/[e-mail]

无效：采用项目 ID 的名称

projects/my-project/serviceAccounts/[e-mail]

如果您不再使用 Node.js 版 IAM 客户端库，可以将其从应用中移除。

如果您使用 Node.js 版 Google 身份验证库（直接使用或用作其他客户端库的依赖项）：

请升级到 google-auth-library-nodejs 6.0.0 版或更高版本。

如果您使用 Firebase Admin Node.js SDK（直接使用或用作其他客户端库的依赖项）：

请升级到 firebase-admin-node 8.13.0 版或更高版本。

如果您使用其他客户端库为 blob 签名：

请与 [e-mail] 联系以寻求支持。

PHP

如果您使用 PHP 版 IAM 客户端库（直接使用或用作其他客户端库的依赖项）：

将 PHP 版 Service Account Credentials 客户端库添加到您的应用。使用 signBlob() 方法生成签名。

服务账号的名称必须使用通配符 - 来表示项目 ID：

有效：采用通配符的名称

projects/-/serviceAccounts/[e-mail]

无效：采用项目 ID 的名称

projects/my-project/serviceAccounts/[e-mail]

如果您不再使用 PHP 版 IAM 客户端库，可以将其从应用中移除。

如果您使用 PHP 版 Google 身份验证库（直接使用或用作其他客户端库的依赖项）：

请升级到 google-auth-library-php 1.5.0 版或更高版本。

如果您使用其他客户端库为 blob 签名：

请与 [e-mail] 联系以寻求支持。

Python

如果您使用 Python 版 IAM 客户端库（直接使用或用作其他客户端库的依赖项）：

将 Python 版 Service Account Credentials 客户端库添加到您的应用。使用 sign_blob() 方法生成签名。

服务账号的名称必须使用通配符 - 来表示项目 ID：

有效：采用通配符的名称

projects/-/serviceAccounts/[e-mail]

无效：采用项目 ID 的名称

projects/my-project/serviceAccounts/[e-mail]

如果您不使用 iam_credentials 客户端库，可以将其从应用中移除。

如果您使用 Python 版 Google 身份验证库（直接使用或用作其他客户端库的依赖项）：

请升级到 google-auth-library-python 1.21.2 版或更高版本。

如果您使用适用于 Cloud Storage 的 Python 客户端（直接使用或用作其他客户端库的依赖项）：

请升级到 python-storage 1.30.0 版或更高版本。

如果您使用其他客户端库为 blob 签名：

请与 [e-mail] 联系以寻求支持。

Ruby

如果您使用 Ruby 版 IAM 客户端库（直接使用或用作其他客户端库的依赖项）：

将 Ruby 版 Service Account Credentials 客户端库添加到您的应用。使用 sign_service_account_blob() 方法生成签名。

服务账号的名称必须使用通配符 - 来表示项目 ID：

有效：采用通配符的名称

projects/-/serviceAccounts/[e-mail]

无效：采用项目 ID 的名称

projects/my-project/serviceAccounts/[e-mail]

如果您不再使用 Ruby 版 IAM 客户端库，可以将其从应用中移除。

如果您使用其他客户端库为 blob 签名：

请与 [e-mail] 联系以寻求支持。

迁移使用 gcloud CLI 的代码

Google Cloud CLI 提供了使用 IAM API 为 JWT 和二进制 blob 签名的命令，包括：

• gcloud beta iam service-accounts sign-jwt
• gcloud iam service-accounts sign-blob

我们将于 2021 年 7 月 1 日当天或之后更新这些命令，使其使用 Service Account Credentials API。此项更改不会影响用于为 blob 签名的命令。

如果您使用 gcloud CLI 来为 JWT 签名，则必须在 2021 年 7 月 1 日之前执行以下步骤：

1. 检查您是否在 JWT 声明集中添加了到期时间 (exp) 声明。

   如果您已添加该声明，则无需进行任何更改。您可以跳过其余步骤。

   如果您未添加该声明，请继续执行下一步。

2. 检查您是否使用已签名的 JWT 向 Google API 或需要 exp 声明的其他 API 进行身份验证。

   如果您省略该声明，IAM API 会自动将其设置为未来 1 小时。相反，Service Account Credentials API 不会自动设置此字段。

   如果您确定不需要 exp 声明，则无需进行任何更改。您可以跳过其余步骤。

   如果您知道自己需要 exp 声明，或不确定是否需要，请继续执行下一步。

3. 更新用于创建 JWT 的代码，以便它将 exp 声明添加到 JWT 声明集中。

   exp 声明最长可以设置为未来的 1 小时。

查看配额

Service Account Credentials API 的配额独立于 IAM API 的配额。如果您获得了更多的配额来使用 IAM API 为 JWT 和 blob 签名，您可能也需要为 Service Account Credentials API 申请增加配额。

注意：大多数 Google Cloud 客户使用默认配额来为 JWT 和 blob 签名。如果您使用的是默认配额，则无需阅读此部分。

对于这两个 API，如需查看您的配额和实际使用量，并在必要时申请增加配额，请执行以下操作：

1. 在 Google Cloud 控制台中，转到配额页面。

   转到“配额”页面

2. 选择一个项目。您可以点击近期的项目，也可以点击选择项目以搜索所有项目。

3. 在表格上方的过滤表文本框中，输入 Sign requests per minute，然后选择显示的值。

4. 在过滤表文本框中，从下拉列表中选择或。

5. 在过滤表文本框中，输入 Generate credentials，然后选择显示的值。

   Google Cloud 控制台会显示过去一分钟内为 JWT 和 blob 签名的 API 的当前使用量；过去 7 天每分钟的峰值使用量；以及您的当前配额（显示在上限列中）。

6. 比较表中每一行的配额，并确保您的 Service Account Credentials API 的配额高于 IAM API 7 天的峰值使用量。

7. 可选：如果您的 Service Account Credentials API 的配额过低，请选中 Service Account Credentials API 对应的复选框，然后点击修改配额。填写表单以申请增加配额。

8. 请对您使用 IAM API 为 JWT 和 blob 签名的每个项目，重复上述步骤。

后续步骤

• 了解如何使用 Service Account Credentials REST API 创建已签名的 JWT 或创建已签名的二进制 blob。
• 详细了解用于 Service Account Credentials API 的 REST API。
• 了解 IAM 的配额和限制。