遷移至 Service Account Credentials API

服務帳戶憑證 API 會為 Identity and Access Management (IAM) 服務帳戶建立短期憑證。您也可以使用這項 API 簽署 JSON Web Token (JWT)，以及包含其他類型權杖的二進位資料 blob。

IAM API 也包含簽署 JWT 和二進位大型物件的方法。自 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.

  Roles required to enable APIs

  To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

  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 欄位，與 IAM API 相同，但到期時間 (exp) 聲明行為除外： 如果提供 exp 聲明，時間必須在12 小時內。 如果省略 exp 聲明，系統不會自動新增。如果您使用已簽署的 JWT 向 Google API 或其他需要 exp 聲明的 API 進行驗證，就必須提供這項聲明。
回應主體	這兩個 API 在回應本文中使用相同的欄位。

使用用戶端程式庫簽署 JWT

Service Account Credentials API 的用戶端程式庫與 IAM API 的用戶端程式庫不同。

如要使用 Service Account Credentials API，請將其用戶端程式庫新增至應用程式，並更新程式碼以使用新的用戶端程式庫：

C#

將 C#適用的服務帳戶憑證用戶端程式庫新增至應用程式。使用 SignJwt() 方法產生簽名。

服務帳戶名稱必須使用萬用字元 - 代表專案 ID：

有效：含有萬用字元的名稱

projects/-/serviceAccounts/[e-mail]

無效：含有專案 ID 的名稱

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

如果您不再使用 C#的 IAM 用戶端程式庫，可以從應用程式中移除。

Go

將 Go 專用的服務帳戶憑證用戶端程式庫新增至應用程式。使用 IamCredentialsClient.SignJwt() function 產生簽章。

服務帳戶名稱必須使用萬用字元 - 代表專案 ID：

有效：含有萬用字元的名稱

projects/-/serviceAccounts/[e-mail]

無效：含有專案 ID 的名稱

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

如果您不再使用 Go 適用的 IAM 用戶端程式庫，可以從應用程式中移除。

Java

將 Java 適用的服務帳戶憑證用戶端程式庫新增至應用程式。使用 IamCredentialsClient#signJwt() 方法產生簽名。

服務帳戶名稱必須使用萬用字元 - 代表專案 ID：

有效：含有萬用字元的名稱

projects/-/serviceAccounts/[e-mail]

無效：含有專案 ID 的名稱

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

如果您不再使用 Java 適用的 IAM 用戶端程式庫，可以從應用程式中移除。

Node.js

在應用程式中新增 Node.js 適用的服務帳戶憑證用戶端程式庫。使用 signJwt() 方法產生簽名。

服務帳戶名稱必須使用萬用字元 - 代表專案 ID：

有效：含有萬用字元的名稱

projects/-/serviceAccounts/[e-mail]

無效：含有專案 ID 的名稱

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

如果您不再使用 Node.js 適用的 IAM 用戶端程式庫，可以從應用程式中移除。

PHP

將 PHP 專用的服務帳戶憑證用戶端程式庫新增至應用程式。使用 signJwt() 方法產生簽名。

服務帳戶名稱必須使用萬用字元 - 代表專案 ID：

有效：含有萬用字元的名稱

projects/-/serviceAccounts/[e-mail]

無效：含有專案 ID 的名稱

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

如果您不再使用 PHP 適用的 IAM 用戶端程式庫，可以從應用程式中移除。

Python

將 Python 適用的服務帳戶憑證用戶端程式庫新增至應用程式。使用 sign_jwt() 方法產生簽名。

服務帳戶名稱必須使用萬用字元 - 代表專案 ID：

有效：含有萬用字元的名稱

projects/-/serviceAccounts/[e-mail]

無效：含有專案 ID 的名稱

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

如果您不再使用iam_credentials用戶端程式庫，可以從應用程式中移除。

Ruby

將 Ruby 適用的服務帳戶憑證用戶端程式庫新增至應用程式。使用 sign_service_account_jwt() 方法產生簽名。

服務帳戶名稱必須使用萬用字元 - 代表專案 ID：

有效：含有萬用字元的名稱

projects/-/serviceAccounts/[e-mail]

無效：含有專案 ID 的名稱

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

如果您不再使用 Ruby 適用的 IAM 用戶端程式庫，可以從應用程式中移除該程式庫。

遷移用於簽署二進位大型物件的程式碼

本節說明如何將簽署二進位 BLOB 的程式碼遷移至 Service Account Credentials API。

使用 REST API 簽署二進位大型物件

下表列出使用 IAM REST API 簽署二進位大型物件，以及使用服務帳戶憑證 API 簽署二進位大型物件的差異。請更新程式碼，以反映這些差異：

簽署二進位 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 編碼的字串，代表要簽署的二進位大型物件。 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，無論是直接使用，還是做為其他用戶端程式庫的依附元件：

升級至 0.9.0 以上版本的 google-cloud-cpp。

如果您使用其他用戶端程式庫簽署 Blob：

如需支援，請與 [e-mail] 聯絡。

C#

如果您使用 C#的 IAM 用戶端程式庫，無論是直接使用，還是做為其他用戶端程式庫的依附元件：

將 C#適用的服務帳戶憑證用戶端程式庫新增至應用程式。使用 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 專用的服務帳戶憑證用戶端程式庫新增至應用程式。使用 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 適用的服務帳戶憑證用戶端程式庫新增至應用程式。使用 IamCredentialsClient#signBlob() 方法產生簽名。

服務帳戶名稱必須使用萬用字元 - 代表專案 ID：

有效：含有萬用字元的名稱

projects/-/serviceAccounts/[e-mail]

無效：含有專案 ID 的名稱

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

如果您不再使用 Java 適用的 IAM 用戶端程式庫，可以從應用程式中移除。

如果您使用 Java 適用的 Google Auth 程式庫 (直接使用或做為其他用戶端程式庫的依附元件)：

升級至 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 適用的服務帳戶憑證用戶端程式庫。使用 signBlob() 方法產生簽名。

服務帳戶名稱必須使用萬用字元 - 代表專案 ID：

有效：含有萬用字元的名稱

projects/-/serviceAccounts/[e-mail]

無效：含有專案 ID 的名稱

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

如果您不再使用 Node.js 適用的 IAM 用戶端程式庫，可以從應用程式中移除。

如果您使用 Node.js 適用的 Google Auth 程式庫 (直接使用或做為其他用戶端程式庫的依附元件)：

升級至 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 專用的服務帳戶憑證用戶端程式庫新增至應用程式。使用 signBlob() 方法產生簽名。

服務帳戶名稱必須使用萬用字元 - 代表專案 ID：

有效：含有萬用字元的名稱

projects/-/serviceAccounts/[e-mail]

無效：含有專案 ID 的名稱

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

如果您不再使用 PHP 適用的 IAM 用戶端程式庫，可以從應用程式中移除。

如果您使用 PHP 適用的 Google Auth 程式庫，無論是直接使用，還是做為其他用戶端程式庫的依附元件：

升級至 google-auth-library-php 1.5.0 以上版本。

如果您使用其他用戶端程式庫簽署 Blob：

如需支援，請與 [e-mail] 聯絡。

Python

如果您使用 Python 適用的 IAM 用戶端程式庫 (直接使用或做為其他用戶端程式庫的依附元件)：

將 Python 適用的服務帳戶憑證用戶端程式庫新增至應用程式。使用 sign_blob() 方法產生簽名。

服務帳戶名稱必須使用萬用字元 - 代表專案 ID：

有效：含有萬用字元的名稱

projects/-/serviceAccounts/[e-mail]

無效：含有專案 ID 的名稱

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

如果您不再使用iam_credentials用戶端程式庫，可以從應用程式中移除。

如果您使用 Python 適用的 Google Auth 程式庫，無論是直接使用，還是做為其他用戶端程式庫的依附元件：

升級至 google-auth-library-python 1.21.2 以上版本。

如果您使用 Cloud Storage 的 Python 用戶端，無論是直接使用，還是做為其他用戶端程式庫的依附元件：

升級至 python-storage 1.30.0 以上版本。

如果您使用其他用戶端程式庫簽署 Blob：

如需支援，請與 [e-mail] 聯絡。

Ruby

如果您使用 Ruby 適用的 IAM 用戶端程式庫 (直接使用或做為其他用戶端程式庫的依附元件)：

將 Ruby 適用的服務帳戶憑證用戶端程式庫新增至應用程式。使用 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 和二進位大型物件的指令，包括：

• 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，可能也需要申請提高服務帳戶憑證 API 的配額。

注意： 大多數 Google Cloud 客戶都使用簽署 JWT 和 Blob 的預設配額。如果您使用預設配額，則不需要閱讀本節。

如要查看這兩個 API 的配額和實際用量，並視需要申請增加配額，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Quotas」(配額) 頁面。

   前往配額頁面

2. 選取專案。您可以按一下最近的專案，也可以按一下「選取專案」搜尋所有專案。

3. 在表格上方的「Filter table」(篩選表格) 文字方塊中輸入 Sign requests per minute，然後選取顯示的值。

4. 在「Filter table」(篩選資料表) 文字方塊中，從下拉式清單選取「OR」(或)。

5. 在「篩選表格」文字方塊中輸入 Generate credentials，然後選取顯示的值。

   Google Cloud 控制台會顯示過去一分鐘內簽署 JWT 和 Blob 的目前用量、過去 7 天內每分鐘的最高用量，以及「限制」欄中顯示的目前配額。

6. 比較表格中各列的配額，並確認服務帳戶憑證 API 的配額高於 IAM API 的 7 天尖峰用量。

7. 選用步驟：如果服務帳戶憑證 API 的配額過低，請選取服務帳戶憑證 API 的核取方塊，然後按一下「編輯配額」。填寫表單，要求提高配額。

8. 針對每個使用 IAM API 簽署 JWT 和 Blob 的專案，重複執行這些步驟。

後續步驟

• 瞭解如何使用 Service Account Credentials REST API 建立已簽署的 JWT 或建立已簽署的二進位大型物件。
• 取得有關服務帳戶憑證 API 的 REST API 詳細資料。
• 瞭解 IAM 的配額與限制。