SAMLのトラブルシューティング

このページには、使用中に遭遇する可能性のある問題の解決策が記載されています：

SAML デバッグツール

SAML 応答は base64 エンコードされているため、その場でデコードするには、以下のブラウザ・プラグインを推奨します：

特に注意してください：

  • NameID は、どのユーザーがサインインしているかを識別するために使用します。ユーザーが以前にサインインしたことがある場合は、保存した値と一致しなければなりません。
  • X509Certificate ：応答署名を検証するために必要。
  • SubjectConfirmation とConditionsは、設定を誤るとエラーを引き起こす可能性があります。

SAML レスポンスの生成

SAML 応答を使用すると、ID プロバイダを使用してサインインを試行する際に、アサーション・リストで送 信される属性名と値をプレビューできます。

SAML 応答を生成するには、以下の手順に従います：

  1. ブラウザ・デバッグ・ツールのいずれかをインストールします。
  2. 新しいブラウザのタブを開きます。
  3. SAML トレーサ・コンソールを開きます：
    • Chrome を開きます：Chrome： ページのコンテキスト・メニューで「Inspect」を選択し、開いた開発者コンソールで「SAML」タブを選択します。
    • Firefox： ブラウザのツールバーにある SAML トレーサ・アイコンを選択します：ブラウザのツールバーにある SAML-tracer アイコンを選択します。
  4. SAMLトレーサーを開いたまま、同じブラウザタブでグループのGitLabシングルサインオンURLにアクセスします。
  5. Authorizeを選択するか、サインインを試みます。トレーサーコンソールに、この例の SAML レスポンスのような SAML レスポンスが表示されます。
  6. SAML トレーサ内でExporterアイコンを選択して、応答を JSON 形式で保存します。

GitLab SAML のテスト

SAMLのトラブルシューティングには、以下のいずれかを使用できます：

設定の確認

便宜上、サポート・チームが使用するリソースの例を示します。これらのリソースは、SAML アプリの設定を確認するのに役立ちますが、サードパーティ製品の現在の状態を反映することを保証するものではありません。

フィンガープリントの計算

idp_cert_fingerprint を使用する場合は、SHA1 フィンガープリントである必要があります。SHA1 フィンガープリントを計算するには、証明書ファイルをダウンロードして実行します：

openssl x509 -in <filename.crt> -noout -fingerprint -sha1

filename.crt を証明書ファイル名に置き換えます。

SAML レスポンスの Rails ログの検索

Base64エンコードされたSAMLレスポンスは、production_json.log。このレスポンスはIDプロバイダから送信され、GitLabが消費するユーザー情報を含んでいます。SAML インテグレーションにおける多くのエラーは、このレスポンスをデコードして GitLab 設定ファイルの SAML 設定と比較することで解決できます。

例えば、グループ用のSAMLでは、以下のフィルタで検索することで、base64エンコードされたSAMLレスポンスを見つけることができるはずです：

  • json.meta.caller_id:Groups::OmniauthCallbacksController#group_saml
  • json.meta.user またはjson.username：username
  • json.method:POST
  • json.path:/groups/GROUP-PATH/-/saml/callback

関連するログエントリーに、json.params ：

  • "key": "SAMLResponse" と"value": (full SAML response)、
  • "key": "RelayState" "value": "/group-path"と
  • "key": "group_id" "value": "group-path"を参照してください。

また、顧客がSAML Group Sync を設定している場合は、デコードされた SAML 応答を以下のフィルタで確認する必要があります：

  • json.class:GroupSamlGroupSyncWorker
  • json.args:<user ID> or <group ID>

該当のログエントリでは

  • json.args は<userID>, <group ID>, [group link ID 1, group link ID 2, ..., group link ID N]という形式です。
  • json.extra.group_saml_group_sync_worker.stats.* フィールドは、このグループ同期added、removed またはchanged の実行回数とユーザーのメンバーシップを示します。

SAML 応答が長い場合、"value":"..."で"key": "truncated" を受信することがあります。このような場合は、SAML デバッグ・ツールのいずれかを使用するか、グループ用 SAML SSO の場合は、グループ・オーナーがグループ SSO 設定ページの「Verify SAML Configuration」ボタンを選択すると、SAML 応答のコピーを取得できます。

SAML 応答の人間が読めるバージョンを表示するには、base64 デコーダを使用します。SAML 応答をオンラインで貼り付けてデコードするのを避けるには、開発者ツールのブラウザのコンソールを使用できます：

atob(decodeURI("<paste_SAML_response_here>"))

XML 形式の SAML 応答が出力されるはずです。

設定エラー

無効なオーディエンス

このエラーは、IDプロバイダーがGitLabをSAMLリクエストの有効な送受信者として認識していないことを意味します。確認してください：

  • GitLab コールバック URL をアイデンティティ・プロバイダ・サーバの承認者に追加してください。
  • issuer 文字列の末尾の空白は避けてください。

キー検証エラー、ダイジェスト不一致、フィンガープリント不一致

これらのエラーはすべて、SAML 証明書という同じ場所から発生します。SAML 要求は、フィンガープリント、証明書、バリデータのいずれかを使用して検証する必要があります。

この要件については、以下を必ず考慮してください：

  • フィンガープリントを使用する場合、正しいSHA1フィンガープリントでなければなりません。正しいSHA1フィンガープリントを使用していることを確認するには：
    1. 証明書ファイルを再ダウンロードします。
    2. フィンガープリントを計算します。
    3. フィンガープリントをidp_cert_fingerprint で提供された値と比較します。値は同じでなければなりません。
  • 設定で証明書が提供されていない場合、フィンガープリントまたはフィンガープリントバリデータを提供する必要があり、サーバからのレスポンスには証明書が含まれていなければなりません (<ds:KeyInfo><ds:X509Data><ds:X509Certificate>)。
  • 設定で証明書が提供されている場合、リクエストに証明書を含める必要はなくなります。この場合、指紋または指紋バリデータはオプションです。

上記のシナリオのどれもが有効でない場合、リクエストは前述のエラーのいずれかで失敗します。

請求がない、またはEmail can't be blank エラー

GitLab がアカウントを作成したり、ログイン情報を既存のアカウントと照合したりするためには、ID プロバイダサーバが特定の情報を渡す必要があります。email は、渡す必要のある最小限の情報です。ID プロバイダ・サーバがこの情報を提供していない場合、すべての SAML リクエストは失敗します。

この情報が提供されていることを確認してください。

このエラーが発生するもう 1 つのイシューは、ID プロバイダから正しい情報が送信されているにもかか わらず、属性が OmniAuthinfo ハッシュの名前と一致しない場合です。この場合、SAML 設定でattribute_statements を設定して、SAML レスポンスの属性名を、対応する OmniAuthinfo ハッシュ名にマッピングする必要があります。

ユーザ・サイン・イン・バナーのエラー・メッセージ

メッセージ”SAML認証に失敗しました：外部 UID は既に取得されています”

このエラーは、GitLab ユーザーとしてサインインしているにもかかわらず、SAML ID を別の GitLab ユーザーにリンクしてしまっていることを示唆しています。いったんサインアウトしてから SAML を使ってもう一度サインインしてみると、リンク先のユーザーアカウントで GitLab にログインできるはずです。

SAMLログインでそのGitLabユーザーを使いたくない場合は、SAMLアプリからGitLabアカウントのリンクを解除してください。

メッセージ”SAML 認証に失敗しました：ユーザーは既に取得されています”

サインインしているユーザーが、すでに別の ID に SAML リンクされているか、NameID の値が変更されています。考えられる原因と解決策は以下のとおりです：

原因解答
特定の ID プロバイダに対して、複数の SAML ID を同じユーザにリンクしようとしました。サインインする ID を変更してください。再度サインインする前に、この GitLab アカウントから以前の SAML ID のリンクを解除してください。
NameID は、ユーザーが SSO 識別を要求するたびに変更されます。 NameID がTransient フォーマットで設定されていないか、NameID がその後のリクエストで変更されていないか確認してください。

メッセージ”SAML 認証に失敗しました：電子メールは既に取得されています”

原因解答
メールアドレスを持つユーザーアカウントが既にGitLabに存在しているが、そのユーザーがSAML IDをアカウントに紐付けていない場合。ユーザーはアカウントを紐付ける必要があります。

ユーザーアカウントは以下のいずれかの方法で作成されます：

  • ユーザー登録
  • OAuthによるサインイン
  • SAMLによるサインイン
  • SCIMプロビジョニング

メッセージ”SAML認証に失敗しました：外部 UID は既に取得済み、ユーザーは既に取得済み”

これらのエラーが同時に発生した場合、IDプロバイダから提供されたNameID の大文字小文字が、そのユーザーの以前の値と正確に一致しなかったことを意味します。

これは、NameID が一貫した値を返すように設定することで防ぐことができます。個々のユーザーについてこれを修正するには、そのユーザーの識別子を変更する必要があります。GitLab.com の場合は、ユーザーがGitLab アカウントから SAML へのリンクを解除する必要があります。

GitLab アカウントをリンクしようとしているユーザーが、ID プロバイダーの SAML アプリ内でユーザーとして追加されていることを確認してください。

あるいは、SAML レスポンスのsamlp:Response タグにSAML gem が期待するInResponseTo 属性がない可能性もあります。ID プロバイダ管理者は、ログインが ID プロバイダだけでなく、サービスプロバイダによって開始されることを確認する必要があります。

メッセージ”There is already a GitLab account associated with this email address.組織のアカウントに接続するには、既存の認証情報でサインインしてください。”

ユーザーが既存の GitLab.com アカウントに手動で SAML をリンクしようとしているときに、このメッセージが表示されることがあります。

この問題を解決するには、ユーザーはサインインに正しい GitLab パスワードを使っていることを確認する必要があります。両方の場合、ユーザーはまずパスワードをリセットする必要があります：

  • アカウントが SCIM によってプロビジョニングされている場合。
  • ユーザ名とパスワードを使って初めてサインインします。

その他のユーザーサインインのイシュー

検証NameID

トラブルシューティングでは、認証されたユーザーはAPIを使って、https://gitlab.com/api/v4/user にアクセスし、identitiesの下にあるextern_uid をチェックすることで、GitLabがすでに自分のユーザーにリンクしているNameID を確認することができます。

自己管理の場合、管理者はユーザー APIを使って同じ情報を見ることができます。

グループに SAML を使用する場合、適切な権限を持つロールのグループ・メンバは、members APIを使用して、グループのメンバのグループ SAML ID 情報を表示できます。

そして、SAML デバッグツールでメッセージをデコードすることで、ID プロバイダから送信されるNameID と比較することができます。ユーザーを識別するには、これらの情報が一致する必要があります。

ログイン “ループ “から抜け出せない

GitLab シングルサインオン URL（GitLab.comの場合）またはインスタンス URL（セルフマネージの場合）が、ID プロバイダの SAML アプリで “Login URL”（または同様の名前のフィールド）として設定されていることを確認してください。

GitLab.com の場合は、ユーザーが既存の GitLab.com アカウントに SAML をリンクする必要があるときに、GitLab シングルサインオン URLを提供し、最初のサインインでは SAML アプリを使わないように指示します。

ユーザーは 404 を受け取ります。

グループ用の SAML SSO は有料機能であるため、サブスクリプションの有効期限が切れると、404 GitLab.com で SAML SSO を使用してサインインする際にエラーが 404発生することがあります。404 すべてのユーザーが 404SAML を使ってサインインしようとすると 404 を受け取る場合は、この SAML SSO ネームスペースでアクティブなサブスクリプションが使用されていることを確認してください。

設定の検証” を使用した際に404 を受け取った場合は、正しいSHA-1 生成フィンガープリントを使用したことを確認してください。

ユーザーが初めてサインインしようとしているときに GitLab シングルサインオン URL が設定されていない場合、404 が表示されることがあります。ユーザーアクセスのセクションで説明したように、グループのオーナーがURLをユーザーに提供する必要があります。

アイデンティティ・プロバイダ（IdP）にサインインした後、すべてのユーザーが404 を受け取っている場合：

  • assertion_consumer_service_url を検証してください：

  • Azure IdP でユーザーに割り当てられているグループが多すぎることが404 に関連しているかどうかを確認します：

    • ユーザーにグループリンクが設定されている場合。
    • ユーザーがグループに追加され、すぐに削除された場合の監査イベント。

一般的なプロバイダの設定例については、グループ SAML および SCIM の設定例を参照してください。

ログイン後の 500 エラー

GitLab で SAML サインインページからリダイレクトされて戻ってきたときに “500 エラー” が表示される場合は、次のような可能性があります：

  • GitLab は SAML ユーザーのメールアドレスを取得できませんでした。ID プロバイダが、クレーム名email またはmail を使ってユーザーのメールアドレスを含むクレームを提供していることを確認してください。
  • identity provider_cert_fingerprint またはidentity provider_cert ファイルに対するgitlab.rb ファイルの証明書セットが正しくありません。
  • gitlab.rb ファイルがidentity provider_cert_fingerprint を有効にするように設定され、identity provider_cert が提供されているか、またはその逆になっています。

ログイン後の422エラー

GitLab で SAML サインインページからリダイレクトされたときに “422 エラー” が表示される場合は、ID プロバイダの Assertion Consumer Service(ACS) URL が正しく設定されていない可能性があります。

ACS URL がhttps://gitlab.example.com/users/auth/saml/callback を指していることを確認してください。gitlab.example.com は GitLab インスタンスの URL です。

ACS URL が正しくてもエラーが発生する場合は、他のトラブルシューティングのセクションをレビューしてください。

SAML を使用してサインインすると、ユーザーがブロックされます。

SAML を介したサインイン時にユーザがブロックされる最も可能性の高い理由は、以下のとおりです：

  • 設定で、gitlab_rails['omniauth_block_auto_created_users'] = true が設定されており、ユーザが初めてサインインする場合。
  • required_groups が設定されていますが、ユーザーはいずれかのメンバーではありません。

Googleワークスペース トラブルシューティングのヒント

Google Workspace のドキュメントにあるSAML アプリのエラーメッセージは、Google からのサインイン時にエラーが発生した場合のデバッグに役立ちます。特に、以下の 403 エラーには注意してください：

  • app_not_configured
  • app_not_configured_for_user

SAML Name ID とメールアドレスがユーザーアカウントと一致しません。

ユーザーがエラーSAML Name ID and email address do not match your user account. Contact an administrator. に遭遇した場合、これは次のことを意味します：

  • SAML から送信された NameID 値が、既存の SAML IDextern_uid の値と一致しません。
  • SAML レスポンスにメールアドレスが含まれていないか、メールアドレスがユーザーの GitLab メールアドレスと一致していません。

GitLab グループのオーナーは、SAML API を使ってユーザーの SAMLextern_uidを更新することができます。extern_uid の値は、SAML ID プロバイダ（IdP）から送信された名前 ID の値と一致する必要があります。IdP の設定によって、これは生成された一意の ID、電子メールアドレス、またはその他の値になります。

メッセージ：”このメンバの電子メール・アドレスは、SAML アカウントにリンクされていません”

このエラーは、SAML SSOが有効になっているGitLab.comグループ（またはグループ内のサブグループやプロジェクト）にユーザーを招待しようとしたときに表示されます。

グループにユーザーを招待しようとしてこのメッセージが表示された場合：

  1. ユーザがSAML ID プロバイダに追加されていることを確認します。
  2. ユーザーが既存の GitLab.com アカウントを持っている場合は、そのアカウントに SAML をリンクするように指示します。そうでなければ、アイデンティティ・プロバイダのダッシュボードから GitLab.com にアクセスするか、手動でサインアップして新しいアカウントに SAML をリンクすることで、GitLab.com アカウントを作成するようにユーザーに依頼します。
  3. ユーザーが SCIM ID を持っている場合は、active 属性がtrue になっていることを確認しましょう。