Microsoft Entra ID と多数のグループを使用して Workforce Identity 連携を構成する

このドキュメントでは、Microsoft Entra ID ID プロバイダ（IdP）を使用して Workforce Identity 連携を構成し、Microsoft Graph を使用して Microsoft Entra ID から Google Cloud に最大 400 個のグループをマッピングする方法について説明します。このドキュメントでは、これらのグループに IAM ロールを付与する方法と、グループのメンバーである Microsoft Entra ID ユーザーをGoogle Cloudにログインさせる方法について説明します。ユーザーは、IAM でアクセス権が付与され、Workforce Identity 連携をサポートする Google Cloud プロダクトにアクセスできます。

Microsoft Entra ID から Google Cloudにマッピングするグループが 150 未満の場合は、Microsoft Entra ID との Workforce Identity 連携を構成してユーザー ログインを行うをご覧ください。

このドキュメントで説明する方法は、次のプロトコルで使用できます。

  • 暗黙的フローを使用した OIDC
  • コードフローを使用した OIDC
  • SAML 2.0 プロトコル

Microsoft Entra ID アプリケーションがトークンで出力できるグループのメールアドレスの数は、SAML で 150、JWT で 200 に制限されています。この上限の詳細については、Microsoft Entra ID を使用してアプリケーションのグループ クレームを構成するをご覧ください。より多くのグループを取得するため、Workforce Identity 連携は Microsoft Identity の OAuth 2.0 クライアント認証情報フローを使用して認証情報を取得します。これにより、Workforce Identity 連携は Microsoft Graph API をクエリしてユーザーのグループを取得できます。

この方法を使用する大まかな手順は次のとおりです。

  • 新しい Microsoft Entra ID アプリケーションを作成するか、既存のアプリケーションを更新して、Microsoft Graph API からユーザーのグループ メンバーシップを取得します。Microsoft Graph が Microsoft Entra ID から大量のグループを取得する方法については、グループの超過をご覧ください。

  • Workforce Identity プール プロバイダを作成するときに、extra-attributes フラグを使用して、Microsoft Graph API からユーザーのグループ メールアドレスを取得するように Workforce Identity 連携を構成します。

Workforce Identity 連携は、Microsoft Graph API から最大 999 個のグループを取得できます。Microsoft Graph API が 999 を超えるグループを返すと、ログインは失敗します。

Microsoft Graph API から返されるグループの数を減らすには、Workforce Identity プール プロバイダを作成するときに --extra-attributes-filter フラグを使用して、Workforce Identity 連携のクエリを絞り込みます。

Workforce Identity 連携は、Microsoft Graph API からグループを取得した後、アクセス トークンを生成します。Workforce Identity 連携では、アクセス トークンに最大 400 個のグループを追加できます。グループ数を 400 個以下にするには、Workforce Identity プール プロバイダを作成するときに、Common Expression Language（CEL）式を含む属性マッピングを指定します。

始める前に

  1. Google Cloud 組織が設定されていることを確認します。

  2. After installing the Google Cloud CLI, configure the gcloud CLI to use your federated identity and then initialize it by running the following command: 

    gcloud init
  3. Microsoft Entra ID で、暗黙的フローに対して ID トークンが有効になっていることを確認します。詳細については、ID トークンの暗黙的付与を有効にするをご覧ください。
  4. ログインの場合、IdP は署名付き認証情報を提供する必要があります。OIDC IdP は JWT を提供し、SAML IdP レスポンスは署名されている必要があります。
  5. 組織またはGoogle Cloud プロダクトの変更に関する重要な情報を受け取るには、重要な連絡先を指定する必要があります。詳細については、Workforce Identity 連携の概要をご覧ください。
  6. マッピングするすべてのグループが、Microsoft Entra ID でセキュリティ グループとしてマークされている必要があります。

必要なロール

Workforce Identity 連携の構成に必要な権限を取得するには、組織に対する IAM Workforce プール管理者（roles/iam.workforcePoolAdmin）の IAM ロールを付与するように管理者に依頼します。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

本番環境ではなく、開発環境またはテスト環境で権限を構成する場合は、IAM オーナー（roles/owner）の基本ロールを付与できます。このロールには、Workforce Identity 連携の権限も含まれています。

Microsoft Entra ID アプリケーションを作成する

このセクションでは、Microsoft Entra 管理ポータルを使用して Microsoft Entra ID アプリケーションを作成する方法について説明します。また、既存のアプリケーションを更新することもできます。詳細については、Microsoft Entra ID エコシステムでアプリケーションを構築するをご覧ください。

Workforce Identity プールは、OIDC プロトコルと SAML プロトコルの両方を使用した連携をサポートしています。

OIDC

OIDC プロトコルを使用する Microsoft Entra ID アプリケーション登録を作成するには、次の操作を行います。

  1. Microsoft Entra 管理ポータルにログインします。

  2. [Identity] > [Applications] > [App registrations] に移動します。

  3. アプリケーション登録の構成を開始するには、次の操作を行います。

    1. [New registration] をクリックします。

    2. アプリケーションの名前を入力します。

    3. [Supported account types] で、オプションを選択します。

    4. [Redirect URI] セクションの [Select a platform] プルダウン リストで、[Web] を選択します。

    5. テキスト フィールドにリダイレクト URL を入力します。ログインに成功すると、この URL にリダイレクトされます。コンソール（連携）へのアクセスを構成する場合は、次の URL 形式を使用します。

      https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

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

      • WORKFORCE_POOL_ID: このドキュメントの後半で Workforce Identity プールを作成するときに使用する Workforce Identity プール ID（例: entra-id-oidc-pool）。

      • WORKFORCE_PROVIDER_ID: このドキュメントの後半で Workforce Identity プール プロバイダを作成するときに使用する Workforce Identity プール プロバイダ ID（例: entra-id-oidc-pool-provider）。

        ID の形式については、API ドキュメントのクエリ パラメータ セクションをご覧ください。

    6. アプリケーション登録を作成するには、[Register] をクリックします。

SAML

SAML プロトコルを使用する Microsoft Entra ID アプリケーション登録を作成するには、次の操作を行います。

  1. Microsoft Entra 管理ポータルにログインします。

  2. [Identity] > [Applications] > [App registrations] に移動します。

  3. エンタープライズ アプリケーションの構成を開始するには、次の操作を行います。

    1. [Single sign-on] > [Create your own application] をクリックします。

    2. アプリケーションの名前を入力します。

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

    4. [Single sign-on] > [SAML] に移動します。

    5. [基本的な SAML 構成] を次のように更新します。

      1. [Identifier (Entity ID)] フィールドに次の値を入力します。

        https://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

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

        • WORKFORCE_POOL_ID: このドキュメントの後半で Workforce Identity プールを作成するときに使用する Workforce Identity プール ID（例: entra-id-saml-pool）。

        • WORKFORCE_PROVIDER_ID: このドキュメントの後半で Workforce Identity プール プロバイダを作成するときに使用する Workforce Identity プール プロバイダ ID（例: entra-id-saml-pool-provider）。

          ID の形式については、API ドキュメントのクエリ パラメータ セクションをご覧ください。

      2. [Reply URL (Assertion Consumer Service URL)] フィールドに、リダイレクト URL を入力します。ログインに成功すると、この URL にリダイレクトされます。コンソール（連携）へのアクセスを構成する場合は、次の URL 形式を使用します。

        https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

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

        • WORKFORCE_POOL_ID: Workforce Identity プールの ID
        • WORKFORCE_PROVIDER_ID: Workforce Identity プロバイダの ID。

      3. IdP によるログインを有効にする場合は、[Relay State] フィールドを次の値に設定します。

        https://console.cloud.google/

      4. SAML アプリケーションの構成を保存するには、[Save] をクリックします。

Microsoft Entra ID で多数のグループを構成する

このセクションでは、OIDC プロトコルと SAML プロトコルを使用して、Microsoft Entra ID から Workforce Identity 連携に最大 400 個のグループをマッピングする方法について説明します。

OIDC 暗黙的フローを使用して Microsoft Entra ID で多数のグループを構成する

このセクションでは、暗黙的フローで OpenID Connect（OIDC）プロトコルを使用して、Microsoft Entra ID から Workforce Identity 連携に最大 400 個のグループをマッピングする方法について説明します。

Microsoft Entra ID アプリケーションを構成する

既存の Microsoft Entra ID アプリケーションを構成することも、新しいアプリケーションを作成することもできます。アプリケーションを構成するには、次の操作を行います。

  1. Microsoft Entra ID ポータルで、次の操作を行います。
    • 新しいアプリケーションを登録するには、新しいアプリケーションを登録するの手順に沿って操作してください。
    • 既存のアプリケーションを更新するには、次の操作を行います。
      • [Identity] > [Applications] > [Enterprise applications] に移動します。
      • 更新するアプリケーションを選択します。
  2. 証明書とシークレットの手順に沿って、アプリケーションに新しいクライアント シークレットを作成します。クライアント シークレットの値は 1 回しか表示されないため、必ず記録してください。

    作成または更新したアプリケーションの次の値をメモします。この値は、このドキュメントの後半で Workforce Identity プール プロバイダを構成するときに指定します。

    • Client ID
    • Issuer URI
    • Client Secret
    • Tenant ID

  3. Microsoft Entra ID グループを取得するには、Workload Identity 連携が Microsoft Graph API を使用して Microsoft Entra ID のユーザー情報にアクセスして、管理者の同意を付与できるように API 権限を追加します。Microsoft Entra ID で次の操作を行います。

    1. [API permissions] に移動します。
    2. [Add a Permission] をクリックします。
    3. [Microsoft API] を選択します。
    4. [Application permissions] を選択します。
    5. 検索フィールドに「User.ReadBasic.All」と入力します。
    6. [Add permissions] をクリックします。

    Microsoft Entra ID グループは、グループ オブジェクト ID として取得できます。メールが有効なグループの場合はグループのメールアドレスとして取得できます。

    グループをグループのメールアドレスとして取得する場合は、次の手順が必要です。

  4. Microsoft Entra ID グループをグループのメールアドレスとして取得する手順は次のとおりです。グループをグループ オブジェクト ID として取得する場合は、この手順をスキップします。
    1. 検索フィールドに「GroupMember.Read.All」と入力します。
    2. [Add permissions] をクリックします。
    3. ドメイン名の [Grant admin consent] をクリックします。
    4. 表示されたダイアログで [Yes] をクリックします。
    5. 前に作成または更新した Microsoft Entra ID アプリケーションの [Overview] ページに移動します。
    6. [Endpoints] をクリックします。

    発行元 URI は、パス /.well-known/openid-configuration を省略した OIDC メタデータ ドキュメントの URI です。

    たとえば、OIDC メタデータ ドキュメントが https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/.well-known/openid-configuration の場合、発行元 URI は https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/ です。

Workforce Identity プールを作成する

コンソール

Workforce Identity プールを作成するには、次の操作を行います。

  1. Google Cloud コンソールで、[Workforce Identity プール] ページに移動します。

    [Workforce Identity プール] に移動

  2. Workforce Identity プールの組織を選択します。Workforce Identity プールは、組織内のすべてのプロジェクトとフォルダで使用できます。

  3. [プールを作成] をクリックして、次の操作を行います。

    1. [名前] フィールドに、プールの表示名を入力します。プール ID は、入力した名前から自動的に取得され、[名前] フィールドの下に表示されます。プール ID を更新するには、プール ID の横にある [編集] をクリックします。

    2. 省略可: [説明] にプールの説明を入力します。

    3. [セッション継続時間] はデフォルトで設定されています。カスタムのセッション継続時間を入力するには、[編集] をクリックします。セッション継続時間は、この Workforce プールの Google Cloudアクセス トークン、コンソール（連携）ログイン セッション、gcloud CLI ログイン セッションの有効期間を決定します。継続時間は 15 分（900 秒）より長く、12 時間（43,200 秒）より短くする必要があります。セッション継続時間が設定されていない場合、デフォルトで 1 時間（3,600 秒）に設定されます。

    4. プールを有効な状態で作成するには、[有効なプール] がオンになっていることを確認します。

    5. Workforce Identity プールを作成するには、[次へ] をクリックします。

gcloud

Workforce Identity プールを作成するには、次のコマンドを実行します。

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization=ORGANIZATION_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --session-duration=SESSION_DURATION \
    --location=global

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

  • WORKFORCE_POOL_ID: Google Cloud Workforce プールを表す ID。ID の形式については、API ドキュメントのクエリ パラメータ セクションをご覧ください。
  • ORGANIZATION_ID: Workforce Identity プールの Google Cloud 組織の組織 ID。Workforce Identity プールは、組織内のすべてのプロジェクトとフォルダで使用できます。
  • DISPLAY_NAME: 省略可。Workforce Identity プールの表示名。
  • DESCRIPTION: 省略可。Workforce Identity プールの説明。
  • SESSION_DURATION: 省略可。セッション継続時間。この Workforce プールの Google Cloudアクセス トークン、コンソール（連携）ログイン セッション、gcloud CLI ログイン セッションの有効期間を決定します。継続時間は 15 分（900 秒）より長く、12 時間（43,200 秒）より短くする必要があります。セッション継続時間が設定されていない場合、デフォルトで 1 時間（3,600 秒）に設定されます。

OIDC 暗黙的フローの Workforce Identity プール プロバイダを構成する

OIDC Workforce Identity プール プロバイダを作成するには、次のコマンドを実行します。

gcloud iam workforce-pools providers create-oidc PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --location=global \
    --display-name=DISPLAY_NAME \
    --issuer-uri=ISSUER_URI \
    --client-id=CLIENT_ID \
    --attribute-mapping=ATTRIBUTE_MAPPING \
    --web-sso-response-type=id-token \
    --web-sso-assertion-claims-behavior=only-id-token-claims \
    --extra-attributes-issuer-uri=EXTRA_ATTRIBUTES_ISSUER_URI \
    --extra-attributes-client-id=EXTRA_ATTRIBUTES_CLIENT_ID \
    --extra-attributes-client-secret-value=EXTRA_ATTRIBUTES_CLIENT_SECRET \
    --extra-attributes-type=EXTRA_ATTRIBUTES_TYPE  \
    –-extra-attributes-filter=EXTRA_ATTRIBUTES_FILTER

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

  • PROVIDER_ID: 一意のプロバイダ ID。接頭辞 gcp- は予約されているため、プールやプロバイダ ID では使用できません。
  • WORKFORCE_POOL_ID: Workforce プール ID
  • DISPLAY_NAME: プロバイダの表示名。
  • ISSUER_URI: このドキュメントで作成した Microsoft Entra ID アプリケーションの発行元 URI。
  • CLIENT_ID: Microsoft Entra ID アプリケーションのクライアント ID。
  • ATTRIBUTE_MAPPING: Microsoft Entra ID から Google Cloudへの属性のマッピング。たとえば、Microsoft Entra ID の groups と subject をマッピングするには、次の属性マッピングを使用します。
    --attribute-mapping=”google.groups=assertion.groups, google.subject=assertion.sub"

    詳細については、属性のマッピングをご覧ください。

  • EXTRA_ATTRIBUTES_ISSUER_URI: Microsoft Entra ID アプリケーションの発行元 URI。
  • EXTRA_ATTRIBUTES_CLIENT_ID: Microsoft Entra ID アプリケーションのクライアント ID。
  • EXTRA_ATTRIBUTES_CLIENT_SECRET: Microsoft Entra ID アプリケーションの追加のクライアント シークレット。
  • EXTRA_ATTRIBUTES_TYPE: azure-ad-groups-mail を使用して、グループのメールアドレスを取得します。azure-ad-groups-id を使用して、グループの ID を取得します。
  • EXTRA_ATTRIBUTES_FILTER: 省略可。グループの Microsoft Graph API をクエリするときに使用されるフィルタ式。このパラメータを使用すると、IdP から取得されるグループ数が上限（999 グループ）を下回るようにすることができます。

    次の例では、メール ID に接頭辞 sales が付いているグループを取得します。

    –-extra-attributes-filter='"mail:sales"'

    次の式は、表示名に sales という文字列を含むグループを取得します。

    -–extra-attributes-filter='"displayName:sales”'

OIDC コードフローを使用して Microsoft Entra ID で多数のグループを構成する

このセクションでは、コードフローで OIDC プロトコルを使用して、Microsoft Entra ID から Workforce Identity 連携に最大 400 個のグループをマッピングする方法について説明します。

Microsoft Entra ID アプリケーションを構成する

既存の Microsoft Entra ID アプリケーションを構成することも、新しいアプリケーションを作成することもできます。アプリケーションを構成するには、次の操作を行います。

  1. Microsoft Entra ID ポータルで、次の操作を行います。
    • 新しいアプリケーションを登録するには、新しいアプリケーションを登録するの手順に沿って操作してください。
    • 既存のアプリケーションを更新するには、次の操作を行います。
      • [Identity] > [Applications] > [Enterprise applications] に移動します。
      • 更新するアプリケーションを選択します。
  2. 証明書とシークレットの手順に沿って、アプリケーションに新しいクライアント シークレットを作成します。クライアント シークレットの値は 1 回しか表示されないため、必ず記録してください。

    作成または更新したアプリケーションの次の値をメモします。この値は、このドキュメントの後半で Workforce Identity プール プロバイダを構成するときに指定します。

    • Client ID
    • Issuer URI
    • Client Secret
    • Tenant ID

  3. Microsoft Entra ID グループを取得するには、Workload Identity 連携が Microsoft Graph API を使用して Microsoft Entra ID のユーザー情報にアクセスして、管理者の同意を付与できるように API 権限を追加します。Microsoft Entra ID で次の操作を行います。

    1. [API permissions] に移動します。
    2. [Add a Permission] をクリックします。
    3. [Microsoft API] を選択します。
    4. [Delegated permissions] を選択します。
    5. 検索フィールドに「User.Read」と入力します。
    6. [Add permissions] をクリックします。

    Microsoft Entra ID グループは、グループ オブジェクト ID として取得できます。メールが有効なグループの場合はグループのメールアドレスとして取得できます。

    グループをグループのメールアドレスとして取得する場合は、次の手順が必要です。

  4. Microsoft Entra ID グループをグループのメールアドレスとして取得する手順は次のとおりです。グループをグループ オブジェクト ID として取得する場合は、この手順をスキップします。
    1. 検索フィールドに「GroupMember.Read.All」と入力します。
    2. [Add permissions] をクリックします。
    3. ドメイン名の [Grant admin consent] をクリックします。
    4. 表示されたダイアログで [Yes] をクリックします。
    5. 前に作成または更新した Microsoft Entra ID アプリケーションの [Overview] ページに移動します。
    6. [Endpoints] をクリックします。

    発行元 URI は、パス /.well-known/openid-configuration を省略した OIDC メタデータ ドキュメントの URI です。

    たとえば、OIDC メタデータ ドキュメントが https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/.well-known/openid-configuration の場合、発行元 URI は https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/ です。

Workforce Identity プールを作成する

コンソール

Workforce Identity プールを作成するには、次の操作を行います。

  1. Google Cloud コンソールで、[Workforce Identity プール] ページに移動します。

    [Workforce Identity プール] に移動

  2. Workforce Identity プールの組織を選択します。Workforce Identity プールは、組織内のすべてのプロジェクトとフォルダで使用できます。

  3. [プールを作成] をクリックして、次の操作を行います。

    1. [名前] フィールドに、プールの表示名を入力します。プール ID は、入力した名前から自動的に取得され、[名前] フィールドの下に表示されます。プール ID を更新するには、プール ID の横にある [編集] をクリックします。

    2. 省略可: [説明] にプールの説明を入力します。

    3. [セッション継続時間] はデフォルトで設定されています。カスタムのセッション継続時間を入力するには、[編集] をクリックします。セッション継続時間は、この Workforce プールの Google Cloudアクセス トークン、コンソール（連携）ログイン セッション、gcloud CLI ログイン セッションの有効期間を決定します。継続時間は 15 分（900 秒）より長く、12 時間（43,200 秒）より短くする必要があります。セッション継続時間が設定されていない場合、デフォルトで 1 時間（3,600 秒）に設定されます。

    4. プールを有効な状態で作成するには、[有効なプール] がオンになっていることを確認します。

    5. Workforce Identity プールを作成するには、[次へ] をクリックします。

gcloud

Workforce Identity プールを作成するには、次のコマンドを実行します。

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization=ORGANIZATION_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --session-duration=SESSION_DURATION \
    --location=global

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

  • WORKFORCE_POOL_ID: Google Cloud Workforce プールを表す ID。ID の形式については、API ドキュメントのクエリ パラメータ セクションをご覧ください。
  • ORGANIZATION_ID: Workforce Identity プールの Google Cloud 組織の組織 ID。Workforce Identity プールは、組織内のすべてのプロジェクトとフォルダで使用できます。
  • DISPLAY_NAME: 省略可。Workforce Identity プールの表示名。
  • DESCRIPTION: 省略可。Workforce Identity プールの説明。
  • SESSION_DURATION: 省略可。セッション継続時間。この Workforce プールの Google Cloudアクセス トークン、コンソール（連携）ログイン セッション、gcloud CLI ログイン セッションの有効期間を決定します。継続時間は 15 分（900 秒）より長く、12 時間（43,200 秒）より短くする必要があります。セッション継続時間が設定されていない場合、デフォルトで 1 時間（3,600 秒）に設定されます。

OIDC コードフローの Workforce Identity プール プロバイダを構成する

OIDC Workforce Identity プール プロバイダを作成するには、次のコマンドを実行します。

gcloud iam workforce-pools providers create-oidc PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --location=global \
    --display-name=DISPLAY_NAME \
    --issuer-uri=ISSUER_URI \
    --client-id=CLIENT_ID \
    --attribute-mapping=ATTRIBUTE_MAPPING \
    --web-sso-response-type=code \
    --web-sso-assertion-claims-behavior=merge-user-info-over-id-token-claims \
    --extra-attributes-issuer-uri=EXTRA_ATTRIBUTES_ISSUER_URI \
    --extra-attributes-client-id=EXTRA_ATTRIBUTES_CLIENT_ID \
    --extra-attributes-client-secret-value=EXTRA_ATTRIBUTES_CLIENT_SECRET \
    --extra-attributes-type=EXTRA_ATTRIBUTES_TYPE  \
    –-extra-attributes-filter=EXTRA_ATTRIBUTES_FILTER

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

  • PROVIDER_ID: 一意のプロバイダ ID。接頭辞 gcp- は予約されているため、プールやプロバイダ ID では使用できません。
  • WORKFORCE_POOL_ID: Workforce プール ID
  • DISPLAY_NAME: プロバイダの表示名。
  • ISSUER_URI: このドキュメントで作成した Microsoft Entra ID アプリケーションの発行元 URI。
  • CLIENT_ID: Microsoft Entra ID アプリケーションのクライアント ID。
  • ATTRIBUTE_MAPPING: Microsoft Entra ID から Google Cloudへの属性のマッピング。たとえば、Microsoft Entra ID の groups と subject をマッピングするには、次の属性マッピングを使用します。
    --attribute-mapping=”google.groups=assertion.groups, google.subject=assertion.sub"

    詳細については、属性のマッピングをご覧ください。

  • EXTRA_ATTRIBUTES_ISSUER_URI: Microsoft Entra ID アプリケーションの発行元 URI。
  • EXTRA_ATTRIBUTES_CLIENT_ID: Microsoft Entra ID アプリケーションのクライアント ID。
  • EXTRA_ATTRIBUTES_CLIENT_SECRET: Microsoft Entra ID アプリケーションの追加のクライアント シークレット。
  • EXTRA_ATTRIBUTES_TYPE: azure-ad-groups-mail を使用して、グループのメールアドレスを取得します。azure-ad-groups-id を使用して、グループの ID を取得します。
  • EXTRA_ATTRIBUTES_FILTER: 省略可。グループの Microsoft Graph API をクエリするときに使用されるフィルタ式。このパラメータを使用すると、IdP から取得されるグループ数が上限（999 グループ）を下回るようにすることができます。

    次の例では、メール ID に接頭辞 sales が付いているグループを取得します。

    –-extra-attributes-filter='"mail:sales"'

    次の式は、表示名に sales という文字列を含むグループを取得します。

    -–extra-attributes-filter='"displayName:sales”'

SAML 2.0 を使用して Microsoft Entra ID で多数のグループを構成する

このセクションでは、SAML 2.0 プロトコルを使用して、Microsoft Entra ID から Workforce Identity 連携に最大 400 個のグループをマッピングする方法について説明します。

Microsoft Entra ID アプリケーションを構成する

アプリケーションを構成するには、次の操作を行います。

  1. Microsoft Entra ID ポータルで、次の操作を行います。
    • 新しいアプリケーションを登録するには、新しいアプリケーションを登録するの手順に沿って操作してください。
    • 既存のアプリケーションを更新するには、次の操作を行います。
      • [Identity] > [Applications] > [Enterprise applications] に移動します。
      • 更新するアプリケーションを選択します。
  2. 証明書とシークレットの手順に沿って、アプリケーションに新しいクライアント シークレットを作成します。クライアント シークレットの値は 1 回しか表示されないため、必ず記録してください。

    作成または更新したアプリケーションの次の値をメモします。この値は、このドキュメントの後半で Workforce Identity プール プロバイダを構成するときに指定します。

    • Client ID
    • Issuer URI
    • Client Secret
    • Tenant ID

  3. Microsoft Entra ID グループを取得するには、Workload Identity 連携が Microsoft Graph API を使用して Microsoft Entra ID のユーザー情報にアクセスして、管理者の同意を付与できるように API 権限を追加します。Microsoft Entra ID で次の操作を行います。

    1. [API permissions] に移動します。
    2. [Add a Permission] をクリックします。
    3. [Microsoft API] を選択します。
    4. [Application permissions] を選択します。
    5. 検索フィールドに「User.ReadBasic.All」と入力します。
    6. [Add permissions] をクリックします。

    Microsoft Entra ID グループは、グループ オブジェクト ID として取得できます。メールが有効なグループの場合はグループのメールアドレスとして取得できます。

    グループをグループのメールアドレスとして取得する場合は、次の手順が必要です。

  4. Microsoft Entra ID グループをグループのメールアドレスとして取得する手順は次のとおりです。グループをグループ オブジェクト ID として取得する場合は、この手順をスキップします。
    1. 検索フィールドに「GroupMember.Read.All」と入力します。
    2. [Add permissions] をクリックします。
    3. ドメイン名の [Grant admin consent] をクリックします。
    4. 表示されたダイアログで [Yes] をクリックします。
    5. 前に作成または更新した Microsoft Entra ID アプリケーションの [Overview] ページに移動します。
    6. [Endpoints] をクリックします。

    発行元 URI は、パス /.well-known/openid-configuration を省略した OIDC メタデータ ドキュメントの URI です。

    たとえば、OIDC メタデータ ドキュメントが https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/.well-known/openid-configuration の場合、発行元 URI は https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/ です。

Workforce Identity プールを作成する

コンソール

Workforce Identity プールを作成するには、次の操作を行います。

  1. Google Cloud コンソールで、[Workforce Identity プール] ページに移動します。

    [Workforce Identity プール] に移動

  2. Workforce Identity プールの組織を選択します。Workforce Identity プールは、組織内のすべてのプロジェクトとフォルダで使用できます。

  3. [プールを作成] をクリックして、次の操作を行います。

    1. [名前] フィールドに、プールの表示名を入力します。プール ID は、入力した名前から自動的に取得され、[名前] フィールドの下に表示されます。プール ID を更新するには、プール ID の横にある [編集] をクリックします。

    2. 省略可: [説明] にプールの説明を入力します。

    3. [セッション継続時間] はデフォルトで設定されています。カスタムのセッション継続時間を入力するには、[編集] をクリックします。セッション継続時間は、この Workforce プールの Google Cloudアクセス トークン、コンソール（連携）ログイン セッション、gcloud CLI ログイン セッションの有効期間を決定します。継続時間は 15 分（900 秒）より長く、12 時間（43,200 秒）より短くする必要があります。セッション継続時間が設定されていない場合、デフォルトで 1 時間（3,600 秒）に設定されます。

    4. プールを有効な状態で作成するには、[有効なプール] がオンになっていることを確認します。

    5. Workforce Identity プールを作成するには、[次へ] をクリックします。

gcloud

Workforce Identity プールを作成するには、次のコマンドを実行します。

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization=ORGANIZATION_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --session-duration=SESSION_DURATION \
    --location=global

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

  • WORKFORCE_POOL_ID: Google Cloud Workforce プールを表す ID。ID の形式については、API ドキュメントのクエリ パラメータ セクションをご覧ください。
  • ORGANIZATION_ID: Workforce Identity プールの Google Cloud 組織の組織 ID。Workforce Identity プールは、組織内のすべてのプロジェクトとフォルダで使用できます。
  • DISPLAY_NAME: 省略可。Workforce Identity プールの表示名。
  • DESCRIPTION: 省略可。Workforce Identity プールの説明。
  • SESSION_DURATION: 省略可。セッション継続時間。この Workforce プールの Google Cloudアクセス トークン、コンソール（連携）ログイン セッション、gcloud CLI ログイン セッションの有効期間を決定します。継続時間は 15 分（900 秒）より長く、12 時間（43,200 秒）より短くする必要があります。セッション継続時間が設定されていない場合、デフォルトで 1 時間（3,600 秒）に設定されます。

SAML 2.0 の Workforce Identity プール プロバイダを構成する

SAML Workforce Identity プール プロバイダを作成するには、次のコマンドを実行します。

gcloud iam workforce-pools providers create-saml PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --location=global \
    --display-name=DISPLAY_NAME \
    --idp-metadata-path=XML_METADATA_PATH \
    --attribute-mapping=ATTRIBUTE_MAPPING \
    --extra-attributes-issuer-uri=EXTRA_ATTRIBUTES_ISSUER_URI \
    --extra-attributes-client-id=EXTRA_ATTRIBUTES_CLIENT_ID \
    --extra-attributes-client-secret-value=EXTRA_ATTRIBUTES_CLIENT_SECRET \
    --extra-attributes-type=EXTRA_ATTRIBUTES_TYPE  \
    –-extra-attributes-filter=EXTRA_ATTRIBUTES_FILTER

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

  • PROVIDER_ID: 一意のプロバイダ ID。接頭辞 gcp- は予約されているため、プールやプロバイダ ID では使用できません。
  • WORKFORCE_POOL_ID: Workforce プール ID
  • DISPLAY_NAME: プロバイダの表示名。
  • XML_METADATA_PATH: SAML 2.0 XML メタデータ ファイルのパス。
  • ATTRIBUTE_MAPPING: Microsoft Entra ID から Google Cloudへの属性のマッピング。たとえば、Microsoft Entra ID の groups と subject をマッピングするには、次の属性マッピングを使用します。
    --attribute-mapping=”google.groups=assertion.groups, google.subject=assertion.sub"

    詳細については、属性のマッピングをご覧ください。

  • EXTRA_ATTRIBUTES_ISSUER_URI: Microsoft Entra ID アプリケーションの発行元 URI。
  • EXTRA_ATTRIBUTES_CLIENT_ID: Microsoft Entra ID アプリケーションのクライアント ID。
  • EXTRA_ATTRIBUTES_CLIENT_SECRET: Microsoft Entra ID アプリケーションの追加のクライアント シークレット。
  • EXTRA_ATTRIBUTES_TYPE: azure-ad-groups-mail を使用して、グループのメールアドレスを取得します。azure-ad-groups-id を使用して、グループの ID を取得します。
  • EXTRA_ATTRIBUTES_FILTER: 省略可。グループの Microsoft Graph API をクエリするときに使用されるフィルタ式。このパラメータを使用すると、IdP から取得されるグループ数が上限（999 グループ）を下回るようにすることができます。

    次の例では、メール ID に接頭辞 sales が付いているグループを取得します。

    –-extra-attributes-filter='"mail:sales"'

    次の式は、表示名に sales という文字列を含むグループを取得します。

    -–extra-attributes-filter='"displayName:sales”'

グループに IAM ロールを付与する

このセクションでは、 Google Cloud リソースのグループにロールを付与します。Workforce Identity 連携のプリンシパル ID の詳細については、IAM ポリシーで Workforce プールユーザーを表すをご覧ください。

次の例では、Microsoft Entra ID グループ内のユーザーにストレージ管理者ロール（roles/storage.admin）を付与します。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role="roles/storage.admin" \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

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

  • PROJECT_ID: プロジェクト ID
  • WORKFORCE_POOL_ID: Workforce Identity プールの ID
  • GROUP_ID: グループ ID。Workforce Identity プール プロバイダの作成に使用された --extra-attributes-type の値によって異なります。
    • azure-ad-groups-mail: グループ ID はメールアドレスです（例: admin-group@altostrat.com）。
    • azure-ad-groups-id: グループ ID はグループの UUID です（例: abcdefgh-0123-0123-abcdef）。

ログインしてアクセスをテストする

このセクションでは、Workforce Identity プールユーザーとしてログインし、 Google Cloud リソースにアクセスできることを確認します。

ログイン

このセクションでは、連携ユーザーとしてログインし、Google Cloud リソースにアクセスする方法について説明します。

コンソール（連携）ログイン

Google Cloud Workforce Identity 連携コンソール（コンソール（連携））にログインするには、次の操作を行います。

  1. コンソール（連携）のログインページに移動します。

    コンソール（連携）に移動

  2. プロバイダ名を入力します。形式は次のとおりです。
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

    3. プロンプトが表示されたら、Microsoft Entra ID でユーザー認証情報を入力します。

    IdP 開始のログインを始める場合は、リレー URL に https://console.cloud.google/ を使用します。

gcloud CLI ブラウザベースのログイン

ブラウザベースのログインフローを使用して gcloud CLI にログインする方法は次のとおりです。

構成ファイルを作成する

ログイン構成ファイルを作成するには、次のコマンドを実行します。必要に応じて、--activate フラグを追加することで、このファイルを gcloud CLI のデフォルトとして有効にできます。その後、構成ファイルのパスを毎回指定しなくても gcloud auth login を実行できます。

gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE_PATH

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

  • WORKFORCE_POOL_ID: Workforce プール ID
  • PROVIDER_ID: プロバイダ ID
  • LOGIN_CONFIG_FILE_PATH: 指定した構成ファイルのパス（例: login.json）

このファイルには、gcloud CLI でブラウザベースの認証フローを有効にし、Workforce Identity プール プロバイダで構成された IdP にオーディエンスを設定するために使用するエンドポイントが含まれています。このファイルに機密情報は含まれていません。

出力は次のようになります。

{
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "auth_url": "https://auth.cloud.google/authorize",
  "token_url": "https://sts.googleapis.com/v1/oauthtoken",
  "token_info_url": "https://googleapis.com/v1/introspect",
}

gcloud auth login がこの構成ファイルを自動的に使用しないようにするには、gcloud config unset auth/login_config_file を実行して設定を解除します。

ブラウザベースの認証を使用してログインする

ブラウザベースのログイン認証を使用して認証するには、次のいずれかの方法を使用します。

  • 構成ファイルの作成時に --activate フラグを使用した場合、または gcloud config set auth/login_config_file で構成ファイルを有効にした場合、gcloud CLI は構成ファイルを自動的に使用します。

    gcloud auth login

  • 構成ファイルの場所を指定してログインするには、次のコマンドを実行します。

    gcloud auth login --login-config=LOGIN_CONFIG_FILE_PATH
  • 環境変数を使用して構成ファイルの場所を指定するには、CLOUDSDK_AUTH_LOGIN_CONFIG_FILE を構成パスに設定します。

ブラウザベースのログインを無効にする

ログイン構成ファイルの使用を停止するには、次の手順を行います。

  • 構成ファイルの作成時に --activate フラグを使用した場合、または gcloud config set auth/login_config_file で構成ファイルを有効にした場合は、次のコマンドを実行して設定を解除する必要があります。

    gcloud config unset auth/login_config_file
  • CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 環境変数が設定されている場合は、クリアします。

gcloud CLI ヘッドレス ログイン

gcloud CLI を使用して Microsoft Entra ID にログインする手順は次のとおりです。

OIDC

  1. ログイン リクエストを送信するの手順に沿って操作します。OIDC を使用して、Microsoft Entra ID でユーザーをアプリケーションにログインさせます。

  2. リダイレクト URL の id_token パラメータから ID トークンをコピーし、ローカルマシン上の安全な場所にあるファイルに保存します。後のステップで、PATH_TO_OIDC_ID_TOKEN をこのファイルのパスに設定します。

  3. 次のコマンドを実行して、この手順の後半の例に似た構成ファイルを生成します。

    gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-file=PATH_TO_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

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

    • WORKFORCE_POOL_ID: Workforce Identity プールの ID。
    • WORKFORCE_PROVIDER_ID: Workforce Identity プール プロバイダ ID。
    • PATH_TO_OIDC_ID_TOKEN: IdP トークンが保存されているファイルのパス。
    • WORKFORCE_POOL_USER_PROJECT: 割り当てと課金に使用されるプロジェクト番号または ID。プリンシパルには、このプロジェクトに対する serviceusage.services.use 権限が必要です。

    コマンドが完了すると、Microsoft Entra ID によって次の構成ファイルが作成されます。

    {
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS"
  }
}

  4. gcloud CLI を開き、次のコマンドを実行します。

    gcloud auth login --cred-file=PATH_TO_OIDC_CREDENTIALS

    PATH_TO_OIDC_CREDENTIALS は、前の手順の出力ファイルのパスに置き換えます。

    gcloud CLI は、認証情報を Security Token Service エンドポイントに透過的に送信します。これは、エンドポイントで一時的な Google Cloud アクセス トークンと交換されます。

    これで、Google Cloudに gcloud CLI コマンドを実行できるようになりました。

SAML

  1. Microsoft Entra ID アプリケーションにユーザーをログインさせ、SAML レスポンスを取得します。

  2. Microsoft Entra ID から返された SAML レスポンスをローカルマシンの安全な場所に保存し、次のようにパスを保存します。

    SAML_ASSERTION_PATH=SAML_ASSERTION_PATH

  3. 次のコマンドを実行して、認証情報の構成ファイルを生成します。

    gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --credential-source-file=SAML_ASSERTION_PATH  \
    --workforce-pool-user-project=PROJECT_ID  \
    --output-file=config.json

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

    • WORKFORCE_PROVIDER_ID: このガイドの前半で作成した Workforce Identity プール プロバイダの ID。
    • WORKFORCE_POOL_ID: このガイドの前半で作成した Workforce Identity プールの ID。
    • SAML_ASSERTION_PATH: SAML アサーション ファイルのパス
    • PROJECT_ID: プロジェクト ID

    生成された構成ファイルは次のようになります。

    {
   "type": "external_account",
   "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
   "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
   "token_url": "https://sts.googleapis.com/v1/token",
   "credential_source": {
     "file": "SAML_ASSERTION_PATH"
   },
   "workforce_pool_user_project": "PROJECT_ID"
}

  4. Workforce Identity 連携のトークン交換を使用して gcloud CLI にログインするには、次のコマンドを実行します。

    gcloud auth login --cred-file=config.json

    gcloud CLI は、Microsoft Entra ID の認証情報を一時的な Google Cloud アクセス トークンと透過的に交換します。アクセス トークンを使用すると、 Google Cloudにアクセスできます。

    次のような出力が表示されます。

    Authenticated with external account user credentials for:
[principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/USER_ID].

  5. 認証されたアカウントとアクティブなアカウントを一覧表示するには、次のコマンドを実行します。

    gcloud auth list

テストアクセス

これで、Workforce Identity 連携をサポートし、アクセス権が付与されている Google Cloud プロダクトにアクセスできるようになりました。このドキュメントの前半で、プロジェクト TEST_PROJECT_ID の gcloud projects add-iam-policy-binding で指定したグループ ID 内のすべての ID にストレージ管理者ロール（roles/storage.admin）を付与しました。

ここでは、Cloud Storage バケットを一覧取得して、そのバケットにアクセスできるかどうかをテストします。

コンソール（連携）

コンソール（連携）を使用してアクセス権があることを確認するには、次の操作を行います。

  • Cloud Storage ページに移動します。

    [Cloud Storage] に移動

  • TEST_PROJECT_ID の既存バケットの一覧が表示できることを確認します。

gcloud CLI

gcloud CLI を使用してアクセス権があることを確認するには、アクセス権のあるプロジェクトの Cloud Storage バケットとオブジェクトを一覧取得します。これを行うには、次のコマンドを実行します。プリンシパルには、指定したプロジェクトに対する serviceusage.services.use 権限が必要です。

gcloud storage ls --project="TEST_PROJECT_ID"

ユーザーを削除する

Workforce Identity 連携は、連携ユーザー ID のユーザー メタデータとリソースを作成します。IdP でユーザーを削除する場合は、 Google Cloudでこれらのリソースも明示的に削除する必要があります。詳しくは、Workforce Identity 連携ユーザーとそのデータを削除するをご覧ください。

削除されたユーザーにリソースが引き続き関連付けられていることがあります。これは、ユーザーのメタデータとリソースの削除には長時間実行オペレーションが必要になるためです。ユーザー ID の削除を開始した後、削除前にユーザーが開始したプロセスは、プロセスが完了するかキャンセルされるまで引き続き実行されます。

次のステップ