有効期間が短いサービスアカウント認証情報の作成

このページでは、サービスアカウント ID を使用するための有効期間が短いサービスアカウント認証情報を作成する方法を説明します。

サービスアカウントは、有効期間が短い認証情報を使用して、Google Cloud Platform API やその他の Google 以外の API への呼び出しを認証できます。有効期間が短い認証情報の存続期間は限られており、その期間は数時間未満です。有効期間が短いサービスアカウント認証情報は、信頼できるサービスアカウントのリソースへのアクセスを制限する必要がある場合に便利です。また、サービスアカウントキーなどの有効期間が長い認証情報を使用する場合と比較してリスクを軽減できます。

サポートされている認証情報タイプには、OAuth 2.0 アクセストークン、OpenID Connect ID トークン、自己署名 JSON ウェブトークン（JWT）、自己署名バイナリオブジェクト（BLOB）などがあります。OAuth 2.0 アクセストークンと OpenID Connect（OIDC）ID トークンが、特によく使用されるタイプの認証情報です。いくつかのサンプル事例としては、次のようなものがあります。

OAuth 2.0 アクセストークン: An OAuth 2.0 アクセストークンは、Google Cloud Platform API に対してサービスアカウントの ID を認証する場合に便利です。次の使用例を考えてみます。プロジェクトの昇格した権限を取得するために、サービス管理者はサービスアカウントを使用し、そのサービスアカウントに属する OAuth 2.0 アクセストークンを作成することで GCP API を呼び出します。トークンの有効期間は短いため、昇格した権限は一時的なものです。これは特に、本番環境で緊急事態が発生し、サービス管理者がデバッグのために有効期間が短い昇格した承認を必要とする場合に便利です。
OIDC ID トークン: OIDC ID トークンは、OpenID Connect を認可するサービスに対するサービスアカウント ID の認証に便利です。次の使用例を考えてみます。サービスアカウントに属する OIDC ID トークンを作成すると、GCP で実行されているサービスは、サードパーティクラウドプロバイダにデプロイされた別のサービス（データパイプラインジョブなど）から認証を受けることができます。ターゲットサービスが OIDC で構成されている場合、認証は成功します。

始める前に

Cloud IAM サービスアカウントについて理解する
まだ起動していない場合は、クイックスタートの手順に従って請求と Cloud IAM API を有効にします。

権限を制限したサービスアカウントの作成

開始するには、新しいサービスアカウントを作成します。

必要な権限の付与

呼び出し元がサービスアカウントの有効期間が短い認証情報を作成するには、2 つの異なるフローがあります。各フローには適切な権限が必要です。

直接リクエスト: 呼び出し元は Google アカウントまたはサービスアカウントのいずれかとして認証され、有効期間が短い認証情報の作成を直接リクエストします。このフローには、呼び出し元と認証情報が作成されるサービスアカウントの 2 つの ID が含まれます。
委任リクエスト: 呼び出し元は直接リクエストフローの場合と同じように Google アカウントまたはサービスアカウントのいずれかとして認証されますが、リクエストは委任チェーン内の 1 つ以上のサービスアカウントに委任されます。このフローでは、複数のサービスアカウントが、元の呼び出し元と認証情報が作成されるサービスアカウントの間の仲介役として機能します。委任チェーン内の各サービスアカウントには、リクエストを渡すための権限が必要です。

このフローが役立つのは、プロジェクト内に権限が制限された複数のサービスアカウントが何層にも重なっていて、各サービスアカウントが、特定のリソースに対して特定のファンクションや限定されたファンクションを行うように構成されている場合です。たとえば、あるサービスアカウントには Cloud Storage のリソースに対する権限のみが付与され、別のサービスアカウントには Compute Engine のリソースに対する権限のみが付与されている、といった状況です。サービスアカウント同士でリクエストの委任が正しく行われるようにするには、各サービスアカウントが委任チェーンの一覧に含まれていなければなりません。

直接リクエストの権限

前述のように、直接リクエストには、呼び出し元と認証情報が作成されるサービスアカウントの 2 つの ID のみが含まれます。このフローでは、次の ID があるとします。

サービスアカウント 1（SA-1）: 有効期間が短い認証情報のリクエストを発行する呼び出し元。
サービスアカウント 2（SA-2）: 認証情報が作成される権限を制限したアカウント。

SA-1 に有効期間が短い認証情報を作成するための権限を付与するには、SA-2 のサービスアカウントトークン作成者の役割（roles/iam.serviceAccountTokenCreator）を付与します。これは、ID ではなくリソースのように扱われるサービスアカウントの例です。SA-1 に、SA-2 の認証情報を発行するための権限が付与されている必要があります。ID またはリソースとしてサービスアカウントを扱う方法の詳細については、サービスアカウント権限をご覧ください。

次の手順では REST API で必要な権限を付与しますが、GCP Console や gcloud コマンドラインツールを使用することもできます。

API

まず、SA-2 の Cloud IAM ポリシーを取得します。詳細については、serviceAccounts.getIamPolicy() リファレンスをご覧ください。

以下のコードスニペットで SA-2@PROJECT- ID.iam.gserviceaccount.com は SA-2 を表し、SA-1@PROJECT-ID.iam.gserviceaccount.com は SA-1（有効期間が短い認証情報をリクエストする呼び出し元）を表しています。

この API への各リクエストでは、ハイフン（.../projects/-/serviceAccounts...）が URL の最初の部分のプロジェクト ID に対するワイルドカードとして使用されます。

リクエスト:

POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/SA-2@PROJECT-ID.iam.gserviceaccount.com:getIamPolicy

レスポンス:

{
  "etag": "BwUqLaVeua8=",
  "bindings": [
    {
      "role": "roles/iam.serviceAccountUser",
      "members": [
          "user:alice@gmail.com"
      ]
    }
  ]
}

役割をサービスアカウントにまだ割り当てていない場合、レスポンスには 1 つの etag 値だけが含まれます。

{
  "etag": "ACAB"
}

上記の手順で取得した etag 値は、それが BwUqLaVeua8= か ACAB かを問わず、次の手順に含める必要があります。次に、SA-1 に、サービスアカウントトークン作成者の役割（roles/iam.serviceAccountTokenCreator）を付与するためのポリシーを作成します。

{
    "policy":
    {
        "etag": "BwUqLaVeua8=",
        "bindings": [
        {
            "role": "roles/iam.serviceAccountUser",
            "members": [
                "user:alice@gmail.com"
            ]
        },
        {
            "role": "roles/iam.serviceAccountTokenCreator",
            "members": [
                "serviceAccount:SA-1@PROJECT-ID.iam.gserviceaccount.com"
            ]
        },
        ]
    },
}

更新されるポリシーをリクエスト本文として使用し、serviceAccounts.setIamPolicy() リクエストを行ってポリシーを更新します。

POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/SA-2@PROJECT-ID.iam.gserviceaccount.com:setIamPolicy

レスポンスには、更新されたポリシーが含まれます。

{
    "etag": "BwUqMqbViM8=",
    "bindings": [
      {
        "role": "roles/iam.serviceAccountUser",
        "members": [
            "user:alice@gmail.com"
        ]
      },
      {
        "role": "roles/iam.serviceAccountTokenCreator",
        "members": [
            "serviceAccount:SA-1@PROJECT-ID.iam.gserviceaccount.com"
        ]
      }
    ]
}

委任リクエストの権限

前述のように、委任リクエストには、呼び出し元、委任チェーン内の 1 つ以上のサービスアカウント、最後にサービスアカウントという 3 つ以上の ID が必要です。このフローでは、次の ID があるとします。

サービスアカウント 1（SA-1）: 有効期間が短い認証情報のリクエストを発行する呼び出し元。
サービスアカウント 2（SA-2）: 最初のリクエストを SA-3 に委任する仲介サービスアカウント。
サービスアカウント 3（SA-3）: 認証情報が作成される権限を制限したアカウント。

委任を許可するには、各アカウントがサービスアカウントトークン作成者の役割（roles/iam.serviceAccountTokenCreator）をチェーン内の以前のアカウントに付与する必要があります。

この特定の例では、SA-1 に、SA-2 のサービスアカウントトークン作成者の役割（roles/iam.serviceAccountTokenCreator）を付与する必要があります。これは、ID ではなくリソースのように扱われるサービスアカウントの例です。SA-1 には、SA-2 へのアクセスを委任するための権限が付与されている必要があります。ID またはリソースとしてサービスアカウントを扱う方法の詳細については、サービスアカウント権限をご覧ください。

このフローの例では、仲介サービスアカウントは 1 つだけです。複数のサービスアカウントを介してアクセスを委任するには、チェーン内の他のサービスアカウントにもこの役割を割り当てる必要があります。

次に、SA-2 には、SA-3 のサービスアカウントトークン作成者の役割（roles/iam.serviceAccountTokenCreator）も付与されている必要があります。これにより、SA-2 は SA-3 の有効期間が短い認証情報を作成できます。

次の手順では REST API で必要な権限を付与しますが、GCP Console や gcloud コマンドラインツールを使用することもできます。

API

まず、SA-2（仲介サービスアカウント）の Cloud IAM ポリシーを取得します。詳細については、serviceAccounts.getIamPolicy() リファレンスをご覧ください。

リクエスト:

POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/SA-2@PROJECT-ID.iam.gserviceaccount.com:getIamPolicy

レスポンス:

{
  "etag": "BwUqLaVeua8=",
  "bindings": [
    {
      "role": "roles/iam.serviceAccountUser",
      "members": [
          "user:alice@gmail.com"
      ]
    }
  ]
}

役割をサービスアカウントにまだ割り当てていない場合、レスポンスには 1 つの etag 値だけが含まれます。

{
  "etag": "ACAB"
}

上記の手順で取得した etag 値は、それが BwUqLaVeua8= か ACAB かを問わず、次の手順に含める必要があります。次に、SA-1 に、roles/iam.serviceAccountTokenCreator の役割を付与するためのポリシーを作成します。

{
    "policy":
    {
        "etag": "BwUqLaVeua8=",
        "bindings": [
          {
            "role": "roles/iam.serviceAccountUser",
            "members": [
                "user:alice@gmail.com"
            ]
          },
          {
            "role": "roles/iam.serviceAccountTokenCreator",
            "members": [
                "serviceAccount:SA-1@PROJECT-ID.iam.gserviceaccount.com"
            ]
        },
        ]
    },
}

更新されたポリシーを使用して、serviceAccounts.setIamPolicy() リクエストを実行します。

POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/SA-2@PROJECT-ID.iam.gserviceaccount.com:setIamPolicy

レスポンスには、更新されたポリシーが含まれます。

{
    "etag": "BwUqMqbViM8=",
    "bindings": [
    {
        "role": "roles/iam.serviceAccountUser",
        "members": [
            "user:alice@gmail.com"
        ]
    },
    {
        "role": "roles/iam.serviceAccountTokenCreator",
        "members": [
            "serviceAccount:SA-1@PROJECT-ID.iam.gserviceaccount.com"
        ]
    }
    ]
}

次に、SA-3（認証情報が作成されるサービスアカウント）の Cloud IAM ポリシーを取得します。

リクエスト:

POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/SA-3@PROJECT-ID.iam.gserviceaccount.com:getIamPolicy

レスポンス:

{
    "etag": "BwUqLaVeua8=",
    "bindings": [
    {
        "role": "roles/iam.serviceAccountUser",
        "members": [
            "user:alice@gmail.com"
        ]
    }
    ]
}

役割をサービスアカウントにまだ割り当てていない場合、レスポンスには 1 つの etag 値だけが含まれます。

{
  "etag": "ACAB"
}

上記の手順で取得した etag 値は、それが BwUqLaVeua8= か ACAB かを問わず、次の手順に含める必要があります。次に、SA-2 に、roles/iam.serviceAccountTokenCreator の役割を付与するようにポリシーを更新します。

{
    "policy":
    {
        "etag": "BwUqLaVeua8=",
        "bindings": [
        {
            "role": "roles/iam.serviceAccountUser",
            "members": [
                "user:alice@gmail.com"
            ]
        },
        {
            "role": "roles/iam.serviceAccountTokenCreator",
            "members": [
                "serviceAccount:SA-2@PROJECT-ID.iam.gserviceaccount.com"
            ]
        },
        ]
    },
}

更新されたポリシーを使用して、serviceAccounts.setIamPolicy() リクエストを実行します。

POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/SA-3@PROJECT-ID.iam.gserviceaccount.com:setIamPolicy

レスポンスには、更新されたポリシーが含まれます。

{
    "etag": "BwUqMqbViM8=",
    "bindings": [
    {
        "role": "roles/iam.serviceAccountUser",
        "members": [
            "user:alice@gmail.com"
        ]
    },
    {
        "role": "roles/iam.serviceAccountTokenCreator",
        "members": [
            "serviceAccount:SA-2@PROJECT-ID.iam.gserviceaccount.com"
        ]
    }
    ]
}

有効期間が短い認証情報のリクエスト

各 ID に対して適切な権限を付与した後、目的のサービスアカウントに属する有効期間が短い認証情報をリクエストできます。サポートされている認証情報タイプは、次のとおりです。

OAuth 2.0 アクセストークン
OpenID Connect ID トークン
自己署名 JSON ウェブトークン（JWT）
自己署名バイナリオブジェクト（blob）

こうしたリクエストに委任チェーンを指定する方法を理解するには、以下の委任チェーンの指定をご覧ください。

OAuth 2.0 アクセストークンの生成

OAuth 2.0 アクセストークンは 1 時間（3,600 秒間）有効です。サービスアカウントの OAuth 2.0 アクセストークンを生成するには:

API

generateAccessToken リクエストを実行します。SA-4@PROJECT-ID.iam.gserviceaccount.com は、トークンが作成されるサービスアカウントの名前です。

リクエストは、リクエストの Authorization ヘッダーにアクセストークンを含めることによって認証される必要があります。Google API を呼び出すためのアクセストークンの取得方法については、OAuth 2.0 の概要とサービスアカウントの OAuth 2.0 をご覧ください。

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SA-4@PROJECT-ID.iam.gserviceaccount.com:generateAccessToken

リクエスト本文に次のフィールドを指定します。

{
  "delegates": [],
  "scope": [
      "https://www.googleapis.com/auth/cloud-platform"
  ],
  "lifetime": "300s"
}

これらの各フィールドとその値の例を以下に示します。

delegates[]: 委任リクエストフローを使用している場合は、以下の委任チェーンの指定をご覧ください。委任がない直接リクエストフローを使用している場合は、リクエスト本文の delegates[] フィールドを省略します。
scope: リクエストの OAuth 2.0 スコープ。次のスコープは、generateAccessToken API を呼び出す場合に有効です。
- https://www.googleapis.com/auth/iam
- https://www.googleapis.com/auth/cloud-platform
次の例は、scope フィールドの場合の例です。
```
...
"scope": [
  "https://www.googleapis.com/auth/cloud-platform"
]
...
```
lifetime: トークンの期限が切れるまでのアクセストークンの時間（秒単位）。トークンの最大存続時間は 1 時間（3,600 秒）です。

次の例は、トークンの時間を 5 分に設定する lifetime フィールドの例です。
```
...
"lifetime": "300s"
...
```

generateAccessToken リクエストが成功した場合、レスポンスの本文には OAuth 2.0 アクセストークンと有効期限が含まれます。

{
   "accessToken": "eyJ0eXAi...NiJ9",
   "expireTime": "2018-05-07T15:01:23.045123456Z"
}

その後、accessToken を使用して、expireTime に達するまでサービスアカウントに代わってリクエストを認証できます。

OpenID Connect ID トークンの生成

OpenID Conect ID トークンは、1 時間（3,600 秒間）有効です。サービスアカウントの ID トークンを生成するには:

API

generateIdToken リクエストを実行します。SA-4@PROJECT-ID.iam.gserviceaccount.com は、トークンが作成されるサービスアカウントの名前です。

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SA-4@PROJECT-ID.iam.gserviceaccount.com:generateIdToken

リクエスト本文に次のフィールドを指定します。

{
  "delegates": [],
  "audience": "SA-4@PROJECT-ID.iam.gserviceaccount.com",
  "includeEmail": "true"
}

これらの各フィールドとその値の例を以下に示します。

delegates[]: 委任リクエストフローを使用している場合は、以下の委任チェーンの指定をご覧ください。委任がない直接リクエストフローを使用している場合は、リクエスト本文の delegates[] フィールドを省略します。
audience: サービスの URL または認証情報が作成されるサービスアカウントのメールアドレス。次に例を示します。
```
...
"audience": "SA-4@PROJECT-ID.iam.gserviceaccount.com"
...
```
includeEmail: true に設定すると、ID トークンの email クレームにサービスアカウントのメールが含まれます。また、email_verified クレームが true に設定され、ID トークンに含まれます。次に例を示します。
```
...
"includeEmail": "true"
...
```

generateIdToken リクエストが成功した場合、レスポンス本文には 1 時間有効な ID トークンが含まれます。

{
   "token": "eyJ0eXAi...NiJ9"
}

その後、token を使用して、サービスアカウントに代わってリクエストを認証できます。

自己署名 JSON ウェブトークン（JWT）の作成

自己署名 JWT は、次のようなさまざまなシナリオで役立ちます。

Google の認証ガイドに従って Google API の呼び出しを認証する。
App Engine アプリケーションなど、GCP または Google 以外のサービス間で安全に通信する。このシナリオでは、1 つのアプリケーションが、認証目的で別のアプリケーションによって確認できるトークンに署名できます。
ユーザー、アカウント、デバイスに関する任意のクレームを含む JWT に署名することにより、サービスアカウントを ID プロバイダとして扱う。

サービスアカウントの自己署名 JSON ウェブトークン（JWT）を生成するには:

API

signJwt リクエストを実行します。SA-4@PROJECT-ID.iam.gserviceaccount.com は、JWT が作成されるサービスアカウントの名前です。

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SA-4@PROJECT-ID.iam.gserviceaccount.com:signJwt

リクエスト本文に次のフィールドを指定します。

{
  "delegates": [],
  "payload": "{ \"iss\": \"SA-4@PROJECT-ID.iam.gserviceaccount.com\", \"sub\": \"SA-4@PROJECT-ID.iam.gserviceaccount.com\", \"aud\": \"https://firestore.googleapis.com/google.firestore.v1beta1.Firestore\", \"iat\": 1529350000, \"exp\": 1529353600 }"
}

これらの各フィールドとその値の例を以下に示します。

delegates[]: 委任リクエストフローを使用している場合は、以下の委任チェーンの指定をご覧ください。委任がない直接リクエストフローを使用している場合は、リクエスト本文の delegates[] フィールドを省略します。
payload: 署名する JWT ペイロード。これは JWT クレームセットを含む JSON オブジェクトです。ご希望のユースケースに必要なクレームを含め、ダウンストリームサービスの検証要件を満たしてください。Google API を呼び出す場合は、クレーム要件について Google の認証ガイドをご覧ください。

exp（有効期限）クレームは、今後 12 時間以内に設定する必要があります。そうでない場合は、検証に失敗します。JWT を使用して Google API を呼び出す場合、exp クレームは 1 時間以内に設定する必要があります。

注: クレームセットが引用符や句読点をエスケープするように正しく書式設定されていることを確認してください。

次のクレームセットの例には、最大存続時間を 1 時間（3,600 秒）に設定して Google API を呼び出すクレームの例が含まれています。
```
...
"payload": "payload": "{ "iss": "SA-4@PROJECT-ID.iam.gserviceaccount.com", "sub": "SA-4@PROJECT-ID.iam.gserviceaccount.com", "aud": "https://firestore.googleapis.com/google.firestore.v1beta1.Firestore", "iat": 1529350000, "exp": 1529353600 }"
...
```

signJwt リクエストが成功した場合、レスポンスの本文には、署名された JWT と JWT の署名に使用された署名鍵 ID が含まれています。トークンは、リクエストで指定された有効期限まで有効です。

{
   "keyId": "42ba1e...fc0a"
   "signedJwt": "eyJ0eXAi...NiJ9"
}

次に signedJwt 値を署名なしトークンとして使用して、サービスアカウントに代わってリクエストを直接認証できます。

自己署名 blob の作成

自己署名 blob は、通常は認証目的で任意のバイナリデータを安全に送信する必要がある場合に便利です。たとえば、カスタムプロトコル / トークンタイプ（JWT ではなく）を使用する場合は、ダウンストリームサービスで使用するためにそのデータを署名付き blob に含めることができます。

サービスアカウントの自己署名 blob を生成するには:

API

signBlob リクエストを実行します。SA-4@PROJECT-ID.iam.gserviceaccount.com は、blob が作成されるサービスアカウントの名前です。

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SA-4@PROJECT-ID.iam.gserviceaccount.com:signBlob

リクエスト本文に次のフィールドを指定します。

{
  "delegates": [],
  "payload": "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2cu"
}

これらの各フィールドとその値の例を以下に示します。

delegates[]: 委任リクエストフローを使用している場合は、以下の委任チェーンの指定をご覧ください。委任がない直接リクエストフローを使用している場合は、リクエスト本文の delegates[] フィールドを省略します。
payload: Base64 でエンコードされたバイトの文字列。次に例を示します。
```
...
"payload": "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2cu"
...
```

signBlob リクエストが成功した場合、レスポンスの本文には、署名 blob と blob の署名に使用された署名鍵 ID が含まれています。トークンは、リクエストで指定された有効期限まで有効です。

{
   "keyId": "42ba1e...fc0a"
   "signedBlob": "eyJ0eXAi...NiJ9"
}

委任チェーンの指定

委任されたリクエストフローを使用して有効期間が短いサービスアカウント認証情報を作成する場合、各 API のリクエストの本文で次に示す形式のサービスアカウントの委任チェーンを正しい順序で指定する必要があります。

projects/-/serviceAccounts/ACCOUNT-EMAIL-OR-UNIQUEID

たとえば、SA-1（呼び出し元）から SA-2（委任）、SA-3（委任）、SA-4 と移動する委任チェーンでは、delegates[] フィールドに SA-2 と SA-3 が次の順序で含まれます。

...
"delegates": [
    "projects/-/serviceAccounts/SA-2@PROJECT-ID.iam.gserviceaccount.com",
    "projects/-/serviceAccounts/SA-3@PROJECT-ID.iam.gserviceaccount.com"
],
...

呼び出し元と認証情報が作成されるサービスアカウントは、委任チェーンに含まれません。

有効期間が短いサービス アカウント認証情報の作成

始める前に

権限を制限したサービス アカウントの作成

必要な権限の付与

直接リクエストの権限

API

委任リクエストの権限

API

有効期間が短い認証情報のリクエスト

OAuth 2.0 アクセス トークンの生成

API

OpenID Connect ID トークンの生成

API

自己署名 JSON ウェブトークン（JWT）の作成

API

自己署名 blob の作成

API

委任チェーンの指定

フィードバックを送信...

権限を制限したサービスアカウントの作成

OAuth 2.0 アクセストークンの生成