企業向け SSO

シングルサインオン（SSO）を使うと、組織の OpenID Connect（OIDC）プロバイダーで Epismo にサインインできます。ワークスペースの Owner または Admin が組織のドメインと OIDC 接続を登録し、ドメイン所有権の確認と実ログインテストを完了してから有効にします。

現在提供していること

• 通常のサインイン画面に入力した勤務先メール、または epismo login --email に指定したメールのドメインから、対応するワークスペースの IdP へ自動転送します。
• IdP が返した検証済みメールのドメインが、ワークスペースの検証済みドメインと一致する場合だけログインを完了します。
• 検証済みメールが既存の Epismo ユーザーと一致する場合、そのユーザーへ OIDC ID を追加します。一致するユーザーがいない場合は新規作成します。
• 必要に応じて、対象ワークスペースへ Member として JIT 追加します。

現在提供していないこと

現在の SSO は追加のログイン方法であり、ワークスペースへのアクセス時に SSO を強制する機能ではありません。既存メンバーは Google やメール認証など、すでに利用できる方法でも引き続きサインインできます。

そのため、IdP で社員を停止しても、すでに発行済みの Epismo セッションや別のログイン方法によるアクセスが即座に無効になるとは限りません。現段階では、SSO 強制、SCIM、グループ同期、ロールマッピング、複数ドメイン、複数 OIDC 接続には対応していません。

サインインの流れ

1. ユーザーが通常の Epismo サインイン画面で会社メールを入力するか、epismo login --email <メールアドレス> を実行します。
2. Epismo はメールドメインから、有効かつ検証済みの SSO 接続を探します。
3. ユーザーを会社の IdP へ転送します。
4. Epismo は OIDC 応答と検証済みメールを確認します。
5. issuer と subject で ID を解決します。新しい ID の場合は、検証済みメールが一致する既存ユーザーへリンクするか、新しいユーザーを作成します。
6. 必要に応じて Member メンバーシップを作成します。
7. ユーザーを対象ワークスペースへ戻します。

メールアドレスは接続先の探索とドメイン適格性の確認に使います。OIDC ID の識別には、メールではなく IdP が発行した issuer と subject を使います。

SSO を設定する

ワークスペースの Owner または Admin が SSO を設定できます。1 つのワークスペースに登録できるのは、現在 1 つの企業メールドメインと 1 つの OIDC 接続です。

IdP 側でアプリを作成する

IdP に Web アプリケーションを作成し、次のコールバック URL を登録します。

https://epismo.ai/api/auth/oidc/callback

Epismo は Authorization Code Flow、PKCE（S256）、state、nonce を使用し、次のスコープを要求します。

openid email profile

ID token には次の claim が必要です。

IdP 側で、Epismo アプリを利用できるユーザーを適切に割り当ててください。Epismo 側のドメイン確認は、IdP のアプリ割り当てに代わるものではありません。

Epismo に接続情報を保存する

対象ワークスペースを開き、ワークスペース設定 → シングルサインオンへ移動します。

Client secret は暗号化して保存され、保存後に再表示されません。空欄のまま保存すると既存の secret を維持します。削除する場合は、保存済み secret の削除項目を選びます。

ドメイン所有権を確認する

ドメインルーティングを有効にする前に、そのドメインをワークスペースが所有していることを確認します。SSO 設定を保存したら、画面に表示された DNS TXT レコードを追加します。例:

Name:  _epismo-challenge.acme.com
Value: epismo-domain-verification=<random-challenge>

DNS プロバイダーによっては Name に _epismo-challenge だけを入力します。DNS の反映後、DNS レコードを確認を選びます。Epismo が完全な TXT 値を確認できると、ドメインは確認済みになります。

検証には次のルールがあります。

• 1 つのメールドメインを複数のワークスペースへ同時に登録することはできません。
• gmail.com、outlook.com などの共有メールドメインは登録できません。
• チャレンジは設定ごとにランダムに生成されます。
• ドメインを変更すると以前の検証は解除され、新しいチャレンジが発行されます。
• チャレンジを再生成すると、以前のチャレンジは無効になり、再検証まで SSO も無効になります。
• SSO 設定を削除して作り直した場合も、新しいチャレンジで検証が必要です。

SSO を有効にする

1. 接続情報を保存します。
2. DNS TXT レコードを追加して所有権を確認します。
3. SSO ログインをテストを選び、管理者自身で IdP のログインを完了します。
4. 設定画面へ戻り、SSO を有効化を選んで保存します。

DNS 検証と実ログインテストの両方が成功するまで接続は有効化できません。issuer、Client ID、Client secret、またはドメインを変更するとログインテストが無効になります。ドメインを変更した場合は DNS 検証もやり直します。

DNS 検証に失敗する場合

TXT レコードのホスト名と値が画面の表示に完全一致すること、DNS の反映時間が経過していること、同じドメインが別のワークスペースに登録されていないことを確認してください。TXT 値が複数の文字列に分割表示される場合は、結合した値が一致する必要があります。古い TXT レコードでは、再作成した設定を検証できません。

ユーザーのサインインと JIT 参加

有効な接続がある場合、一致する勤務先メールを送信すると、ユーザーは組織の IdP へ自動転送されます。SSO 専用のボタンを選ぶ必要はありません。CLI の epismo login --email <メールアドレス> も同じ判定を行い、SSO 対象ならブラウザへ進み、対象外ならターミナル上のメールコード入力でログインを完了します。認証後、OIDC 応答の署名、issuer、audience、有効期限、state、nonce、PKCE が有効である必要があります。ID token には email_verified: true のメールが含まれ、そのドメインがワークスペースの検証済みドメインと一致しなければなりません。

SSO を完了できなかった場合は、SSO の再試行、メールコードの送信、別のメールアドレスの使用を明示的に選べます。フォールバックのメールコードが自動送信されることはありません。

Epismo は issuer と subject で ID を解決します。新しい ID の場合は、検証済みメールが一致する既存ユーザーへリンクし、一致するユーザーがいなければ作成します。その後、必要に応じて対象ワークスペースへ Member として追加します。SSO 経由で Owner や Admin へ自動昇格することはありません。

ドメインが一致しない外部ユーザーは、IdP で認証できても JIT 追加されません。外部メンバーは、ワークスペースで利用できる既存の追加方法と通常の認証方法を使用します。

既存アカウント

リダイレクト前に入力したメールは、SSO 接続先の選択にのみ使用します。アカウントのリンクには IdP が返した検証済みメールを使用します。そのメールが既存ユーザーに使われている場合は、そのユーザーへ OIDC ID を追加します。ログイン中のユーザーが明示的にリンクすることもできます。別のユーザーへリンク済みの OIDC ID は付け替えられません。

SSO は現在強制されません

IdP でユーザーを停止しても、既存の Epismo セッションが即時に失効するとは限りません。社員に常に SSO を要求するポリシーや、SCIM による停止同期は現在の範囲外です。