このページでは、Workforce Identity 連携に関する一般的な問題の解決方法について説明します。
IdP のレスポンスを検査する
このセクションでは、ID プロバイダ(IdP)からのレスポンスを調べて、このドキュメントに記載されている問題のトラブルシューティングを行う方法について説明します。
ブラウザベースのログイン
IdP から返されたレスポンスを調べるには、任意のツールを使用して HAR ファイルを生成します。たとえば、Google 管理者ツールボックスの HAR Analyzer を使用できます。ここでは、HAR ファイルの生成手順が示され、ファイルのアップロードと分析を行うためのツールが提供されます。
SAML
SAML IdP のレスポンスを検査するには、次の操作を行います。
- パス
/signin-callback
を含む URL に対して記録された HAR ファイルでSAMLResponse
リクエスト パラメータの値を見つけます。 - 任意のツールを使用してデコードします。たとえば、Google 管理者ツールボックスのエンコード / デコードを使用します。
OIDC
OIDC IdP のレスポンスを検査するには、次の操作を行います。
- パス
/signin-callback
を含む URL に対して記録された HAR ファイルでid_token
リクエスト パラメータを見つけます。 - 任意の JWT デバッグツールを使用してデコードします。
gcloud CLI
gcloud CLI の使用時に IdP からのレスポンスを検査するには、gcloud iam workforce-pools create-cred-config
コマンドを実行するときに --credential-source-file
フラグで渡したファイルの内容をコピーしてから、次の操作を行います。
SAML
任意のツールを使用して SAML IdP レスポンスをデコードします。たとえば、Google 管理者ツールボックスのエンコード / デコードを使用します。
OIDC
JWT デバッグツールを使用して、OIDC IdP レスポンスをデコードします。
ログを確認する
Google Cloud が IdP と通信しているかどうかを確認し、トランザクション情報を確認するには、Cloud Audit Logs のログを調べます。ログの例を確認するには、監査ログの例をご覧ください。
Workforce プールとプロバイダ管理のエラー
このセクションでは、プールとプロバイダの管理で発生する可能性のある一般的なエラーの修正方法について説明します。
権限の拒否
このエラーは、Workforce Identity 連携を構成しようとしているユーザーに IAM Workforce プール管理者(roles/iam.workforcePoolAdmin
)のロールがない場合に発生します。
INVALID_ARGUMENT: OIDC ウェブ シングル サインオン構成がない
OIDC Workforce Identity プール プロバイダを作成するときに、web-sso-response-type
フィールドと web-sso-assertion-claims-behavior
フィールドが設定されていない場合、次のエラーが発生します。
ERROR: (gcloud.iam.workforce-pools.providers.create-oidc) INVALID_ARGUMENT: Missing OIDC web single sign-on config.
このエラーを解決するには、OIDC Workforce Identity プール プロバイダを作成するとき、プロバイダの作成セクションの手順に沿ってそれらのフィールドを適切に設定します。
レート制限を超えました。しばらくしてからもう一度お試しください
このエラーは、Workforce プールリソースの割り当て上限に達した場合に発生します。割り当ての増加をリクエストするには、Google Cloud アカウント担当者にお問い合わせください。
ログインエラー
このセクションでは、Workforce Identity 連携のユーザーがログインするときに発生する可能性がある一般的なエラーの修正方法について説明します。
一般的なログインエラー
指定された認証情報が属性条件によって拒否されました
このエラーは、Workforce Identity プール プロバイダに設定されている属性条件を満たしていない場合に発生します。
たとえば、次の属性条件について考えてみましょう。
SAML
'gcp-users' in assertion.attributes.groups
OIDC
'gcp-users' in assertion.groups
この場合、ID プロバイダ(IdP)によって groups
属性で送信されたグループのリストに gcp-users
が含まれていないと、このエラーが表示されます。
このエラーを解決するには、次の操作を行います。
ログインに使用したプロバイダを指定して、
attributeCondition
が正しいことを確認します。条件でサポートされているオペレーションについては、言語の定義をご覧ください。IdP のレスポンスを検査するの手順に沿って、IdP から返される属性を確認し、属性条件が正しい形式で正確であることを確認します。
IdP の管理コンソールにログインし、属性条件で参照されている IdP 属性が正しく設定されているかどうかを確認します。必要に応じて、IdP のドキュメントをご覧ください。
マッピングされた属性は STRING 型である必要がある
このエラーは、SAML Workforce Identity プール プロバイダで、エラー メッセージで指定される属性に単一値の STRING 型を想定しているが、属性マッピングのリストにマッピングされている場合に発生します。
たとえば、属性マッピングに 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
この問題を解決するには、次の操作を行います。
ログインに使用したプロバイダを指定して、
attributeMapping
に設定されている IdP 属性を特定します。この属性をエラー メッセージに表示されている属性と比較します。前の例では、userRole
という IdP 属性がrole
属性にマッピングされ、role
属性が上記のエラーサンプルに表示されます。以下のガイダンスに沿って、属性マッピングを更新します。
エラーの原因となる属性がリスト値の場合は、代替の安定した文字列値の属性を見つけます。次に、最初の項目を参照して属性マッピングを更新します。上記の例では、
myRole
が代替の単一値の IdP 属性として識別されると、属性マッピングは次のようになります。attribute.role=assertion.attributes.myRole[0]
または、属性が単一値であることがわかっている場合は、リストの最初の項目を使用するように属性マッピングを更新します。前述の例で、
userRole
にロールが 1 つしかない場合は、次のマッピングを使用できます。attribute.role=assertion.attributes.userRole[0]
リストから単一値で安定した識別子を取得するには、言語の定義を参照し、それに応じて属性マッピングを更新します。
IdP から返されるレスポンスを確認するには、IdP のレスポンスを検査するセクションをご覧ください。
指定された認証情報から google.subject の値を取得できない
このエラーは、Workforce Identity プール プロバイダの構成に設定した属性マッピングを使用して、必要なクレーム google.subject
がマッピングされなかった場合に発生します。
このエラーを解決するには、次の操作を行います。
プロバイダの説明を取得し、
attributeMapping
を検査します。google.subject
に構成されているマッピングを特定します。マッピングが正しくない場合は、Workforce Identity プール プロバイダを更新します。IdP から返されるレスポンスを確認するには、IdP レスポンスを検査するセクションをご覧ください。属性マッピングで
google.subject
にマッピングされた IdP レスポンスの属性の値を検査します。値が空であるか、正しくない場合は、IdP の管理コンソールにログインして、構成されている属性を確認します。属性については、影響を受けるユーザーが IdP に対応するデータを持っているかどうかを確認してください。IdP の構成を更新して、属性またはユーザー情報を適宜修正します。
ログインを再試行します。
400 エラーが発生しました
このエラーは、リクエストが期待どおりに受信されなかったか、形式が正しくない場合に発生します。
このエラーを解決するには、次の操作を行います。
ログイン方法を通知するセクションの説明に従って、正しい手順でログインしていることを確認します。
Workforce Identity プール プロバイダの構成と IdP の構成を比較します。
OIDC ログインエラー
このセクションでは、Workforce Identity 連携のユーザーがログインするときに発生する可能性がある OIDC 固有のエラーの修正方法について説明します。
指定された認証情報の発行者への接続中にエラーが発生した
このエラーは、OIDC Workforce Identity プール プロバイダが OIDC ディスカバリ ドキュメントや JWKS URI に到達できない場合に発生します。
このエラーを解決するには、次の操作を行います。
プロバイダの説明を取得し、構成されている
issuerUri
を検査します。発行者 URI に/.well-known/openid-configuration
を追加して、ディスカバリ ドキュメントの URL を作成します。たとえば、issuerUri
がhttps://example.com
の場合、ディスカバリ ドキュメントの URL はhttps://example.com/.well-known/openid-configuration
になります。シークレット モードのブラウザ ウィンドウで、ディスカバリ ドキュメントの URL を開きます。
URL が開かない場合や、ブラウザに
404
エラーが表示される場合は、IdP のドキュメントを参照して、正しい発行者 URI を特定します。必要に応じて、Workforce Identity 連携プールのプロバイダのissuerUri
を更新します。IdP がオンプレミスで実行されている場合は、IdP のドキュメントを参照して、インターネット経由でアクセスできるようにプロビジョニングします。
URL が開いた場合は、次の条件を確認します。
- ディスカバリ ドキュメントを提供する前に、URL が過剰にリダイレクトされていないかどうかを確認します。その場合は、IdP の管理者に問い合わせて問題を解決してください。
- IdP のレスポンス時間を確認します。レスポンスのレイテンシを短縮するには、IdP 管理者に相談してください。
- 開いているディスカバリ ドキュメントは JSON 形式にする必要があります。
JSON で
jwks_uri
フィールドを探します。- 関連付けられた URL の値も開きます。
- このガイドの前半で説明したように、URL が条件を満たしていることを確認します。
ログインを再試行します。
SAML ログインエラー
このセクションでは、Workforce Identity 連携のユーザーがログインするときに発生する可能性がある SAML 固有のエラーの修正方法について説明します。
SAMLResponse の署名を検証できない
このエラーは、SAML Workforce Identity プール プロバイダで、Workforce Identity プール プロバイダに構成した IdP メタデータ XML で提供される X.509 証明書のどれを使用しても IdP レスポンスの署名を検証できない場合に発生します。このエラーの一般的な原因は、IdP で検証用の証明書はローテーションされたが、Workforce Identity プール プロバイダの構成が最新の IdP メタデータ XML ファイルを使用して更新していないことです。
このエラーを解決するには、次の操作を行います。
(省略可)IdP レスポンスを検査するの手順に沿って、IdP から返されたレスポンスを確認し、
X509Certificate
フィールドを見つけます。ログインに使用したプロバイダを指定し、Workforce Identity プール プロバイダに設定されたidpMetadataXml
内にあるX509Certificate
フィールドを調べます。証明書を IdP から返されたレスポンスに表示されているものと比較します。証明書は一致する必要があります。IdP の管理コンソールにログインし、最新のメタデータ XML をダウンロードします。
ダウンロードした IdP メタデータ XML で Workforce Identity プール プロバイダを更新します。
ログインを再試行します。
SAML アサーションの受信者が正しい ACS の URL に設定されていない
このエラーは、SAML Workforce Identity プール プロバイダで、IdP レスポンスの SubjectConfirmationData
タグの Recipient
フィールドの値が正しくない場合に発生します。
このエラーを解決するには、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 と一致しない
このエラーは、SAML Workforce Identity プール プロバイダで、IdP レスポンスの Response
タグの Destination
フィールドの値が正しくない場合に発生します。
このエラーを解決するには、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 アサーションのサブジェクトです(通常は、認証されているユーザー)。
IdP レスポンスを検査するの手順に沿って、IdP から返されるレスポンスと、それに設定されている NameID
を確認します。
すべての <AudienceRestriction>
に SAML RP のエンティティ ID を含める必要がある
このエラーは、IdP からの SAML レスポンスの AudienceRestriction
タグに、Workforce Identity プール プロバイダのエンティティ ID を表す値を持つ Audience
タグが設定されていない場合に発生します。
このエラーを解決するには、次の操作を行います。
SAML レスポンスで送信される
AudienceRestriction
タグでオーディエンスを構成する方法については、IdP のドキュメントをご覧ください。通常、IdP 構成でEntity ID
フィールドまたはAudience
フィールドを設定してオーディエンスを構成します。設定する必要があるSP Entity ID
値を確認するには、Workforce Identity プール プロバイダを作成するの SAML セクションをご覧ください。IdP 構成を更新したら、ログインを再試行します。
IdP レスポンスを検査するの手順に沿って、IdP から返されるレスポンスと、それに設定されている AudienceRestriction
を確認します。