汎用 OIDC で SSO を設定する

組織のオーナーと管理者が、メンバーを IdP のアカウントで Actagate にログインさせるための手順です。一覧にない IdP (Keycloak、Okta の独自ドメインなど) にアプリを作り、Actagate の設定画面で「汎用 OIDC」の接続を追加して、テストしてから有効にします。

始める前に、運用担当者に SSO_SECRET_ENCRYPTION_KEY と WEB_BASE_URL を設定してもらいます (詳しくはシングルサインオンの考え方)。

IdP は次の条件を満たす必要があります。

<issuer>/.well-known/openid-configuration で discovery を公開している
PKCE の S256 に対応している (discovery の code_challenge_methods_supported に S256 がある)
トークンエンドポイントのクライアント認証が client_secret_post か client_secret_basic
discovery、トークンエンドポイント、JWKS にインターネットから HTTPS で届く

1. IdP でアプリを作る

IdP で、Web アプリケーション向けの OIDC クライアント (confidential client) を作ります
許可するフローを認可コードにし、PKCE の S256 を有効にします
リダイレクト URI に仮の値 https://<ホスト>/api/auth/sso/callback/0 を入れます。本当の URL は、手順 2 で接続を保存したあとに決まります
スコープ openid、profile、email を許可します。ID トークンに sub、email、email_verified が入るようにします
テストする管理者とログインさせるメンバーに、アプリへのアクセスを許可します
クライアント ID、クライアントシークレット、issuer を控えます

公式資料: OpenID Connect Discovery 1.0

2. Actagate で接続を追加する

「設定」の「セキュリティ」(/ws/settings/security) を開き、「シングルサインオン」の「プロバイダを選んで接続を追加」で「汎用 OIDC」を開きます。接続のフォームが開きます
「表示名」「Issuer URL」「クライアント ID」「クライアントシークレット」を入力し、「接続を追加」を押します。「接続を保存しました。」と表示され、「接続」の一覧に「下書き · 未テスト」の接続が増えます
接続に表示される「IdP に登録するコールバック URL」をコピーします。形は https://<ホスト>/api/auth/sso/callback/<接続 ID> です
IdP のリダイレクト URI にその URL を登録し、仮の値を消します。接続 ID を含め、表示と完全に一致させます

接続フォーム (Okta の例) — 接続のフォーム (Okta の例)。汎用 OIDC のフォームも同じ項目が並ぶ: プロバイダの説明、「公式の設定ガイド」、「表示名」、「Issuer URL」、「クライアント ID」、「クライアントシークレット」

issuer は https:// で始まる絶対 URL です。ユーザー情報 (user:pass@)、クエリ、フラグメントは使えません。末尾の / は保存時に 1 つだけ取り除かれ、それ以外は大文字小文字やパスも含めてそのまま保存されます。discovery の issuer は、保存した値と一致する必要があります。許される違いは末尾の / 1 つだけです。トークンなどの URL は discovery から読み取るため、手で入力する欄はありません。

保存後のクライアントシークレットは画面に表示されず、「シークレット: 設定済み」とだけ出ます。

3. テストする

接続の「テスト」を押します。IdP のサインイン画面に移ります
管理者自身の IdP のアカウントでサインインします。設定画面に戻り、「テストに成功しました。接続を有効化できます。」と表示されます。接続は「テスト済み」になります

テストでは認可コードフロー (PKCE) を最後まで行い、ID トークンの署名、issuer、audience、有効期限、nonce、sub を確かめます。管理者のセッションはそのままで、利用者の作成もログイン方法の紐づけも行いません。失敗したときは理由コードが表示されます。

4. 有効化する

接続の「有効化」を押します。「接続を有効にしました。ログイン画面から利用できます。」と表示され、状態が「有効」になります

「有効化」はテストに成功するまで押せません。Issuer URL、クライアント ID、クライアントシークレットを変えると、テストの結果が消えて下書きに戻ります。

5. ログインを確かめる

招待済みの一般メンバーがログイン画面を開きます。「<表示名> で続ける」のボタンが出ています
ボタンを押して IdP でサインインします。Actagate の画面が開きます
IdP でアプリを割り当てていない利用者は、サインインできないことを確かめます

初回のログインでは、IdP が検証済み (email_verified) と示すメールアドレスを、招待済みメンバーのメールアドレスと照合します。オーナーと管理者は、既存の方法でログインしてから「設定」の「ログイン方法」で「<表示名> を追加」を押して紐づけます。

6. 困ったとき

discovery_failed: <issuer>/.well-known/openid-configuration をブラウザーで開けるか確かめます
unsafe_endpoint: discovery やエンドポイントが HTTPS でないか、社内ネットワーク向けのアドレスを指しています
pkce_unsupported: IdP で PKCE の S256 を有効にします
unsupported_client_auth: クライアント認証を client_secret_post か client_secret_basic にします
invalid_identity: ID トークンに sub が入るように IdP を設定します

ほかの理由コードは SSO で困ったときにまとめています。