Service Account Credentials API への移行

Service Account Credentials API は、Identity and Access Management（IAM）サービス アカウントに有効期間の短い認証情報を作成します。また、この API を使用して、JSON Web Token（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 この URL で、project-id はプロジェクト ID、sa-email はサービス アカウントのメールアドレスです。 POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt この URL では、プロジェクト ID の代わりにワイルドカード文字 - が使用されています。sa-email はサービス アカウントのメールアドレスです。 Service Account Credentials API 次の HTTP メソッドとエンドポイントを使用します。ワイルドカード文字をプロジェクト ID で置き換えないでください。 POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt この URL で、sa-email はサービス アカウントのメールアドレスです。
リクエストの本文	IAM API リクエストの本文には payload フィールドが含まれます。この値は、署名する JWT ペイロードです。ペイロードは、JWT クレームセットを含む JSON オブジェクトで、文字列としてシリアル化されている必要があります。 有効期限（exp）クレームを指定する場合は、現在の時刻から 12 時間以内にする必要があります。exp クレームを省略すると、クレームが自動的に追加され、現在の時間から 1 時間に設定されます。 Service Account Credentials API リクエストの本文には IAM API と同じ payload フィールドが含まれます。ただし、有効期限（exp）クレームの動作は異なります。 exp クレームを指定する場合は、現在の時間から 12 時間以内にする必要があります。 exp クレームを省略した場合、クレームは自動的に追加されません。署名付き JWT を使用して Google API または exp クレームを必要とする別の API で認証を行う場合は、このクレームを指定する必要があります。
レスポンスの本文	どちらの API も、レスポンスの本文で同じフィールドが使用されます。

クライアント ライブラリを使用した JWT の署名

Service Account Credentials API のクライアント ライブラリは、IAM API のクライアント ライブラリとは別のものです。

Service Account Credentials API を使用する場合は、この 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 この URL で、project-id はプロジェクト ID、sa-email はサービス アカウントのメールアドレスです。 POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob この URL では、プロジェクト ID の代わりにワイルドカード文字 - が使用されています。sa-email はサービス アカウントのメールアドレスです。 Service Account Credentials API 次の HTTP メソッドとエンドポイントを使用します。ワイルドカード文字をプロジェクト ID で置き換えないでください。 POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob この URL で、sa-email はサービス アカウントのメールアドレスです。
リクエストの本文	IAM API リクエストの本文には bytesToSign フィールドが含まれます。この値は、署名するバイナリ blob を表す Base64 エンコード文字列です。 Service Account Credentials API リクエストの本文には、IAM API の bytesToSign フィールドと同じ値の payload フィールドが含まれます。
レスポンスの本文	IAM API レスポンスの本文には、blob の署名に使用された鍵を識別する keyId フィールドと、署名を表す Base64 エンコード文字列を含む signature フィールドが含まれています。 Service Account Credentials API レスポンスの本文には、IAM API の keyId フィールドと同じ keyId フィールドが含まれています。また、IAM API の signature フィールドと同じ signedBlob フィールドも含まれています。 注: signedBlob フィールドには、元の blob ではなく、署名のみが含まれます。

クライアント ライブラリを使用したバイナリ blob の署名

Service Account Credentials API のクライアント ライブラリは、IAM API のクライアント ライブラリとは別のものです。

Service Account Credentials API を使用する場合は、この 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. [表をフィルタリング] テキスト ボックスで、プルダウン リストから [OR] を選択します。

5. [表をフィルタリング] テキスト ボックスに「Generate credentials」と入力し、表示された値を選択します。

   Google Cloud コンソールには、過去 1 分間の JWT と blob の署名に対する現在の使用状況と、過去 7 日間の 1 分あたりのピーク使用量が表示されます。また、[上限] 列には現在の割り当てが表示されます。

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 の割り当てと上限を理解する。