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 のすべてのクライアント ライブラリで非推奨となりました。2021 年 7 月 1 日までに Service Account Credentials API に移行する必要があります。また、gcloud コマンドライン ツールを使用して JWT に署名する場合、JWT クレームセットに新しいクレームを追加する必要がある場合があります。

IAM API と比べると、Service Account Credentials API は署名付き JWT の有効期限を柔軟に設定できます。Service Account Credentials API では、自己署名トークンでの認証ができません。また、別の自己署名トークンを取得することもできません。そのため、攻撃者が署名付きトークンを取得しても、そのトークンを使用してトークンを更新することはできません。

このページでは、Service Account Credentials API を使用するように既存のコードを更新する方法について説明します。この変更に関するフィードバックについては、フィードバック フォームをご利用いただくか、iam-sign-deprecation-public@google.com までメールでお送りください。

監査ログを有効にする

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 のオペレーション スイートの料金をご覧ください。

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)クレームを指定する場合は、現在の時間から 1 時間以内にする必要があります。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# 用 ervice Account Credentials クライアント ライブラリを追加します。SignJwt() メソッドを使用して署名を生成します。

サービス アカウントの名前には、プロジェクト ID を表すワイルドカード文字 - を使用する必要があります。

有効: ワイルドカード文字を含む名前

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

無効: プロジェクト ID を含む名前

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

リクエストのペイロードに有効期限(exp)クレームが含まれている場合、その期限は現在の時間から 12 時間以内にする必要があります。このクレームを省略すると、クレームは自動的に追加されません署名付き JWT を使用して Google API または exp クレームを必要とする別の API で認証を行う場合は、このクレームを指定する必要があります。

C# 用 IAM クライアント ライブラリが不要になった場合は、アプリケーションから削除できます。

Go

アプリケーションに Go 用 ervice Account Credentials クライアント ライブラリを追加します。IamCredentialsClient.SignJwt() function を使用して署名を生成します。

サービス アカウントの名前には、プロジェクト ID を表すワイルドカード文字 - を使用する必要があります。

有効: ワイルドカード文字を含む名前

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

無効: プロジェクト ID を含む名前

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

リクエストのペイロードに有効期限(exp)クレームが含まれている場合、その期限は現在の時間から 12 時間以内にする必要があります。このクレームを省略すると、クレームは自動的に追加されません署名付き JWT を使用して Google API または exp クレームを必要とする別の API で認証を行う場合は、このクレームを指定する必要があります。

Go 用 IAM クライアント ライブラリが不要になった場合は、アプリケーションから削除できます。

Java

アプリケーションに Java 用 ervice Account Credentials クライアント ライブラリを追加します。IamCredentialsClient#signJwt() メソッドを使用して署名を生成します。

サービス アカウントの名前には、プロジェクト ID を表すワイルドカード文字 - を使用する必要があります。

有効: ワイルドカード文字を含む名前

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

無効: プロジェクト ID を含む名前

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

リクエストのペイロードに有効期限(exp)クレームが含まれている場合、その期限は現在の時間から 12 時間以内にする必要があります。このクレームを省略すると、クレームは自動的に追加されません署名付き JWT を使用して Google API または exp クレームを必要とする別の API で認証を行う場合は、このクレームを指定する必要があります。

Java 用 IAM クライアント ライブラリが不要になった場合は、アプリケーションから削除できます。

Node.js

Node.js 用 Service Account Credentials クライアント ライブラリをアプリケーションに追加します。signJwt() メソッドを使用して署名を生成します。

サービス アカウントの名前には、プロジェクト ID を表すワイルドカード文字 - を使用する必要があります。

有効: ワイルドカード文字を含む名前

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

無効: プロジェクト ID を含む名前

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

リクエストのペイロードに有効期限(exp)クレームが含まれている場合、その期限は現在の時間から 12 時間以内にする必要があります。このクレームを省略すると、クレームは自動的に追加されません署名付き JWT を使用して Google API または exp クレームを必要とする別の API で認証を行う場合は、このクレームを指定する必要があります。

Node.js 用 IAM クライアント ライブラリが不要になった場合は、アプリケーションから IAM クライアント ライブラリを削除できます。

PHP

アプリケーションに PHP 用 ervice Account Credentials クライアント ライブラリを追加します。signJwt() メソッドを使用して署名を生成します。

サービス アカウントの名前には、プロジェクト ID を表すワイルドカード文字 - を使用する必要があります。

有効: ワイルドカード文字を含む名前

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

無効: プロジェクト ID を含む名前

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

リクエストのペイロードに有効期限(exp)クレームが含まれている場合、その期限は現在の時間から 12 時間以内にする必要があります。このクレームを省略すると、クレームは自動的に追加されません署名付き JWT を使用して Google API または exp クレームを必要とする別の API で認証を行う場合は、このクレームを指定する必要があります。

PHP 用 IAM クライアント ライブラリが不要になった場合は、アプリケーションから削除できます。

Python

アプリケーションに Python 用 ervice Account Credentials クライアント ライブラリを追加します。sign_jwt() メソッドを使用して署名を生成します。

サービス アカウントの名前には、プロジェクト ID を表すワイルドカード文字 - を使用する必要があります。

有効: ワイルドカード文字を含む名前

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

無効: プロジェクト ID を含む名前

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

リクエストのペイロードに有効期限(exp)クレームが含まれている場合、その期限は現在の時間から 12 時間以内にする必要があります。このクレームを省略すると、クレームは自動的に追加されません署名付き JWT を使用して Google API または exp クレームを必要とする別の API で認証を行う場合は、このクレームを指定する必要があります。

Python 用 IAM クライアント ライブラリが不要になった場合は、アプリケーションから削除できます。

Ruby

アプリケーションに Ruby 用 ervice Account Credentials クライアント ライブラリを追加します。sign_service_account_jwt() メソッドを使用して署名を生成します。

サービス アカウントの名前には、プロジェクト ID を表すワイルドカード文字 - を使用する必要があります。

有効: ワイルドカード文字を含む名前

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

無効: プロジェクト ID を含む名前

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

リクエストのペイロードに有効期限(exp)クレームが含まれている場合、その期限は現在の時間から 12 時間以内にする必要があります。このクレームを省略すると、クレームは自動的に追加されません署名付き JWT を使用して Google API または exp クレームを必要とする別の API で認証を行う場合は、このクレームを指定する必要があります。

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 フィールドも含まれています。

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

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

Service Account Credentials API を使用する場合は、この API のクライアント ライブラリをアプリケーションに追加し、新しいクライアント ライブラリを使用するようにコードを更新します。

C#

アプリケーションに C# 用 ervice Account Credentials クライアント ライブラリを追加します。SignBlob() メソッドを使用して署名を生成します。

サービス アカウントの名前には、プロジェクト ID を表すワイルドカード文字 - を使用する必要があります。

有効: ワイルドカード文字を含む名前

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

無効: プロジェクト ID を含む名前

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

C# 用 IAM クライアント ライブラリが不要になった場合は、アプリケーションから削除できます。

Go

アプリケーションに Go 用 ervice Account Credentials クライアント ライブラリを追加します。IamCredentialsClient.SignBlob() function を使用して署名を生成します。

サービス アカウントの名前には、プロジェクト ID を表すワイルドカード文字 - を使用する必要があります。

有効: ワイルドカード文字を含む名前

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

無効: プロジェクト ID を含む名前

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Go 用 IAM クライアント ライブラリが不要になった場合は、アプリケーションから削除できます。

Java

アプリケーションに Java 用 ervice Account Credentials クライアント ライブラリを追加します。IamCredentialsClient#signBlob() メソッドを使用して署名を生成します。

サービス アカウントの名前には、プロジェクト ID を表すワイルドカード文字 - を使用する必要があります。

有効: ワイルドカード文字を含む名前

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

無効: プロジェクト ID を含む名前

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Java 用 IAM クライアント ライブラリが不要になった場合は、アプリケーションから削除できます。

Node.js

Node.js 用 Service Account Credentials クライアント ライブラリをアプリケーションに追加します。signBlob() メソッドを使用して署名を生成します。

サービス アカウントの名前には、プロジェクト ID を表すワイルドカード文字 - を使用する必要があります。

有効: ワイルドカード文字を含む名前

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

無効: プロジェクト ID を含む名前

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Node.js 用 IAM クライアント ライブラリが不要になった場合は、アプリケーションから IAM クライアント ライブラリを削除できます。

PHP

アプリケーションに PHP 用 ervice Account Credentials クライアント ライブラリを追加します。signBlob() メソッドを使用して署名を生成します。

サービス アカウントの名前には、プロジェクト ID を表すワイルドカード文字 - を使用する必要があります。

有効: ワイルドカード文字を含む名前

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

無効: プロジェクト ID を含む名前

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

PHP 用 IAM クライアント ライブラリが不要になった場合は、アプリケーションから削除できます。

Python

アプリケーションに Python 用 ervice Account Credentials クライアント ライブラリを追加します。sign_blob() メソッドを使用して署名を生成します。

サービス アカウントの名前には、プロジェクト ID を表すワイルドカード文字 - を使用する必要があります。

有効: ワイルドカード文字を含む名前

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

無効: プロジェクト ID を含む名前

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Python 用 IAM クライアント ライブラリが不要になった場合は、アプリケーションから削除できます。

Ruby

アプリケーションに Ruby 用 ervice Account Credentials クライアント ライブラリを追加します。sign_service_account_blob() メソッドを使用して署名を生成します。

サービス アカウントの名前には、プロジェクト ID を表すワイルドカード文字 - を使用する必要があります。

有効: ワイルドカード文字を含む名前

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

無効: プロジェクト ID を含む名前

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Ruby 用 IAM クライアント ライブラリが不要になった場合は、アプリケーションから削除できます。

gcloud ツールを使用したコードの移行

次のように、gcloud コマンドライン ツールには IAM API を使用して JWT とバイナリ blob に署名するコマンドがあります。

2021 年 7 月 1 日以降、これらのコマンドは Service Account Credentials API を使用するように更新されます。この変更は blob に署名するコマンドには影響しません。

gcloud ツールを使用して 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 の割り当て増加もリクエストする必要があります。

両方の API の割り当てと実際の使用量を確認し、必要に応じて割り当ての増加をリクエストするには、次の操作を行います。

  1. Cloud Console で、[割り当て] ページに移動します。

    [割り当て] ページに移動

  2. プロジェクトを選択します。最近のプロジェクトをクリックするか、[プロジェクトを選択] をクリックしてプロジェクトを検索します。

  3. 表の上にある [表をフィルタリング] テキスト ボックスに「Sign requests per minute」と入力し、表示された値を選択します。

  4. [表をフィルタリング] テキスト ボックスで、プルダウン リストから [OR] を選択します。

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

    Cloud Console には、過去 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 に署名するプロジェクトごとに、上記の手順を繰り返します。

次のステップ