Workload Identity 連携の構成

このガイドでは、外部 ID プロバイダによって発行された認証情報を使用して、サービス アカウントの権限を借用し、Google Cloud のリソースにアクセスする方法について説明します。このプロセスは Workload Identity 連携と呼ばれます。

Workload Identity 連携の一般的なユースケースは次のとおりです。

• Google Cloud の外部で実行されるバックグラウンド アプリケーションまたは継続的インテグレーション / 継続的デリバリー（CI / CD）パイプラインを有効にして、Google Cloud のリソースと API にアクセスできるようにする。
• Google Cloud の外部で実行されるウェブ アプリケーションのユーザーが、Cloud Storage や BigQuery などの Google Cloud サービスに保存されているデータにアクセスできるようにする。

Workload Identity 連携を使用するには、アマゾン ウェブ サービス（AWS）、Azure Active Directory（AD）、OIDC 互換 ID プロバイダ、または SAML 2.0 対応 ID プロバイダなどの外部 ID プロバイダを信頼するように Google Cloud を構成します。これにより、外部 ID プロバイダから発行された認証情報をアプリケーションで使用し、次のようにサービス アカウントの権限を借用できるようになります。

1. 信頼できる ID プロバイダから認証情報を取得します。
2. Security Token Service から取得したトークンと認証情報を交換します。
3. Security Token Service のトークンを使用してサービス アカウントの権限を借用し、有効期間の短い Google アクセス トークンを取得します。

Workload Identity 連携を使用することで、サービス アカウント キーを保存して管理する必要がなくなります。

始める前に

• IAM, Resource Manager, Service Account Credentials, and Security Token Service API を有効にします。

  API を有効にする

必要なロール

Workload Identity 連携の構成に必要な権限を取得するには、プロジェクトに対して次の IAM ロールを付与するよう管理者に依頼してください。

• Workload Identity プール管理者（roles/iam.workloadIdentityPoolAdmin）
• サービス アカウント管理者（roles/iam.serviceAccountAdmin）

ロールの付与の詳細については、アクセスの管理をご覧ください。

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

外部 ID プロバイダの準備

Workload Identity 連携を使用するには、プロジェクトで Workload Identity プールと Workload Identity プール プロバイダを構成する必要があります。

AWS

AWS ユーザーと AWS ロールは、永続的または一時的な AWS セキュリティ認証情報を使用して、Google Cloud のサービス アカウントの権限を借用できます。

AWS セキュリティ認証情報を使用できるようにするには、AWS アカウントを信頼するように Workload Identity プールを構成する必要があります。これにより、この AWS アカウントに発行されたセキュリティ認証情報トークンが Workload Identity 連携で認識され、このトークンを使用して、有効期間の短いサービス アカウント認証情報を取得できるようになります。

Azure

Azure ユーザーとサービス プリンシパルは、Azure AD アクセス トークンを使用して Google Cloud のサービス アカウントの権限を借用できます。

Azure AD アクセス トークンの使用を許可するには、Azure AD アプリケーションを信頼するように Workload Identity プールを構成する必要があります。これにより、このアプリケーションに発行されたアクセス トークンが Workload Identity 連携で認識され、このトークンを使用して、有効期間の短いサービス アカウント認証情報を取得できるようになります。

Azure AD で新しいアプリケーションを作成し、そのアプリケーションを Google Cloud の認証情報の取得のみに使用することをおすすめします。

1. Azure AD アプリケーションとサービス プリンシパルを作成します。

2. アプリケーションにアプリケーション ID URI を設定します。

   アプリケーション ID の URI を設定する場合、デフォルトは api://<appid> になります。後で Workload Identity プールのプロバイダと認証情報構成ファイルを作成するときに必要になるため、この URI をメモしておいてください。

後で Workload Identity プール プロバイダを構成するときに、アプリケーション ID URI が必要になります。

アプリケーションが Azure AD アプリケーションのアクセス トークンを取得できるようにするには、マネージド ID を使用します。

1. マネージド ID を作成します。マネージド ID のオブジェクト ID をメモします。これは、後で権限借用を構成するときに必要になります。

2. アプリケーションを実行する仮想マシンまたは別のリソースにマネージド ID を割り当てます。

注: Azure のデフォルト設定を使用すると、新しいアプリケーションによって、Azure AD テナントのすべてのユーザーにアクセス トークンの取得権限が付与されます。アプリロールの割り当てを使用して、アプリケーションのアクセス トークンを取得できる ID を制限します。

GitHub Actions

GitHub Actions ワークフローで GitHub OIDC トークンを使用して、Google Cloud のサービス アカウントの権限を借用できます。

これらのトークンの使用を許可するには、GitHub から発行された OIDC トークンを信頼するように Workload Identity プールを構成する必要があります。これにより、ワークフロー用に発行された ID トークンが Workload Identity 連携によって認識され、このトークンを使用して、有効期間の短いサービス アカウント認証情報を取得できるようになります。

OIDC

ID トークンを使用するか、OIDC 準拠の ID プロバイダから発行される JSON ウェブトークン形式のアクセス トークンを使用して、ユーザーとアプリケーションが Google Cloud でサービス アカウントの権限を借用できるようにします。

これらのトークンの使用を許可するには、外部 ID プロバイダを信頼するように Workload Identity プールを構成する必要があります。これにより、外部 ID プロバイダによって発行されたトークンが Workload Identity 連携によって認識され、このトークンを使用して、有効期間の短いサービス アカウント認証情報を取得できるようになります。

Workload Identity 連携を使用するには、ID プロバイダの OIDC メタデータ URI がインターネットからアクセス可能で、エンドポイント ISSUER/.well-known/openid-configuration を使用する必要があります。ここで ISSUER は、トークンの発行者（iss）要求の値です。Google Cloud からメタデータ エンドポイントにクエリを実行して、プロバイダの JSON ウェブ キー セット（JWKS）を取得し、このキーセットを使用してトークンを検証します。

ID トークンはユーザーの ID を反映しているため、トークンの交換時に ID トークンを使用することをおすすめします。アクセス トークンを使用する場合は、Google Cloud の認証情報の取得のみを行う専用のアプリケーションまたはリソースを ID プロバイダに構成します。

Workload Identity 連携のデフォルトでは、トークンが次の URL を対象（aud）要求として使用することを想定しています。

https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

次のように置き換えます。

• PROJECT_NUMBER: Workload Identity プールの作成に使用する Google Cloud プロジェクトのプロジェクト番号。
• POOL_ID: Workload Identity プールを識別する任意の ID。後で Workload Identity プールを作成するときに、この ID を使用する必要があります。
• PROVIDER_ID: Workload Identity プールのプロバイダを識別する任意の ID。後で Workload Identity プールのプロバイダを作成するときに、この ID を使用する必要があります。

Workload Identity プールとプロバイダを作成するときに、許可する対象のカスタムリストを指定できます。

注: Workload Identity 連携は、opaque トークンまたはトークン イントロスペクションをサポートしていません。

OIDC（AD FS）

Active Directory ユーザーは、Active Directory フェデレーション サービス（AD FS）の OIDC アクセス トークンを使用して、Google Cloud でサービス アカウントの権限を借用できます。

アプリケーションが AD FS アクセス トークンをリクエストし、これらのトークンを使用して Google Cloud にアクセスできるようにするには、AD FS で 2 つのアプリケーション登録が必要です。

1. ネイティブ アプリケーションまたはサーバー アプリケーションのタイプのアプリケーション登録。

2. Google Cloud 上の Workload Identity プール プロバイダに対応する Web API タイプのアプリケーション登録。

次に、Workload Identity プロバイダを構成して、Web API に発行されるアクセス トークンを受け入れます。

Windows 統合認証の使用

Workload Identity 連携は、Windows 統合認証（IWA）と統合できます。IWA を使用すると、Active Directory アプリケーションは Kerberos 認証情報や NTLM 認証情報を使用して AD FS に対して認証を行えます。Workload Identity 連携と IWA を統合することで、AD FS クライアント認証情報とサービス アカウント キーの保存と管理が不要になります。

IWA を使用するには、次の前提条件を満たす必要があります。

• アプリケーションが、IWA をサポートする HTTP ライブラリを使用している。
• Windows 認証を許可するように AD FS を構成し、適切なサービス プリンシパル名を使用している。
• 認証のための拡張保護が AD FS デプロイと互換性を持つように構成されている。
• アプリケーションが HTTP リクエストで使用するユーザー エージェント用に IWA を有効にしている。

クライアント アプリケーションを登録する

AD FS で Windows Server 2019 にアプリケーションを登録するには、次の手順を行います。

1. AD FS MMC スナップインを開き、[アプリケーション グループ] に移動します。
2. [アプリケーション グループの追加] をクリックします。
3. [ようこそ] ページでクライアントの名前を入力し、[サーバー アプリケーション] を選択します。[次へ] をクリックします。
4. [サーバー アプリケーション] ページで、クライアント識別子（クライアント ID）とリダイレクト URI を入力します。client_credentials 付与タイプのみを使用する場合、リダイレクト URI は使用されないため、http://localhost/ などの URI を使用できます。[次へ] をクリックします。
5. [アプリケーションの資格情報の構成] ページで、クライアントの認証方法を選択します。IWA を使用するには、[Windows 統合認証] を [有効] に設定して、アプリケーションを実行するドメイン ユーザーを選択します。[次へ] をクリックします。
6. [概要] ページで、設定を確認して [次へ] をクリックします。
7. [閉じる] をクリックしてダイアログを閉じます。

Workload Identity 連携プール用のウェブ API アプリケーションを作成する

Web API タイプの別のアプリケーション登録を作成します。このアプリケーションは Workload Identity プールのプロバイダに対応し、Google Cloud との信頼関係を設定するために使用します。

AD FS for Windows Server 2019 でアプリケーションを作成するには、次の操作を行います。

1. AD FS MMC スナップインを開き、[アプリケーション グループ] に移動します。
2. [アプリケーション グループの追加] をクリックします。
3. スタートページで、「Workload Identity Federation (test environment)」などの名前を入力し、[Web API] を選択します。[次へ] をクリックします。

4. [Web API の構成] ページで、ウェブ API 用の証明書利用者 ID を入力します。

   カスタム証明書利用者 ID を定義するのではなく、次の URI を証明書利用者 ID として使用できます。

   https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
   

   次の値を置き換えます。

   • PROJECT_NUMBER: Workload Identity プールの作成に使用する Google Cloud プロジェクトのプロジェクト番号。
   • POOL_ID: Workload Identity プールを識別する任意の ID。後で Workload Identity プールを作成するときに、この ID を使用する必要があります。
   • PROVIDER_ID: Workload Identity プールのプロバイダを識別する任意の ID。後で Workload Identity プールのプロバイダを作成するときに、この ID を使用する必要があります。

   この形式を使用することで、証明書利用者 ID によって Workload Identity プールのプロバイダが一意に識別されます。

   証明書利用者 ID は、後で Workload Identity プール プロバイダを構成するときに必要になります。

5. [次へ] をクリックします。

6. [アクセス制御ポリシーの適用] ページで、適切なアクセス ポリシーを選択し、[次へ] をクリックします。

7. [アプリケーションのアクセス許可の構成] ページで、前に作成したクライアント アプリケーションを追加します。[次へ] をクリックします。

8. [概要] ページで、設定を確認して [次へ] をクリックします。

9. [閉じる] をクリックしてダイアログを閉じます。

注: Workload Identity 連携は、opaque トークンまたはトークン イントロスペクションをサポートしていません。

SAML

SAML 2.0 対応 ID プロバイダによって発行されたアサーションを使用して、ユーザーとアプリケーションが Google Cloud でサービス アカウントの権限を借用できるようにします。暗号化されたアサーションを使用した連携はサポートされません。

ご利用の SAML ID プロバイダを構成し、Workload Identity プール プロバイダを含むアサーションを、オーディエンスとして https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID 形式で発行します。

このようなアサーションの使用を許可するには、SAML ID プロバイダのメタデータ ドキュメントを提供して、外部 ID プロバイダを信頼するように Workload Identity プールを構成する必要があります。

次に、Workload Identity 連携は、外部 ID プロバイダによって発行されたアサーションを認識します。トークンを使用して有効期間が短いサービス アカウント認証情報を取得できます。

SAML（AD FS）

Active Directory フェデレーション サービス（AD FS）の SAML 2.0 アサーションを使用することで、アプリケーションがサービス アカウントの権限を借用できます。

注: Workload Identity 連携では、SAML 1.1 アサーションも暗号化されたアサーションもサポートされていません。

アプリケーションが Workload Identity 連携に使用できる AD FS からの SAML アサーションをリクエストできるようにするには、証明書利用者信頼を作成する必要があります。Windows Server 2019 用の AD FS で証明書利用者信頼を作成するには、次の手順を行います。

1. AD FS MMC スナップインを開き、[証明書利用者信頼] に移動します。
2. [証明書利用者信頼の追加] をクリックします。
3. [証明書利用者信頼の追加] ウィザードの [ようこそ] ページで、[要求に対応する] を選択して [開始] をクリックします。
4. [データ ソースの選択] ページで、[証明書利用者についてのデータを手動で入力する] を選択します。[次へ] をクリックします。
5. [表示名の指定] ページで、信頼の名前を入力します。[次へ] をクリックします。
6. [証明書の構成] ページで、[次へ] をクリックします。Workload Identity 連携は、暗号化された SAML アサーションをサポートしていないため、暗号化証明書は必要ありません。
7. [URL の構成] ページで、デフォルトの設定をそのままに使用して、[次へ] をクリックします。

8. [識別子の構成] ページで、証明書利用者 ID を入力します。

   カスタム証明書利用者 ID を定義するのではなく、次の URI を証明書利用者 ID として使用できます。

   https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
   

   次のように置き換えます。

   • PROJECT_NUMBER: Workload Identity プールの作成に使用する Google Cloud プロジェクトのプロジェクト番号。
   • POOL_ID: Workload Identity プールを識別する任意の ID。後で Workload Identity プールを作成するときに、この ID を使用する必要があります。
   • PROVIDER_ID: Workload Identity プールのプロバイダを識別する任意の ID。後で Workload Identity プールのプロバイダを作成するときに、この ID を使用する必要があります。

   この形式を使用することで、証明書利用者 ID によって Workload Identity プールのプロバイダが一意に識別されます。

   証明書利用者 ID は、後で Workload Identity プール プロバイダを構成するときに必要になります。

9. [次へ] をクリックします。

10. [アクセス制御ポリシーの選択] ページで、適切なアクセス制御ポリシーを選択し、[次へ] をクリックします。

11. [信頼の追加の準備完了] ページで設定内容を確認して、[次へ] をクリックします。

12. [終了] ページで [閉じる] をクリックして、ダイアログを閉じます。

Workload Identity 連携との互換性を確保するために、SAML アサーションには、Active Directory ユーザーを一意に識別する要求が 1 つ以上含まれている必要があります。通常は、この目的のため、SAML アサーションの NameID 要素の値に対応する名前 ID 要求を使用します。

SAML アサーションの一連の要求をカスタマイズするには、証明書利用者信頼の要求発行ポリシーを編集する必要があります。要求発行ポリシーを編集する手順は次のとおりです。

1. 証明書利用者信頼のリストで、作成した信頼を選択し、[要求発行ポリシーの編集] をクリックします。
2. [規則の追加] をクリックします。
3. [変換要求規則の追加] ウィザードの [規則の種類の選択] ページで、[入力方向の要求を変換] を選択します。[次へ] をクリックします。

4. [要求規則の構成] ページで、次の設定を構成します。

   • 要求規則名: Name Identifier。
   • 入力方向の要求の種類: プライマリ SID または UPN。あるいは、サブジェクトを一意に識別する別の要求を選択します。
   • 出力方向の要求の種類: 名前 ID。
   • 出力方向の名前 ID の形式: 指定なし。

5. [すべての要求値をパス スルーする] を選択し、[終了] をクリックします。

6. 必要に応じて追加の規則を構成し、SAML アサーションに属性を追加します。

7. [OK] をクリックして、要求発行ポリシーのダイアログを閉じます。

連携の構成

外部 ID プロバイダと連携するには、次のことを行う必要があります。

1. Workload Identity プールとプロバイダを含む Google Cloud プロジェクトを準備します。
2. ID プロバイダの認証情報を外部 ID にマッピングする属性マッピングを定義します。また、必要に応じて属性条件も定義します。
3. Workload Identity のプールとプロバイダを作成します。

以降のセクションでは、この手順について詳しく説明します。

プロジェクトを準備する

Workload Identity プールとプロバイダを含むプロジェクトを選択して準備します。

1. プロジェクトに Workload Identity プール管理者（roles/iam.workloadIdentityPoolAdmin）とサービス アカウント管理者（roles/iam.serviceAccountAdmin）のロールがあることを確認します。

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

2. 連携を許可するように組織のポリシーを更新します。

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

   API を有効にする

属性のマッピングと条件を定義する

ID プロバイダの認証情報を外部 ID にマッピングする属性マッピングを定義します。また、必要に応じて属性条件も定義します。

外部 ID プロバイダから発行された認証情報には、1 つ以上の属性（クレーム）が含まれます。Workload Identity 連携では、これらの属性をアサーション属性として参照し、先頭に assertion. を付けます。

属性マッピングを使用すると、Workload Identity 連携で認識される事前定義済みのターゲット属性にアサーション属性をマッピングできます。これらの定義済みのターゲット属性は次のとおりです。

属性	説明
google.subject	必須。ユーザーの一意の識別子。この属性は、IAM principal:// ロール バインディングで使用され、Cloud Logging のログに表示されます。127 文字以内の一意の値にする必要があります。
google.groups	省略可。ID が属するグループのセット。この属性は、IAM の principalSet:// ロール バインディングでグループのすべてのメンバーにアクセス権を付与する場合に使用されます。
attribute.NAME	省略可。最大で 50 個までのカスタム属性を定義できます。これらの属性を IAM principalSet:// ロール バインディングで使用して、特定の属性を持つすべての ID にアクセス権を付与できます。

属性マッピングの形式は TARGET_ATTRIBUTE=SOURCE_EXPRESSION です。次の例をご覧ください。

• このマッピングでは、アサーション属性 sub が google.subject に割り当てられます。

  google.subject=assertion.sub
  

• このマッピングでは、Common Expression Language（CEL）式を使用して、複数のアサーション属性を連結します。

  google.subject="myprovider::" + assertion.aud + "::" + assertion.sub
  

• このマッピングでは、別の CEL 式を使用して GUID 値のアサーション属性 workload_id を名前にマッピングし、結果を attribute.my_display_name という名前のカスタム属性に割り当てます。

  attribute.my_display_name={
    "8bb39bdb-1cc5-4447-b7db-a19e920eb111": "Workload1",
    "55d36609-9bcf-48e0-a366-a3cf19027d2a": "Workload2"
  }[assertion.workload_id]
  

• このマッピングでは、CEL の論理演算子と関数を使用して、ID の Amazon リソース名（ARN）に応じて、attribute.environment という名前のカスタム属性を prod または test に設定します。

  attribute.environment=assertion.arn.contains(":instance-profile/Production") ? "prod" : "test"
  

• このマッピングでは、extract 関数を使用して、想定されたロールの名前カスタム属性 aws_role に設定します。想定されたロールがない場合は、ID の ARN が設定されます。

  attribute.aws_role=assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn
  

必要に応じて、属性条件を定義することもできます。属性条件は、アサーション属性とターゲット属性をチェックする CEL 式です。特定の認証情報の属性条件が true と評価されると、認証情報が受け入れられます。それ以外の場合、認証情報は拒否されます。

ユースケースに適した属性マッピングと条件を選択するため、サービス ID とユーザー ID のどちらをマッピングするかを決める必要があります。

• サービス ID をマッピングすると、Google Cloud の外部で実行されるバックグラウンド アプリケーションまたは CI / CD パイプラインを有効にして、有効期間の短い Google Cloud の認証情報を取得できます。アプリケーションは、ユーザーの操作なしで、これらの認証情報を取得できます。
• ユーザー ID をマッピングすると、Google Cloud の外部で実行されているアプリケーションのユーザーが有効期間の短い Google Cloud の認証情報を取得できます。アプリケーションは、ユーザーに代わってこの認証情報を取得します。

サービス ID のマッピング

AWS

属性マッピングでは、ソース属性として GetCallerIdentity のレスポンス フィールドを使用できます。次のようなフィールドがあります。

• account: AWS アカウント番号が含まれます。
• arn: 外部エンティティの AWS ARN が含まれます。
• userid: 呼び出し元エンティティの一意の識別子が含まれます。

ロールが関連付けられた Amazon Elastic Compute Cloud（EC2）インスタンスでアプリケーションが実行されている場合は、次の属性マッピングを使用できます。

google.subject=assertion.arn
attribute.aws_role=assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn

このマッピングにより、特定の EC2 インスタンスにサービス アカウントの借用権限を付与できます。また、以下の ID を使用してロールごと付与することもできます。

特定の EC2 インスタンスへのアクセスを許可する:

principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/arn:aws:sts::ACCOUNT_ID:assumed-role/AWS_ROLE/AWS_ROLE_SESSION_NAME

ロールごとにアクセス権を付与する:

principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/arn:aws:sts::ACCOUNT_ID:assumed-role/AWS_ROLE

AWS アカウントに多くのユーザーとロールが含まれている場合がありますが、Google Cloud リソースへのアクセスが必要になるのはごく一部です。Workload Identity 連携を使用できるユーザーとロールのセットを制限するには、属性条件を使用します。たとえば、次の条件を使用すると、Google Cloud リソースへのアクセスを特定のアカウントに限定できます。

assertion.arn.startsWith('arn:aws:sts::ACCOUNT-ID:assumed-role/')

Azure

属性マッピングでは、ソース属性として Azure アクセス トークンに埋め込まれたクレーム（カスタム クレームを含む）を使用できます。

参照可能なクレームの完全なリストを取得するには、マネージド ID が割り当てられている Azure VM に接続し、次の操作を行います。

1. Azure Instance Metadata Service（IMDS）からアクセス トークンを取得します。

   Bash

   curl \
     "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" \
     -H "Metadata: true" | jq -r .access_token
   

   このコマンドは jq ツールを使用します。Cloud Shell では jq がデフォルトで使用されます。

   PowerShell

   $SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"
   $SubjectToken = (Invoke-RestMethod `
     -Uri "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" `
     -Headers @{Metadata="true"}).access_token
   Write-Host $SubjectToken
   

   APP_ID_URI は、Workload Identity 連携用に構成したアプリケーションのアプリケーション ID URI に置き換えます。

2. ウェブブラウザで https://jwt.ms/ に移動し、アクセス トークンをテキスト ボックスに貼り付けます。

3. アクセス トークンに埋め込まれたクレームのリストを表示するには、[Claims] をクリックします。

サービス プリンシパルで認証するには、次の属性マッピングを使用します。

google.subject=assertion.sub

マネージド ID に発行されたアクセス トークンの場合、sub クレームにマネージド ID のオブジェクト ID が含まれます。別のクレームを使用する場合は、そのクレームが一意であり、再割り当てできないことを確認してください。

サービス ID の場合は通常、google.groups やカスタム属性のマッピングを作成する必要はありません。

有効期間の短い Google Cloud の認証情報を取得できる ID を制限する場合は、属性条件を定義しないでください。代わりに、アプリロールの割り当てを使用するように Azure AD アプリケーションを構成します。

GitHub Actions

属性マッピングでは、OIDC トークンに埋め込まれたクレームをソース属性として使用できます。たとえば、次のようなものが挙げられます。

• sub: リポジトリ名と Git リファレンスが含まれます（例: repo:username/reponame:ref:refs/heads/master）。
• repository: オーナーとリポジトリ名が含まれます（例: username/reponame）。
• repository_owner: オーナー（ユーザー名または GitHub 組織の名前）が含まれます。
• ref: Git リファレンスが含まれます（refs/heads/main など）。

次の属性マッピングでは、google.subject を GitHub Actions OIDC トークンの sub クレームに設定します。sub クレームにはリポジトリ名と Git リファレンスの両方が含まれるため、このマッピングによりリポジトリとブランチによるアクセスを制御できます。

google.subject=assertion.sub

リポジトリとブランチによるアクセスの制御は、特定のブランチ（main など）が他のブランチ（機能ブランチなど）以外のリソースに対する異なるアクセスが必要な場合に役立ちます。

ブランチごとにアクセスを区別しない場合は、次の属性マッピングを使用します。これにより、google.subject が repository クレームに設定されます。

google.subject=assertion.repository

属性条件を使用して、ID トークンが満たさなければならない追加要件を定義することもできます。たとえば、次の条件では、Git ブランチ main を使用するワークフローの ID トークンへのアクセスを制限します。

assertion.ref=='refs/heads/main'

OIDC

属性マッピングでは、外部 ID プロバイダから発行された ID トークンまたはアクセス トークンに埋め込まれたクレームを使用できます。

ユーザーを一意に識別するため、これらのクレームのいずれかを google.subject にマッピングする必要があります。なりすましの脅威から保護するため、変更できない一意の値を持つクレームを選択します。

多くの ID プロバイダは、変更できない一意 ID を sub クレームに設定します。こうした ID プロバイダの場合は、sub クレームを google.subject にマッピングすることを検討してください。

google.subject=assertion.sub

email のようなクレームをこの目的で使用しないでください。通常、メールアドレスは再割り当てまたは変更が可能なため、ユーザーを一意に識別することはできません。

ID プロバイダに多くのユーザーが含まれている場合がありますが、Google Cloud リソースへのアクセスが必要になるのはごく一部です。Workload Identity 連携を使用できるユーザーと認証情報のセットを制限するために、属性条件を使用することもできます。

たとえば、次の条件では、値が true のカスタム service_account 要求を含むトークンにのみアクセスを許可します。

assertion.service_account==true

OIDC（AD FS）

属性マッピングでは、AD FS アクセス トークンに埋め込まれた要求をソース属性として使用できます。

アプリケーションの認証には、次の属性マッピングを使用できます。

google.subject=assertion.appid

このマッピングにより、google.subject が appid 要求の値に設定されます。この値には AD FS アプリケーションのクライアント ID が含まれます。

必要に応じて、属性条件を使用して、AD FS アクセス トークンが満たす必要のある追加要件を定義できます。たとえば、次の条件は、アプリケーションが AD FS への認証に IWA を使用する必要があることを定義します。

assertion.authmethod=='http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/windows'

有効期間が短い Google Cloud の認証情報を取得できるアプリケーションのリストを制御する場合は、属性条件を定義しないでください。代わりに、AD FS でクライアント権限を使用して、許可するアプリケーションを定義します。

SAML

属性マッピングでは、外部 ID プロバイダによって発行されたアサーションに埋め込まれた <Subject> 要素と <Attribute> 要素を使用できます。SAML 属性は、次のキーワードを使用して参照できます。

• assertion.subject には、<Subject> 要素にある認証済みユーザーの NameID が含まれます。
• assertion.attributes['ATTRIBUTE_NAME'] には、同じ名前の <Attribute> の値のリストが格納されています。

ユーザーを一意に識別するため、これらのクレームのいずれかを google.subject にマッピングする必要があります。なりすましの脅威から保護するため、変更できない一意の値を持つクレームを選択します。

多くの ID プロバイダは、変更できない一意 ID を NameId に設定します。こうした ID プロバイダの場合は、NameId 属性を google.subject にマッピングすることを検討してください。

google.subject=assertion.subject

この目的で http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress のような属性を使用しないでください。通常、メールアドレスは再割り当てまたは変更が可能なため、ユーザーを一意に識別することはできません。

ID プロバイダに多くのユーザーが含まれている場合がありますが、Google Cloud リソースへのアクセスが必要になるのはごく一部です。Workload Identity 連携を使用できるユーザーと認証情報のセットを制限するために、属性条件を使用することもできます。

たとえば、次の条件は、値が true のカスタム https://example.com/SAML/Attributes/AllowGcpFederation 属性を含むアサーションへのアクセスを制限します。

assertion.attributes['https://idp.com/SAML/Attributes/AllowGcpFederation'][0]=='true'

SAML（AD FS）

このガイドですでに説明したとおり、属性マッピングでは、AD FS によって発行されたアサーションに埋め込まれた要求を使用できます。

次のマッピングを使用して、Workload Identity 連携で SAML アサーションの名前 ID 要求を使用してユーザーを一意に識別するようにします。

google.subject=assertion.subject

SAML アサーションに要求を含めるように要求発行ポリシーを構成している場合は、別のマッピングを追加できます。例:

google.groups=assertion.attributes['http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid']
attribute.userip=['http://schemas.microsoft.com/2014/09/requestcontext/claims/userip'][0]

必要に応じて、すべての SAML アサーションが満たさなければならない属性条件を使用できます。たとえば、次の条件は、特定のグループ メンバーシップ要求が含まれる SAML アサーションのみを許可します。

"S-1-5-6" in google.groups

Workload Identity のプールとプロバイダを作成する

これで、Workload Identity プールとプロバイダの作成に必要な情報がすべて収集されました。

コンソール

1. Google Cloud コンソールで、[新しいワークロード プロバイダとプール] ページに移動します。

   [新しいワークロード プロバイダとプール] に移動

2. [ID プールを作成] に、次のように入力します。

   • 名前: プールの名前。この名前はプール ID としても使用されます。プール ID を後で変更することはできません。
   • 説明: プールの目的を説明するテキスト。

3. [続行] をクリックします。

4. [プロバイダの選択] プルダウン リストでプロバイダを選択します。

   • AWS: AWS と連携している場合。
   • OpenID Connect（OIDC）: Azure、GitHub Actions、または別の OIDC 互換プロバイダと連携している場合。
   • Google Cloud コンソールを使用して SAML 2.0 ID プロバイダから Workload Identity 連携を構成することはできません。SAML 2.0 ID プロバイダから Workload Identity 連携を構成するには、gcloud CLI を使用する必要があります。

5. [プロバイダの詳細] で、ID プロバイダの詳細を入力します。

   AWS

   • プロバイダ名: プロバイダの名前。この名前はプロバイダ ID としても使用されます。プロバイダ ID は後から変更できません。

   Azure

   • プロバイダ名: プロバイダの名前。この名前はプロバイダ ID としても使用されます。プロバイダ ID は後から変更できません。
   • 発行元 URL: https://sts.windows.net/TENANT_ID。ここで TENANT_ID は、Azure AD テナントのテナント ID（GUID）です。
   • 許可された対象: Azure AD でアプリケーションを登録したときに使用したアプリケーション ID URI。

   GitHub Actions

   • プロバイダ名: プロバイダの名前。この名前はプロバイダ ID としても使用されます。プロバイダ ID は後から変更できません。
   • 発行元 URL: https://token.actions.githubusercontent.com/

   OIDC

   • プロバイダ名: プロバイダの名前。この名前はプロバイダ ID としても使用されます。プロバイダ ID は後から変更できません。
   • 発行元 URL: ID プロバイダの発行元 URL。
   • 許可された対象: ID トークンの想定される対象。

   OIDC（AD FS）

   • プロバイダ名: プロバイダの名前。この名前はプロバイダ ID としても使用されます。プロバイダ ID は後から変更できません。
   • 発行元の URL: https://ADFS_DOMAIN/adfs。ここで、ADFS_DOMAIN は AD FS サーバーまたはファームのパブリック ドメイン名です。

6. [続行] をクリックします。

7. [プロバイダの属性を構成する] で、前に確認した属性マッピングを追加します。

8. [属性条件] で、前に確認した属性条件を入力します。属性条件がない場合は、空白のままにします。

9. [保存] をクリックして、Workload Identity のプールとプロバイダを作成します。

gcloud

1. 新しい Workload Identity プールを作成します。

   gcloud iam workload-identity-pools create POOL_ID \
       --location="global" \
       --description="DESCRIPTION" \
       --display-name="DISPLAY_NAME"
   

   次の値を置き換えます。

   • POOL_ID: プールの一意の ID。
   • DISPLAY_NAME: プールの名前。
   • DESCRIPTION: プールの説明。この説明は、プール ID へのアクセス権を付与するときに表示されます。

2. Workload Identity プールのプロバイダを追加します。

   AWS

   gcloud iam workload-identity-pools providers create-aws PROVIDER_ID \
     --location="global"  \
     --workload-identity-pool="POOL_ID" \
     --account-id="AWS_ACCOUNT_ID" \
     --attribute-mapping="MAPPINGS" \
     --attribute-condition="CONDITIONS"
   

   次の値を置き換えます。

   • PROVIDER_ID: プロバイダの一意の ID。
   • POOL_ID: プールの ID。
   • AWS_ACCOUNT_ID: AWS アカウントを識別する 12 桁の番号。
   • MAPPINGS: 前に確認した属性マッピングのカンマ区切りリスト。
   • CONDITIONS: 前に確認した属性条件。属性条件がない場合は、パラメータを削除します。

   例:

   gcloud iam workload-identity-pools providers create-aws example-provider \
     --location="global"  \
     --workload-identity-pool="pool-1" \
     --account-id="123456789000" \
     --attribute-mapping="google.subject=assertion.arn"
   

   Azure

   gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --issuer-uri="https://sts.windows.net/TENANT_ID" \
       --allowed-audiences="APPLICATION_ID_URI" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   次の値を置き換えます。

   • PROVIDER_ID: プロバイダの一意の ID。
   • POOL_ID: プールの ID。
   • TENANT_ID: Azure AD テナントのテナント ID（GUID）。
   • APPLICATION_ID_URI: Azure AD でアプリケーションを登録したときに使用したアプリケーション ID URI。
   • MAPPINGS: 前に確認した属性マッピングのカンマ区切りリスト。
   • CONDITIONS: 前に確認した属性条件。属性条件がない場合は、パラメータを削除します。

   例:

   gcloud iam workload-identity-pools providers create-oidc example-provider \
       --location="global" \
       --workload-identity-pool="pool-1" \
       --issuer-uri="https://sts.windows.net/00000000-1111-2222-3333-444444444444" \
       --allowed-audiences="api://my-app" \
       --attribute-mapping="google.subject=assertion.sub,google.groups=assertion.groups"
   

   GitHub Actions

   gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --issuer-uri="https://token.actions.githubusercontent.com/" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   次の値を置き換えます。

   • PROVIDER_ID: プロバイダの一意の ID。
   • POOL_ID: プールの ID。
   • OWNER: リポジトリを所有するユーザーまたは組織の名前。
   • REPOSITORY: リポジトリの名前。
   • MAPPINGS: 前に確認した属性マッピングのカンマ区切りリスト。
   • CONDITIONS: 前に確認した属性条件。属性条件がない場合は、パラメータを削除します。

   OIDC

   gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --issuer-uri="ISSUER" \
       --allowed-audiences="AUDIENCE" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   次の値を置き換えます。

   • PROVIDER_ID: プロバイダの一意の ID。
   • POOL_ID: プールの ID。
   • ISSUER: OIDC メタデータで定義されている発行元 URI。
   • AUDIENCE: ID トークンに想定されるオーディエンス。多くのプロバイダでは、オーディエンスがクライアント ID と一致しています。
   • MAPPINGS: 前に確認した属性マッピングのカンマ区切りリスト。
   • CONDITIONS: 前に確認した属性条件。属性条件がない場合は、パラメータを削除します。

   OIDC（AD FS）

   gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --issuer-uri="https://ADFS_DOMAIN/adfs" \
       --allowed-audiences="RELYING_PARTY_ID" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   次の値を置き換えます。

   • POOL_ID: プールの ID。
   • ADFS_DOMAIN: AD FS サーバーまたはファームのパブリック ドメイン名。
   • RELYING_PARTY_ID: AD FS 内の Workload Identity 連携プール用のウェブ API アプリケーションの証明書利用者 ID。このパラメータは、カスタムの証明書利用者 ID を使用する場合にのみ必要です。
   • MAPPINGS: 前に確認した属性マッピングのカンマ区切りリスト。
   • CONDITIONS: 前に確認した属性条件。属性条件がない場合は、パラメータを削除します。

   注: 属性マッピングと属性条件で、= と , の前後にあるスペースを削除します。

   SAML

   gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --idp-metadata-path="IDP_METADATA_PATH" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   次の値を置き換えます。

   • POOL_ID: プールの ID。
   • IDP_METADATA_PATH: SAML ID プロバイダの IdP メタデータ ドキュメントを取得するためのローカル ファイルパス。
   • MAPPINGS: 前に確認した属性マッピングのカンマ区切りリスト。
   • CONDITIONS: 前に確認した属性条件。属性条件がない場合は、パラメータを削除します。

   例:

   gcloud iam workload-identity-pools providers create-saml example-provider \
       --location="global" \
       --workload-identity-pool="pool-1" \
       --idp-metadata-path="/path/to/idp_metadata.xml" \
       --attribute-mapping="google.subject=assertion.subject,google.groups=assertion.attributes.groups"
   

   SAML（AD FS）

   curl -O https://DOMAIN/federationmetadata/2007-06/federationmetadata.xml
   
   gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --idp-metadata-path="federationmetadata.xml" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   次のように置き換えます。

   • DOMAIN: AD FS サーバーまたはサーバー ファームのドメイン名。
   • POOL_ID: プールの ID。
   • MAPPINGS: 前に確認した属性マッピングのカンマ区切りリスト。
   • CONDITIONS: 前に確認した属性条件。属性条件がない場合は、パラメータを削除します。

   例:

   gcloud iam workload-identity-pools providers create-saml example-provider \
       --location="global" \
       --workload-identity-pool="pool-1" \
       --idp-metadata-path="federationmetadata.xml" \
       --attribute-mapping=google.subject=assertion.subject"
   

注: 接頭辞 gcp- は予約されているため、プールやプロバイダ ID では使用できません。

次のステップ

• ID 連携を使用して有効期間の短い認証情報を取得する方法を確認する。
• Workload Identity 連携について確認する。
• Workload Identity プールとプロバイダの管理方法を学習する。