Workforce Identity 連携のトラブルシューティング

このページでは、Workforce Identity 連携に関する一般的な問題の解決方法について説明します。

IdP のレスポンスを検査する

このセクションでは、ID プロバイダ（IdP）からのレスポンスを調べて、このドキュメントに記載されている問題のトラブルシューティングを行う方法について説明します。

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

IdP から返されたレスポンスを調べるには、任意のツールを使用して HAR ファイルを生成します。たとえば、Google 管理者ツールボックスの HAR Analyzer を使用できます。ここでは、HAR ファイルの生成手順が示され、ファイルのアップロードと分析を行うためのツールが提供されます。

重要: ユーザーに HAR ファイルをリクエストする場合は、送信前に HAR ファイルから個人を特定できる情報（PII）と Cookie をクリーンアップするようユーザーにリクエストしてください。

SAML

SAML IdP のレスポンスを検査するには、次の操作を行います。

1. パス /signin-callback を含む URL に対して記録された HAR ファイルで SAMLResponse リクエスト パラメータの値を見つけます。
2. 任意のツールを使用してデコードします。たとえば、Google 管理者ツールボックスのエンコード / デコードを使用します。

OIDC

OIDC IdP のレスポンスを検査するには、次の操作を行います。

1. パス /signin-callback を含む URL に対して記録された HAR ファイルで id_token リクエスト パラメータを見つけます。
2. 任意の JWT デバッグツールを使用してデコードします。

gcloud CLI

gcloud CLI の使用時に IdP からのレスポンスを検査するには、gcloud iam workforce-pools create-cred-config コマンドを実行するときに --credential-source-file フラグで渡したファイルの内容をコピーしてから、次の操作を行います。

SAML

任意のツールを使用して SAML IdP レスポンスをデコードします。たとえば、Google 管理者ツールボックスのエンコード / デコードを使用します。

OIDC

JWT デバッグツールを使用して、OIDC IdP レスポンスをデコードします。

Workforce プールとプロバイダ管理のエラー

このセクションでは、プールとプロバイダの管理で発生する可能性のある一般的なエラーの修正方法について説明します。

NOT_FOUND: メソッドが見つからない

Workforce プールまたはプロバイダの管理で gcloud CLI コマンドを実行するときに、billing/quota_project が Workforce Identity 連携にアクセスできないと、次のエラーが発生します。

ERROR: (gcloud.iam.workforce-pools.providers.create-oidc) NOT_FOUND: Method not
found.

このエラーを解決するには、始める前にセクションの手順に沿って操作し、次に、失敗したコマンドを再実行します。

ログインエラー

このセクションでは、Workforce Identity 連携のユーザーがログインするときに発生する可能性がある一般的なエラーの修正方法について説明します。

一般的なログインエラー

指定された認証情報が属性条件によって拒否されました

このエラーは、Workforce Identity プール プロバイダに設定されている属性条件を満たしていない場合に発生します。

たとえば、次の属性条件について考えてみましょう。

SAML

'gcp-users' in assertion.attributes.groups

OIDC

'gcp-users' in assertion.groups

この場合、ID プロバイダ（IdP）によって groups 属性で送信されたグループのリストに gcp-users が含まれていないと、このエラーが表示されます。

このエラーを解決するには、次の操作を行います。

1. ログインに使用したプロバイダを指定して、attributeCondition が正しいことを確認します。条件でサポートされているオペレーションについては、言語の定義をご覧ください。

2. IdP のレスポンスを検査するの手順に沿って、IdP から返される属性を確認し、属性条件が正しい形式で正確であることを確認します。

3. IdP の管理コンソールにログインし、属性条件で参照されている IdP 属性が正しく設定されているかどうかを確認します。必要に応じて、IdP のドキュメントをご覧ください。

マッピングされた属性は STRING 型である必要があります

このエラーは、エラー メッセージで指定された属性に単一値の STRING 型が想定されているときに、この属性が属性マッピングのリストにマッピングされている場合に、SAML Workforce Identity 連携プール プロバイダで発生します。

たとえば、属性マッピング attribute.role=assertion.attributes.userRole を持つ SAML Workforce Identity 連携プール プロバイダについて考えてみましょう。以下の例に示すように、SAML アサーションでは、Attribute に複数の AttributeValue タグを設定できます。したがって、すべての SAML 属性はリストと見なされるため、assertion.attributes.userRole はリストとなります。

<saml:Attribute Name="userRole">
    <saml:AttributeValue>
      security-admin
    </saml:AttributeValue>
    <saml:AttributeValue>
      user
    </saml:AttributeValue>
</saml:Attribute>

この例では、次のエラーが表示されます。

The mapped attribute 'attribute.role' must be of type STRING

この問題を解決するには、次の操作を行います。

1. ログインに使用したプロバイダを指定して、attributeMapping に設定されている IdP 属性を特定します。この属性をエラー メッセージに表示されている属性と比較します。前の例では、userRole という IdP 属性が role 属性にマッピングされ、role 属性が上記のエラーサンプルに表示されます。

2. 以下のガイダンスに沿って、属性マッピングを更新します。

   注: google.groups のみがリストを受け入れます。

   • エラーの原因となる属性がリスト値の場合は、代替の安定した文字列値の属性を見つけます。次に、最初の項目を参照して属性マッピングを更新します。上記の例では、myRole が代替の単一値の IdP 属性として識別されると、属性マッピングは次のようになります。

     attribute.role=assertion.attributes.myRole[0]
     

   • または、属性が単一値であることがわかっている場合は、リストの最初の項目を使用するように属性マッピングを更新します。前述の例で、userRole にロールが 1 つしかない場合は、次のマッピングを使用できます。

     attribute.role=assertion.attributes.userRole[0]
     

   • リストから単一値で安定した識別子を取得するには、言語の定義を参照し、それに応じて属性マッピングを更新します。

IdP から返されるレスポンスを確認するには、IdP のレスポンスを検査するセクションをご覧ください。

指定された認証情報から google.subject の値を取得できませんでした

このエラーは、Workforce Identity 連携プール プロバイダの構成で設定した属性マッピングを使用して、必要なクレーム google.subject がマッピングされなかった場合に発生します。

このエラーを解決するには、次の操作を行います。

1. プロバイダの説明を取得し、attributeMapping を検査します。google.subject に構成されているマッピングを特定します。マッピングが正しくない場合は、Workforce Identity 連携プールのプロバイダを更新します。

2. IdP から返されるレスポンスを確認するには、IdP レスポンスを検査するセクションをご覧ください。属性マッピングで google.subject にマッピングされた IdP レスポンスの属性の値を検査します。

   値が空であるか、正しくない場合は、IdP の管理コンソールにログインして、構成されている属性を確認します。属性については、影響を受けるユーザーが IdP に対応するデータを持っているかどうかを確認してください。IdP の構成を更新して、属性またはユーザー情報を適宜修正します。

3. ログインを再試行します。

400 エラーが発生しました

このエラーは、リクエストが期待どおりに受信されなかったか、形式が正しくない場合に発生します。

このエラーを解決するには、次の操作を行います。

1. ログイン方法を通知するセクションの説明に従って、正しい手順でログインしていることを確認します。

2. Workforce Identity 連携プール プロバイダの構成と IdP の構成を比較します。

OIDC ログインエラー

このセクションでは、Workforce Identity 連携のユーザーがログインするときに発生する可能性がある OIDC 固有のエラーの修正方法について説明します。

指定された認証情報の発行者への接続中にエラーが発生しました

このエラーは、OIDC Workforce Identity 連携プールのプロバイダが OIDC ディスカバリ ドキュメントまたは JWKS URI に到達できない場合に発生します。

このエラーを解決するには、次の操作を行います。

1. プロバイダの説明を取得し、構成されている issuerUri を検査します。発行者 URI に /.well-known/openid-configuration を追加して、ディスカバリ ドキュメントの URL を作成します。たとえば、issuerUri が https://example.com の場合、ディスカバリ ドキュメントの URL は https://example.com/.well-known/openid-configuration になります。

2. シークレット モードのブラウザ ウィンドウで、ディスカバリ ドキュメントの URL を開きます。

   1. URL が開かない場合や、ブラウザに 404 エラーが表示される場合は、IdP のドキュメントを参照して、正しい発行者 URI を特定します。必要に応じて、Workforce Identity 連携プールのプロバイダの issuerUri を更新します。

      IdP がオンプレミスで実行されている場合は、IdP のドキュメントを参照して、インターネット経由でアクセスできるようにプロビジョニングします。

   2. URL が開いた場合は、次の条件を確認します。

      1. ディスカバリ ドキュメントを提供する前に、URL が過剰にリダイレクトされていないかどうかを確認します。その場合は、IdP の管理者に問い合わせて問題を解決してください。
      2. IdP のレスポンス時間を確認します。レスポンスのレイテンシを短縮するには、IdP 管理者に相談してください。
      3. 開いているディスカバリ ドキュメントは JSON 形式にする必要があります。

      4. JSON で jwks_uri フィールドを探します。

         1. 関連付けられた URL の値も開きます。
         2. このガイドの前半で説明したように、URL が条件を満たしていることを確認します。

   3. ログインを再試行します。

SAML ログインエラー

このセクションでは、Workforce Identity 連携のユーザーがログインするときに発生する可能性がある SAML 固有のエラーの修正方法について説明します。

SAMLResponse の署名を検証できませんでした

このエラーは、Workforce Identity 連携プール プロバイダで構成した IdP メタデータ XML に含まれる X.509 証明書を使用しても IdP レスポンスの署名を検証できない場合に、SAML Workforce Identity 連携プール プロバイダで発生します。このエラーの一般的な原因は、IdP での確認用の証明書がローテーションされたものの、Workforce Identity 連携プール プロバイダの構成が最新の IdP メタデータ XML ファイルを使用して更新されていないことです。

このエラーを解決するには、次の操作を行います。

1. （省略可）IdP レスポンスを検査するの手順に沿って、IdP から返されたレスポンスを確認し、X509Certificate フィールドを見つけます。ログインに使用したプロバイダを指定し、Workforce Identity 連携プール プロバイダに設定された idpMetadataXml 値に存在する X509Certificate フィールドを調べます。証明書を IdP から返されたレスポンスに表示されているものと比較します。証明書は一致する必要があります。

2. IdP の管理コンソールにログインし、最新のメタデータ XML をダウンロードします。

3. ダウンロードした IdP メタデータ XML で Workforce Identity 連携プール プロバイダを更新します。

4. ログインを再試行します。

SAML アサーションの受信者が正しい ACS の URL に設定されていません

このエラーは、IdP レスポンスの SubjectConfirmationData タグの Recipient フィールドの値が正しくない場合に、SAML Workforce Identity 連携プール プロバイダで発生します。

このエラーを解決するには、IdP でリダイレクト URL を設定するに記載されているリダイレクト URL を使用するように、IdP の構成の Recipient URL / Redirect URL または同等のフィールドを更新して、ログインを再試行します。

IdP のレスポンスを検査するの手順で、IdP から返されたレスポンスを確認し、Recipient フィールドが正しいことを確認します。

たとえば、Workforce Identity 連携プール プロバイダ locations/global/workforcePools/example-pool/providers/example-provider の場合、リダイレクト URL を含む Recipient は、次のように IdP の SAML レスポンスに表示されます。

<SubjectConfirmationData Recipient="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

SAMLResponse の宛先が RP コールバック URL と一致しません

このエラーは、IdP レスポンスの Response タグの Destination フィールドの値が正しくない場合に、SAML Workforce Identity 連携プール プロバイダで発生します。

このエラーを解決するには、IdP でリダイレクト URL を設定するに記載のリダイレクト URL を使用するように、IdP の構成の Destination URL / Redirect URL または同等のフィールドを更新します。

IdP のレスポンスを検査するの手順で、IdP から返されたレスポンスを確認し、Destination フィールドが正しいことを確認します。

たとえば、Workforce Identity 連携プール プロバイダ locations/global/workforcePools/example-pool/providers/example-provider の場合、リダイレクト URL を含む Destination は、IdP の SAML レスポンスに次のように表示されます。

<Response Destination="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

無効なアサーション: NameID が欠落しているか、空です

このエラーは、IdP から受信した SAML レスポンスに NameId フィールドが含まれていないか、空の値の場合に発生します。

このエラーを解決するには、IdP のドキュメントを参照して、NameID を送信するように更新します。これは、SAML アサーションのサブジェクトです（通常は、認証されているユーザー）。

注: NameID は、属性マッピングで別の属性を google.subject にマッピングする場合でも必要です。

IdP レスポンスを検査するの手順に沿って、IdP から返されるレスポンスと、それに設定されている NameID を確認します。

すべての <AudienceRestriction> に SAML RP のエンティティ ID を含める必要があります

このエラーは、IdP からの SAML レスポンスの AudienceRestriction タグが、Workforce ID 連携プール プロバイダのエンティティ ID を表す値を Audience に設定していない場合に発生します。

このエラーを解決するには、次の操作を行います。

1. SAML レスポンスで送信される AudienceRestriction タグでオーディエンスを構成する方法については、IdP のドキュメントをご覧ください。通常、IdP 構成で Entity ID フィールドまたは Audience フィールドを設定してオーディエンスを構成します。設定する必要がある SP Entity ID 値を確認するには、Workforce Identity プール プロバイダを作成するの SAML セクションをご覧ください。

2. IdP 構成を更新したら、ログインを再試行します。

IdP レスポンスを検査するの手順に沿って、IdP から返されるレスポンスと、それに設定されている AudienceRestriction を確認します。