Okta で SSO を設定する

組織のオーナーと管理者が、メンバーを Okta のアカウントで Actagate にログインさせるための手順です。 Okta に OIDC のアプリを作り、Actagate の設定画面で接続を追加して、テストしてから有効にします。

始める前に、運用担当者に SSO_SECRET_ENCRYPTION_KEY と WEB_BASE_URL を設定してもらいます (詳しくはシングルサインオンの考え方)。Okta の独自ドメインを使っている場合は、このページではなく汎用 OIDC の手順を使います。

1. Okta でアプリを作る

Okta の管理コンソールで Applications > Applications > Create App Integration を開きます。作成の画面が開きます
Sign-in method で OIDC - OpenID Connect、Application type で Web Application を選びます。アプリの設定画面に進みます
Grant type は Authorization Code だけを有効にします
Sign-in redirect URIs には仮の値 https://<ホスト>/api/auth/sso/callback/0 を入れます。本当の URL は、手順 2 で接続を保存したあとに決まります
Assignments で、テストする管理者と、ログインさせるメンバーを割り当てて保存します。アプリが作成されます
General タブで Require PKCE as additional verification を有効にします。Client authentication は Client secret のままにします
Client ID と Client secret を控えます
issuer を控えます。Okta の組織の認可サーバーなら https://<組織>.okta.com、カスタム認可サーバーなら Security > API > Authorization Servers にある Issuer URI (例: https://<組織>.okta.com/oauth2/default) です

公式資料: Okta のアプリ作成

2. Actagate で接続を追加する

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

Okta の接続フォーム — 接続のフォーム。プロバイダの説明、「公式の設定ガイド」、表示名、Issuer URL、クライアント ID、クライアントシークレットが並ぶ

Okta のプリセットが受け付ける issuer は、ホストが .okta.com、.oktapreview.com、.okta-emea.com のどれかで終わるものだけです。それ以外は invalid_issuer になります。保存後のクライアントシークレットは画面に表示されず、「シークレット: 設定済み」とだけ出ます。

3. テストする

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

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

4. 有効化する

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

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

5. ログインを確かめる

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

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

6. 困ったとき

invalid_issuer: Okta の独自ドメインを入力しています。汎用 OIDC で接続し直します
provider_rejected: Okta の Assignments と、Sign-in redirect URIs に登録した URL を確かめます
token_exchange_failed: クライアント ID とクライアントシークレットを確かめます
issuer_mismatch: 組織の認可サーバーとカスタム認可サーバーの issuer を取り違えています。Okta に表示される issuer と同じ値を入力します

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