メインコンテンツへスキップ

SSO のトラブルシューティングとリファレンス

この記事では、権限、クイック リファレンス値、および一般的な SSO 問題の解決策について説明します。セットアップ手順については、SSO メタデータ設定ガイド を参照してください。

権限​

すべての SSO メタデータ管理アクションは、1 つの例外を除いてスーパー管理者に制限されています。チーム管理者は、自分のチームのドメインのファイルを介して IdP メタデータをアップロードできます。

アクション必要な役割
SSO メタデータ タブの表示スーパー管理者
ファイル経由で IdP メタデータをアップロード（POST /admin/saml-metadata/upload）スーパー管理者、または sso_domain がチームの email_domain と一致するチーム管理者
テキスト貼り付けで IdP メタデータをアップロード（POST /admin/saml-metadata/upload-text）スーパー管理者のみ
保存されたメタデータのダウンロード（GET /admin/saml-metadata/download）スーパー管理者
保存されたメタデータの削除（DELETE /admin/saml-metadata/delete）スーパー管理者
注意

/saml/well-known/sp-metadata の SP メタデータ エンドポイントは設計上パブリックです。秘密情報は含まれていません。SP エンティティ ID、ACS URL、NameID 形式、およびパブリック署名証明書のみが含まれます。

クイックリファレンス​

バックエンド ホスト

<your-backend-host>（例: ek-api.corp.acme.com）

すべての SAML トラフィックを処理します。SP メタデータ、SSO 開始、ACS エンドポイント。これは IdP が把握する必要がある唯一のホストです。

フロントエンド ホスト

<your-frontend-host>（例: ek.corp.acme.com）

ユーザーが開く Web UI。バックエンドで FRONTEND_ROOT_URL を使用して構成。IdP 構成には表示されません。

SP メタデータ URL
https://<your-backend-host>/saml/well-known/sp-metadata

IdP 管理者と共有して、EK を SAML アプリケーションとして登録します。

ACS URL
https://<your-backend-host>/user/generic/sso/saml/acs/admin

IdP が SAML 応答を POST する場所。常にバックエンド ホストであり、フロントエンドではありません。

SP 発信 SSO エントリ ポイント
https://<your-backend-host>/sso/login?enterprise_id=<email-domain>

ユーザーが SSO を開始するときにフロントエンドがリダイレクトするバックエンド エンドポイント。

必須 NameID 形式
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

IdP はユーザーの電子メール アドレスをこの形式で送信する必要があります。

フロントエンド SSO モード環境変数​

変数説明
VITE_ALLOW_ONLY_SSO_LOGINtrue でシングルクリック SSO、false（デフォルト）で電子メールモーダル SSO。
VITE_SSO_ENTERPRISE_IDシングルクリックモード専用。SSO メタデータ タブに IdP メタデータがアップロードされたドメインと一致する必要があります。
  • IdP メタデータをどこにアップロードしますか？ スーパー管理者ダッシュボード → SSO メタデータ タブ → メタデータの追加 / 更新
  • ドメインごとに1つのドキュメント。 再アップロードすると既存のメタデータが置き換えられます。削除するとそのドメインの SSO が無効になります。
  • 必要な役割？ すべてのアクションでスーパー管理者。ただし、チーム管理者は自分のチームのドメインのファイルを介してアップロードできます。

トラブルシューティング​

「Please enter a valid domain」エラー

SSO チームの電子メール ドメイン フィールドは acme.com や eu.acme.co.uk のようなドメインのみを期待します。送信前に、先頭の @、https://、パス、ポート番号をすべて削除してください。

「File must be an XML file」エラー

ファイル アップローダーは .xml 拡張子を持つファイルのみを受け付けます。IdP がメタデータを .txt ファイルまたは拡張子なしで提供した場合は、.xml に名前を変更するか、XML コンテンツを貼り付け オプションを使用してください。

「Content does not appear to be valid XML」エラー

XML コンテンツを貼り付け を使用する場合、貼り付けたコンテンツは空白をトリミングした後 <?xml または < で始まる必要があります。完全なメタデータ ドキュメントをコピーし、前置きや説明文が含まれていないことを確認してください。

IdP ではサインインが成功するが、EK がアサーションを拒否する

これはほぼ常に以下のいずれかが原因です。

  • 証明書の不一致 — アップロードされたメタデータ内の IdP 署名証明書が、IdP が実際に使用している証明書と一致しなくなっています。これは通常、IdP の証明書ローテーション後に発生します。IdP 管理者から最新のメタデータを取得し、更新 を使用してください。
  • NameID 形式の誤り — IdP がメールアドレスを NameID として送信していません。IdP 側で形式が urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress に設定されていることを確認してください。
  • Entity ID の不一致 — IdP で構成された Audience または Entity ID が、EK インスタンスの Entity ID と一致しません。EK SP メタデータ XML を再共有し、IdP 管理者に再インポートさせしてください。
ユーザーは正常にサインインするが、アクセスを拒否される

これは スーパー管理者 → アクセス制御 で制御され、SSO メタデータ タブではありません。SAML アクセス制御 ガイドの 任意の新規ユーザーを許可 と SAML メタデータに制限 および自動チーム/プロジェクト割り当てルール の詳細を参照してください。

IdP 発信 SSO が機能しない

デフォルトでは、EK は自身の /sso/login エンドポイントから開始された SAML 応答のみを受け付けます。つまり SP 発信 SSO のみです。IdP 発信（非要求）SSO を有効にするには、オンプレミス オペレーターが EK バックエンドで ALLOW_IDP_INITIATED_SSO=true を設定し、サービスを再起動する必要があります。これはデプロイレベルの設定であり、SSO メタデータ タブで構成できるものではありません。

IdP がバックエンド ホストではなくフロントエンド ホストで構成されている

IdP アプリケーションが ACS URL または Entity ID に EK フロントエンドのホスト名で構成されている場合、SAML 応答は誤ったサービスに送信され、認証は静かに失敗します。通常、IdP ログイン画面の後に 404 または一般的なエラーページが表示されます。

IdP 管理者に以下を確認してもらってください。

  • ACS URL が https://<your-backend-host>/user/generic/sso/saml/acs/admin であること。
  • Entity ID / Audience が https://<your-backend-host>/saml/well-known/sp-metadata の entityID と一致すること。

フロントエンド ホストは IdP の SAML アプリケーション構成に表示されるべきではありません。

シングルクリック SSO ボタンが応答しない（または「SSO ログインのドメインを決定できませんでした」が表示される）

フロントエンドで VITE_SSO_ENTERPRISE_ID が設定されていません。IdP メタデータをアップロードした電子メール ドメインに設定し、フロントエンドを再デプロイまたは再起動して値を有効にしてください。

シングルクリック SSO ボタンはリダイレクトするが、バックエンドで SSO が失敗する

VITE_SSO_ENTERPRISE_ID は設定されていますが、SSO メタデータ タブにアップロードされたメタデータを持つドメインと一致しません。次のいずれかで修正してください。

  • 現在 VITE_SSO_ENTERPRISE_ID にあるドメインの IdP メタデータをアップロードする（推奨。フロントエンド構成を変更せずに維持できます）。
  • 既にメタデータがアップロードされているドメインに VITE_SSO_ENTERPRISE_ID を更新し、フロントエンドを再デプロイまたは再起動する。

2つの値は正確に一致する必要があります（大文字と小文字は区別されません）。

電子メールモーダル SSO で「組織は SSO ログイン用に構成されていません」が表示される

ユーザーの電子メール ドメインに SSO メタデータ タブでアップロードされた IdP メタデータがありません。そのドメインのメタデータをアップロードするか、ユーザーに電子メール/パスワードまたは OAuth を使用してサインインするよう依頼してください。

ユーザーが SSO を完了するが、誤ったページに到着するか、リダイレクトエラーが発生する

SAML 応答が成功した後、EK はバックエンドの FRONTEND_ROOT_URL で定義されたフロントエンド URL にユーザーをリダイレクトします。この変数が未設定、誤ったホストを指している、または誤ったスキームまたはポートを使用している場合、ユーザーは認証を完了したように見えますが、壊れたページに到着します。

オンプレミス オペレーターに FRONTEND_ROOT_URL が https://<your-frontend-host> と正確に一致することを確認してもらってください。正しいスキーム、正しいポート、末尾のスラッシュの問題がないこと。