SAML認証

SAML シングル サインオン (SSO) を使っていて、ユーザーが お使いの GitHub Enterprise Server インスタンス にアクセスするための認証を行うことができない場合、問題のトラブルシューティングを行うことができます。

この記事の内容

SAML 認証に関する問題について

GitHub Enterprise Server により、失敗した SAML 認証のエラー メッセージは github-unicorn コンテナーの systemd ジャーナル ログにログされます。 このログで応答を確認でき、より詳細なログを構成することもできます。

SAML 応答の要件について詳しくは、「SAML 構成リファレンス」をご覧ください。

SAML デバッグの構成

SAML 認証の試行ごとに詳細なデバッグ ログを書き込むように GitHub Enterprise Server を構成できます。 この追加の出力を使用して、失敗した認証試行のトラブルシューティングを行うことができる場合があります。

警告

  • SAML デバッグは一時的にのみ有効にし、トラブルシューティングが完了したらすぐにデバッグを無効にします。 デバッグを有効にしたままにすると、ログのサイズは通常よりもはるかに速いペースで増加し、GitHub Enterprise Server のパフォーマンスに悪影響を与える可能性があります。
  • 運用環境で設定を適用する前に、ステージング環境で お使いの GitHub Enterprise Server インスタンスの新しい認証設定をテストします。 詳しくは、「ステージングインスタンスのセットアップ」をご覧ください。

  1. の右上で、ご自分のプロフィール フォトをクリックしてから、 [Enterprise 設定] をクリックします。

    GitHub Enterprise Server でプロフィール写真をクリックすると表示されるドロップダウン メニューのスクリーンショット。 [Enterprise settings] オプションが枠線で囲まれています。

  2. ページの上部にある [ Policies] をクリックします。

  3. [ポリシー] で、[オプション] をクリックします。

  4. [SAML デバッグ] でドロップダウンを選択し、 [有効] をクリックします。

  5. SAML IdP を介して お使いの GitHub Enterprise Server インスタンスへのサインインを試みます。

  6. お使いの GitHub Enterprise Server インスタンス上の github-unicorn に対する systemd ジャーナルでデバッグ出力を確認します。 詳しくは、「システム ログについて」をご覧ください。

  7. トラブルシューティングが完了したら、ドロップダウンを選択し、 [無効] をクリックします。

応答のデコード

github-unicorn に対する systemd ジャーナルの出力の一部は、Base64 でエンコードされている場合があります。 管理シェルにアクセスし、お使いの GitHub Enterprise Server インスタンスの base64 ユーティリティを使用して、これらの応答をデコードできます。 詳しくは、「管理シェル (SSH) にアクセスする」をご覧ください。

出力をデコードするには、次のコマンドを実行します。ENCODED_OUTPUT は、ログからのエンコードされた出力に置き換えます。

base64 --decode ENCODED_OUTPUT

エラー:「別のユーザがすでにアカウントを所有しています」

ユーザーが SAML 認証を使って初めて お使いの GitHub Enterprise Server インスタンス にサインインすると、GitHub によってインスタンス上にユーザー アカウントが作成され、SAML NameID と nameid-format はアカウントにマップされます。

ユーザーが再びサインインすると、GitHub Enterprise Server は、アカウントの NameID と nameid-format のマッピングと IdP の応答を比較します。 IdP の応答内の NameID または nameid-format が、GitHub がユーザーに想定する値と一致しなくなった場合、サインインは失敗します。 ユーザには次のメッセージが表示されます。

別のユーザが既にアカウントを所有しています。 管理者に認証ログを確認するようご依頼ください。

このメッセージは通常、その人のユーザ名またはメールアドレスが IdP で変更されたということを示します。 GitHub Enterprise Server のユーザー アカウントの NameID と nameid-format のマッピングと、IdP 上のユーザーの NameID と nameid-format が一致していることを確認します。 詳しくは、「ユーザーの SAML NameID の更新」をご覧ください。

SAMLレスポンスが署名されていなかった場合、あるいは署名が内容とマッチしなかった場合、authログに以下のエラーメッセージが残されます。

Recipient が お使いの GitHub Enterprise Server インスタンスの ACS URL と一致しない場合、ユーザーが認証を試みたときに、次の 2 つのエラー メッセージのいずれかが認証ログに表示されます。

Recipient in the SAML response must not be blank.

Recipient in the SAML response was not valid.

IdP の Recipient の値を、お使いの GitHub Enterprise Server インスタンスの完全な ACS URL に設定してください。 たとえば、https://ghe.corp.example.com/saml/consume のようにします。

エラー:「SAML レスポンスが署名されていないか、変更されています」

IdP が SAML レスポンスに署名しない場合、または署名が内容と一致しない場合、次のエラーメッセージが認証ログに表示されます。

SAML Response is not signed or has been modified.

IdP 上の GitHub アプリケーションに対して署名済みアサーションを構成していることを確認します。

エラー:「Audience が無効です」または「アサーションが見つかりません」

IdP の応答に Audience の値がないか、または正しくない場合は、認証ログに次のエラー メッセージが表示されます。

Audience is invalid. Audience attribute does not match https://YOUR-INSTANCE-URL

IdP の Audience の値を お使いの GitHub Enterprise Server インスタンスの EntityId に設定します。これは、インスタンスの完全な URL です。 たとえば、https://ghe.corp.example.com のようにします。

エラー: "Current time is earlier than NotBefore condition" (現在の時刻は NotBefore 条件より前です)

このエラーは、IdP と GitHub の間の時間差が大きすぎる場合に発生することがあります。これはセルフホステッド IdP でよく発生します。

この問題を防ぐには、可能であれば、IdP と同じネットワーク タイム プロトコル (NTP) ソースを指すようにアプライアンスを設定することをお勧めします。 このエラーが発生した場合は、アプライアンスの時刻が NTP サーバーと適切に同期していることを確認します。 管理シェル上の chronyc コマンドを使用すれば、時間を直ちに同期させることができます。 詳細については、「時間の同期を構成する」を参照してください。

IdP の立場で ADFS を使っている場合は、GitHub のために ADFS の NotBeforeSkew も 1 分に設定します。 NotBeforeSkew を 0 に設定すると、ミリ秒などの非常に短い時間差でも認証の問題が発生する可能性があります。

エラー: "failure - Updated SAML validation returned an invalid result"

このエラーは、バージョン 3.17.0 以降の お使いの GitHub Enterprise Server インスタンス で発生する可能性があります。 これは、ID プロバイダーから受信した SAML 応答を GitHub が適切に処理できないことを示しています。 GitHub のサポート チケットを開いてください。これにより、GitHub のサポート チームとエンジニアリング チームが issue を調査して対処できるようになります。

エラー: Digest mismatch

"Digest mismatch" エラーは、SAML IdP で使われている SAML 署名証明書が、ユーザーが GitHub にアップロードしたものと異なること、または GitHub で構成されている Signature Method または Digest Method が IdP で使われているものと異なることを示します。

IdP からこの SAML 証明書を再度ダウンロードし、OneLogin の Format a x509 cert ツールなどのオンライン ツールを使って検証します。 その後、GitHub Enterprise Server 管理コンソールの [Authentication] セクションで SAML 証明書をもう一度アップロードします。 「Web UI からインスタンスを管理する」を参照してください。