OIDC ID プロバイダからリソースにアクセスする

このドキュメントでは、ID 連携を使用して OpenID Connect（OIDC）をサポートする ID プロバイダから Google Cloud リソースにアクセスする方法について説明します。

従来、Google Cloud の外部で実行されているアプリケーションは、サービス アカウント キーを使用して Google Cloud リソースにアクセスしていました。ID 連携を使用すると、外部 ID でサービス アカウントになり代わることができます。これにより、ワークロードは短期間だけ有効なアクセス トークンを使用して Google Cloud リソースに直接アクセスでき、サービス アカウント キーに関連するメンテナンスとセキュリティの負担が軽減されます。

始める前に

  1. IAM, Resource Manager, Service Account Credentials, and Security Token Service (STS) API を有効にします。

    API を有効にする

  2. Workload Identity プール管理者ロール（roles/iam.workloadIdentityPoolAdmin）があることを確認します。

    また、IAM オーナー（roles/owner）の基本ロールには ID 連携を構成する権限も含まれています。本番環境で基本ロールを付与することはできませんが、開発環境またはテスト環境ではこれらのロールを付与できます。

  3. 組織が ID プロバイダからの連携を許可するには、組織ポリシーを更新します。

  4. Google Cloud サービス アカウントを作成します。

  5. サービス アカウントにアクセス権を付与して、ワークロードに必要な Google Cloud APIs を呼び出します。

Workload Identity プールの作成

Workload Identity プールを使用して、外部 ID を編成および管理できます。Workload Identity プールは相互に分離されていますが、1 つのプールは任意の数のサービス アカウントになり代わることができます。一般に、開発、ステージング、本番環境など、環境ごとに新しいプールを作成することをおすすめします。

新しい Workload Identity プールを作成するには、ID を指定する必要があります。オプションの説明と表示名を指定することもできます。

gcloud

gcloud iam workload-identity-pools create コマンドを実行して Workload Identity プールを作成します。

gcloud iam workload-identity-pools create pool-id \
    --location="global" \
    --description="description" \
    --display-name="display-name"

レスポンスは次のようになります。

Created workload identity pool [pool-id].

REST

projects.locations.workloadIdentityPools.create メソッドにより、Workload Identity プールが作成されます。

HTTP メソッドと URL:

POST https://iam.googleapis.com/v1/projects/project-id/locations/global/workloadIdentityPools?workloadIdentityPoolId=pool-id

JSON 本文のリクエスト: 

{
  "description": "description",
  "display-name": "display-name"
}

リクエストを送信するには、次のいずれかのオプションを展開します。

このメソッドは、次のような長時間実行 Operation を返します。

{
  "name": "projects/project-number/locations/global/workloadIdentityPools/pool-id/operations/operation-id"
}

OIDC ID プロバイダの追加

Workload Identity プールの OIDC ID プロバイダを構成するには、少なくとも次の情報を指定します。

  • プロバイダの ID。

  • このドキュメントの前のセクションの Workload Identity プール ID。

  • プロバイダの発行者 URI。通常は、https://example.com の形式を使用します。URI の確認については、OIDC 統合に関するプロバイダのドキュメントをご覧ください。

  • 外部トークンのクレームを Google トークンの属性にマッピングする属性マッピングのリスト。assertion を使用して外部認証情報を参照します。Google 属性の場合は google、カスタム属性の場合は attribute を使用します。

    Google 属性には google.subject と google.groups の 2 つがあります。これらの属性は IAM ロール バインディングで参照できます。google.subject も Cloud Logging のログエントリに表示されます。

    google.subject のマッピングを指定する必要があります。通常は、assertion.sub にマッピングすることをおすすめします。これにより、IAM ロール バインディングで使用する固定 ID が提供されます。マッピングは次のようになります。

    google.subject=assertion.sub

    より複雑なアサーションの場合は、Common Expression Language を使用できます。たとえば、Workload Identity プールに複数の ID プロバイダが含まれている場合は、それらの ID を明確化するために接頭辞を追加できます。

    google.subject="provider-a::" + assertion.sub

    google.subject フィールドは 127 文字以下で指定してください。

    カスタム属性を指定することもできます。たとえば、以下では assertion.foo を attribute.bar にマッピングします。

    attribute.bar=assertion.foo

    参照できるクレームの完全なリストについては、アクセス トークンに関するプロバイダのドキュメントをご覧ください。

    式で使用されているクレームの特定の部分を参照するには、CEL の extract() 関数を使用します。この関数は、指定したテンプレートに基づいてクレームから値を抽出します。extract() の詳細については、リソース名からの値の抽出をご覧ください。

    認証情報にクレームが含まれているかどうかを確認するには、has() 関数を使用します。

  • 外部認証情報の aud フィールドに設定できる値を指定する許可されたオーディエンスのリスト。最大 10 個のオーディエンス（それぞれ最大 256 文字）を構成できます。aud のデフォルト値については、プロバイダのドキュメントをご覧ください。

    または、ID プロバイダで aud のカスタム値を構成できる場合は、許可オーディエンス パラメータを空白のままにし、aud の値を Workload Identity プロバイダの完全なリソース名に設定できます。HTTP 接頭辞は省略可能です。例:

    //iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id
https://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id

    どちらの場合も、許可された値を含まないトークン交換リクエストは拒否されます。

次の複数のオプション パラメータを指定することもできます。

  • 表示名と説明。

  • プリンシパルが提示する必要がある属性を指定する属性条件。この属性条件は、外部認証情報に対するクレーム、または Google 認証情報の属性に適用できます。属性条件を満たしていないリクエストは拒否されます。

    属性条件は、ブール値を返す CEL 式の形式になります。たとえば以下では、特定のグループのメンバーではない ID からのリクエストは拒否されます。

    group in assertion.groups

    ID プロバイダが一般に公開されている場合は、属性条件を使用することを強くおすすめします。一般的なユースケースの詳細については、属性条件をご覧ください。

次の例は、ID プロバイダを追加する方法を示しています。

gcloud

gcloud iam workload-identity-pools providers create-oidc コマンドを実行して ID プロバイダを追加します。

gcloud iam workload-identity-pools providers create-oidc provider-id \
    --workload-identity-pool="pool-id" \
    --issuer-uri="issuer-uri" \
    --location="global" \
    --attribute-mapping="google.subject=assertion.sub"

レスポンスは次のようになります。

Created workload identity pool provider [provider-id].

REST

projects.locations.workloadIdentityPools.providers.create メソッドにより、OIDC ID プロバイダが追加されます。

HTTP メソッドと URL:

POST https://iam.googleapis.com/v1/projects/project-id/locations/global/workloadIdentityPools/pool-id/providers?workloadIdentityPoolProviderId=provider-id

JSON 本文のリクエスト: 

{
  "issuerUrl": "issuer-uri"
}

リクエストを送信するには、次のいずれかのオプションを展開します。

このメソッドは、次のような長時間実行 Operation を返します。

{
  "name": "projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id/operations/operation-id"
}

サービス アカウントの権限借用を許可する

外部 ID は、ほとんどの Google Cloud リソースに直接アクセスできません。代わりに、Workload Identity ユーザーロール（roles/iam.workloadIdentityUser）をサービス アカウントに付与することで、サービス アカウントの権限を借用できます。

特定の ID にこのロール バインディングを追加するには、google.subject にマッピングされた値を使用します。

gcloud iam service-accounts add-iam-policy-binding service-account-email \
    --role roles/iam.workloadIdentityUser \
    --member "principal://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/subject/subject"

グループのすべてのメンバーにこのバインディングを追加するには:

gcloud iam service-accounts add-iam-policy-binding service-account-email \
    --role roles/iam.workloadIdentityUser \
    --member "principalSet://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/group/group-name"

カスタム属性に基づいてアクセス権を付与することもできます。例:

gcloud iam service-accounts add-iam-policy-binding service-account-email \
    --role="roles/iam.workloadIdentityUser" \
    --member="principalSet://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/attribute.custom-attribute-name/custom-attribute-value"

アクセス権を取り消すには、add-iam-policy-binding を remove-iam-policy-binding に置き換えます。

REST API またはクライアント ライブラリを使用して、バインディングの追加または削除を行うこともできます。詳細については、リソースへのアクセス権の付与、変更、取り消しをご覧ください。

Google 認証情報を生成する

サポートされているクライアント ライブラリを使用する場合は、Google 認証情報が自動的に生成されるようにクライアント ライブラリを構成できます。または、OIDC ID トークンを手動で生成し、Google 認証情報と交換することもできます。

可能であれば、トークン交換プロセスを自身で実装しなくても済むように、認証情報を自動的に生成することをおすすめします。

認証情報の自動生成

次のいずれかの言語のクライアント ライブラリを使用して Google Cloud にアクセスする場合は、ID 連携を使用して認証情報を自動的に生成するようにクライアント ライブラリを構成できます。

C++

C++ 用 Google Cloud クライアント ライブラリのほとんどは、grpc::GoogleDefaultCredentials() を呼び出して作成される ChannelCredentials オブジェクトを使用して ID 連携をサポートしています。この認証情報を初期化するには、バージョン 1.36.0 以降の gRPC でクライアント ライブラリを構築する必要があります。

C++ 用 Cloud Storage クライアント ライブラリは、gRPC ではなく REST API を使用するため、ID 連携をサポートしていません。

Go

Go 用クライアント ライブラリは、golang.org/x/oauth2 モジュールのバージョン v0.0.0-20210218202405-ba52d332ba99 以降を使用している場合、ID 連携をサポートします。

クライアント ライブラリが使用しているこのモジュールのバージョンを確認するには、次のコマンドを実行します。

cd $GOPATH/src/cloud.google.com/go
go list -m golang.org/x/oauth2

Java

Java 用クライアント ライブラリは、com.google.auth:google-auth-library-oauth2-http アーティファクトのバージョン 0.24.0 以降を使用している場合、ID 連携をサポートします。

クライアント ライブラリで使用しているこのアーティファクトのバージョンを確認するには、アプリケーション ディレクトリで次の Maven コマンドを実行します。

mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http

Node.js

Node.js 用クライアント ライブラリは、google-auth-library パッケージのバージョン 7.0.2 以降を使用している場合、ID 連携をサポートします。

クライアント ライブラリで使用されているこのパッケージのバージョンを確認するには、アプリケーション ディレクトリで次のコマンドを実行します。

npm list google-auth-library

GoogleAuth オブジェクトを作成するときに、プロジェクト ID を指定できます。また、GoogleAuth で自動的にプロジェクト ID を検出することもできます。プロジェクト ID を自動的に検出するには、構成ファイルのサービス アカウントに、プロジェクト上でブラウザのロール（roles/browser）または同等の権限を持つロールが付与されている必要があります。詳細については、google-auth-library パッケージの README をご覧ください。

Python

Python 用クライアント ライブラリは、google-auth パッケージのバージョン 1.27.0 以降を使用している場合、ID 連携をサポートします。

クライアント ライブラリで使用されているこのパッケージのバージョンを確認するには、パッケージがインストールされている環境で次のコマンドを実行します。

pip show google-auth

認証クライアントのプロジェクト ID を指定するには、GOOGLE_CLOUD_PROJECT 環境変数を設定するか、クライアントがプロジェクト ID を自動的に検出するようにします。プロジェクト ID を自動的に検出するには、構成ファイルのサービス アカウントに、プロジェクト上でブラウザのロール（roles/browser）または同等の権限を持つロールが付与されている必要があります。詳細については、google-auth パッケージのユーザーガイドをご覧ください。

クライアント ライブラリは、いくつかの方法で ID プロバイダからトークンを取得できます。

  • ファイルソースの認証情報: トークンはファイルから読み込まれます。古いトークンが期限切れになる前に、別のプロセスでこのファイルを新しい OIDC トークンで更新する必要があります。たとえば、トークンの有効期間が 1 時間の場合、1 時間経過する前にファイルを更新する必要があります。
  • URL 提供の認証情報: トークンは、HTTP GET リクエストに応答するエンドポイントを持つローカル サーバーから読み込まれます。レスポンスは、書式なしテキストまたは JSON 形式の OIDC ID トークンでなければなりません。

ファイルソースの認証情報を使用するには、gcloud iam workload-identity-pools create-cred-config コマンドを実行して構成ファイルを生成します。--credential-source-type フラグは省略可能です。--credential-source-type が json でない限り、--credential-source-field-name フラグは省略可能です。

gcloud iam workload-identity-pools create-cred-config \
    projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id \
    --service-account=service-account-email \
    --output-file=configuration-filepath \
    --credential-source-file=token-filepath \
    --credential-source-type=source-type \
    --credential-source-field-name=field-name

次の値を置き換えます。

  • project-number: プロジェクトの数値 ID。
  • pool-id: Workload Identity プールの ID。
  • provider-id: Workload Identity プール プロバイダの ID。
  • service-account-email: なり代わるサービス アカウントのメールアドレス。
  • configuration-filepath: 構成ファイルのファイルパス。
  • token-filepath: OIDC ID トークンが保存されるファイルパス。
  • source-type: OIDC ID トークン ファイルの形式。text または json に設定します。デフォルトは text です。
  • field-name: JSON トークン ファイルの場合、トークンを含む JSON フィールド名。--credential-source-type が json の場合は必須です。

URL で生成された認証情報を使用するには、gcloud iam workload-identity-pools create-cred-config コマンドを実行して構成ファイルを生成する必要もあります。--credential-source-headers フラグと --credential-source-type フラグは省略可能です。--credential-source-type が json でない限り、--credential-source-field-name フラグは省略可能です。

gcloud iam workload-identity-pools create-cred-config \
    projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id \
    --service-account=service-account-email \
    --output-file=configuration-filepath \
    --credential-source-url="token-url" \
    --credential-source-headers="key1=value1,key2=value2" \
    --credential-source-type=source-type \
    --credential-source-field-name=field-name

次の値を置き換えます。

  • project-number: プロジェクトの数値 ID。
  • pool-id: Workload Identity プールの ID。
  • provider-id: Workload Identity プール プロバイダの ID。
  • service-account-email: なり代わるサービス アカウントのメールアドレス。
  • configuration-filepath: 構成ファイルのファイルパス。
  • token-url: HTTP GET リクエストに対する OIDC ID トークンを提供する URL。
  • key1、key2: リクエストに含める HTTP ヘッダーの名前。
  • value1、value2: リクエストに含める HTTP ヘッダーの値。
  • source-type: OIDC トークン ファイルの形式。text または json に設定します。デフォルトは text です。
  • field-name: JSON トークン ファイルの場合、トークンを含むフィールド名。--credential-source-type が json の場合は必須です。

構成ファイルを生成したら、環境変数 GOOGLE_APPLICATION_CREDENTIALS を構成ファイルのファイルパスに設定します。この環境変数は、クライアント ライブラリに対し、アプリケーションのデフォルト認証情報を使用して認証するように指示します。詳細については、認証情報の自動検出をご覧ください。

認証情報を手動で交換する

外部 ID が、サービス アカウントに成り代わることができると、認証情報を Google 認証情報と手動で交換できます。

認証情報を交換するには:

  1. ID プロバイダから OIDC ID トークンを取得します（詳しい手順については、ID プロバイダのドキュメントをご覧ください）。

  2. OIDC ID トークンをセキュリティ トークン サービスの token() メソッドに渡して、連携アクセス トークンを取得します。

    REST

    token メソッドにより、サードパーティ トークンが Google トークンに交換されます。

    後述のリクエストのデータを使用する前に、次のように置き換えます。

    • project-number: Google Cloud プロジェクト番号。
    • pool-id: このチュートリアルで前に作成した Workload Identity プールの ID。
    • provider-id: このチュートリアルで前に構成した ID プロバイダの ID。

    HTTP メソッドと URL:

    POST https://sts.googleapis.com/v1/token

    JSON 本文のリクエスト: 

    {
  "audience": "//iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id",
  "grantType": "urn:ietf:params:oauth:grant-type:token-exchange",
  "requestedTokenType": "urn:ietf:params:oauth:token-type:access_token",
  "scope": "https://www.googleapis.com/auth/cloud-platform",
  "subjectTokenType": "urn:ietf:params:oauth:token-type:jwt",
  "subjectToken": "oidc-id-token"
}

    リクエストを送信するには、次のいずれかのオプションを展開します。

     

    このメソッドは連携トークンを返します。

  3. generateAccessToken() を呼び出して、サービス アカウントのアクセス トークンと連携トークンを交換します。連携トークンは一部の Google Cloud APIs でサポートされています。すべての Google Cloud APIs はサービス アカウントのアクセス トークンをサポートしています。

    REST

    Service Account Credentials API の serviceAccounts.generateAccessToken メソッドによって、サービス アカウントの OAuth 2.0 アクセス トークンが生成されます。

    後述のリクエストのデータを使用する前に、次のように置き換えます。

    • PROJECT_ID: Google Cloud プロジェクト IDプロジェクト ID は英数字からなる文字列です（例: my-project）。
    • SA_ID: サービス アカウントの ID。これは、サービス アカウントのメールアドレス（SA_NAME@PROJECT_ID.iam.gserviceaccount.com の形式）、またはサービス アカウントの一意の数値 ID のいずれかです。
    • token: 連携アクセス トークン。

    HTTP メソッドと URL:

    POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com:generateAccessToken

    JSON 本文のリクエスト: 

    {
  "scope": [
    "https://www.googleapis.com/auth/cloud-platform"
  ]
}

    リクエストを送信するには、次のいずれかのオプションを展開します。

    generateAccessToken リクエストが成功した場合、レスポンスの本文には OAuth 2.0 アクセス トークンと有効期限が含まれます。expireTime に達するまで、サービス アカウントの代わりに accessToken をリクエストの認証に使用できます。

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

サービス アカウントのアクセス トークンを取得したら、リクエストの Authorization ヘッダーにトークンを含めることで、Google Cloud APIs の呼び出しに使用できます。

Authorization: Bearer service-account-access-token

リクエストはサービス アカウントとして承認されます。

次のステップ