外部アカウント認証（OIDC / OAuth / LDAP）

外部アカウント認証では、QQ、Google、Microsoft、GitHub、OIDC 互換のアイデンティティプロバイダー、または LDAP / Active Directory のディレクトリアカウントを TOTP 認証情報へ紐付けます。利用できるのは TOTP ログインモード だけです。ログイン成功後も、fn-knock のセッション、紐付け先 TOTP のサービススコープ、ログイン後の IP 許可ポリシーが適用されます。

OIDC / OAuth はブラウザーを外部サイトへリダイレクトして認可を行います。LDAP は fn-knock サーバーから LDAPS または StartTLS でディレクトリへ接続します。どちらも既存の TOTP への紐付けが必要で、fn-knock の ID を自動作成することはありません。

QQ は組み込み連携を使用

QQ は fn-knock に組み込まれた共用プロバイダーです。QQ アプリの登録や、Client ID、Client Secret、Issuer の入力、Callback URL の手動登録は必要ありません。プロバイダーを追加した後、利用者ごとに QQ アカウントを対象の TOTP 認証情報へ紐付ける必要があります。

詳しい前提条件、紐付け用招待、コールバック要件、解除方法については、QQ クイックログインの連携を参照してください。

Google、Microsoft、GitHub、カスタム OIDC

1. 認証 Host が、インターネットからアクセスできる HTTPS アドレスとして設定されていることを確認します。
2. 認証設定上部の操作メニューから OIDC 設定 を開き、プロバイダーを追加します。
3. fn-knock に表示された Callback URL を変更せず、そのまま外部プロバイダーのコールバック URL 一覧へ登録します。
4. プロバイダーが要求する Client ID と Client Secret を入力します。Microsoft では common、organizations、またはテナント ID を指定でき、カスタム OIDC では Issuer も必要です。
5. Scopes を確認します。入力値は空白またはカンマで区切れます。プロバイダーがユーザーを識別するために必要な openid と、必要なユーザー情報のスコープは必ず残してください。
6. 対象の TOTP 認証情報で クイックログインを管理 → 外部アカウントの紐付け を開き、招待を生成して認可と紐付けを完了します。
7. シークレットウィンドウでログインページから動作を確認し、その後で TOTP のサービススコープを確認します。

Callback URL には、利用者から実際に見える認証 Host を使用する必要があります。localhost、コンテナ名、LAN 内の IP、誤ったポートを指定すると、外部プロバイダーにコールバックを拒否されます。QQ の動的なコールバックはシステムが処理するため、ここで説明した手動登録の手順は適用されません。

通常のプロバイダーは、必須の接続パラメーターが揃っていれば有効な状態で作成されます。不足している場合は、設定が必要 な下書きとして保存されます。編集時に Client Secret を空欄のままにすると、現在の値が維持されます。プロバイダーを無効にすると、そのログイン項目は非表示または拒否されますが、後で再び有効にできるよう設定は保持されます。

LDAP / Active Directory

認証 → OIDC 設定 を開き、LDAP / Active Directory プロバイダー で OpenLDAP、Active Directory、またはカスタム LDAP を追加します。ディレクトリ接続では常に TLS 証明書を検証し、平文 LDAP は使用できません。プライベート CA を使用する場合は、発行チェーンの PEM 証明書を プライベート CA PEM へ貼り付けます。

設定	動作
サーバー URL	1 行に 1 件入力。LDAPS は ldaps://ldap.example.com:636、StartTLS は ldap://ldap.example.com:389 を使用。利用できないサーバーは順に試行
Base DN	ユーザー検索のルート DN。例：dc=example,dc=com
検索後にバインド	サービスアカウントで Base DN 配下のユーザーを 1 件だけ検索し、そのユーザー DN とパスワードで検証
直接バインド	{username} テンプレートから DN または UPN を作成してパスワードを検証し、Base DN 配下から ID 属性を取得
ユーザーフィルター	{username} が必須。入力値は LDAP フィルター値としてエスケープ
安定 ID 属性	同じディレクトリ ID を継続して識別。OpenLDAP は entryUUID、Active Directory は objectGUID がデフォルト

有効にする前に テスト を実行してください。検索後のバインドでは接続とサービスアカウントをテストします。直接バインドでは一時テスト用のディレクトリアカウントを入力しますが、その認証情報は保存されません。接続タイムアウト、証明書名またはプライベート CA の不一致、Base DN の誤り、フィルターが 0 件または複数件を返す場合はログインに失敗します。

ディレクトリアカウントを紐付ける

1. 認証 で対象 TOTP の クイックログイン を開きます。
2. 外部アカウントの紐付け で招待を生成し、有効な LDAP プロバイダーを選択します。
3. ディレクトリ利用者が 30 分以内に招待リンクを開き、ボット対策を完了してユーザー名とパスワードを入力します。
4. クイックログイン画面へ戻り、プロバイダー、アカウント、Subject、最終使用時刻を確認してから、シークレットウィンドウでログインを検証します。

招待リンクは、検証に成功したディレクトリ ID を指定の TOTP へ紐付ける機密性の高い認可情報です。同じプロバイダー内の 1 つのディレクトリ ID を複数の TOTP へ同時に紐付けることはできません。紐付けの削除は fn-knock 内の関連付けだけを削除し、ディレクトリアカウントは変更しません。プロバイダーを削除すると、その配下のすべての紐付けも削除されます。

アクセス範囲

OIDC と LDAP は独立した管理者 ID ではありません。紐付け先 TOTP のサブドメインとプロトコルマッピングの範囲を継承します。紐付けを解除すると外部アカウントではログインできなくなりますが、TOTP 自体は削除されません。プロバイダーを削除すると、そのプロバイダーに属する外部アカウントの紐付けも削除されます。実行前に、すべての利用者が TOTP または別の復旧手段を利用できることを確認してください。

紐付け用の招待は 30 分間有効で、認可を完了した外部 ID を現在の TOTP へ紐付けます。招待リンクは機密性の高い認可情報です。グループチャット、サポートチケット、公開ページへ貼り付けないでください。紐付けが完了したら、クイックログイン管理画面でプロバイダー、アカウント、Subject、最終使用時刻を確認します。

よくある問題

現象	確認項目
ログインページに外部アカウントの項目がない	現在のモードが TOTP ログインモードで、プロバイダーが有効かつ必須設定が完了しているか
プロバイダーにコールバックを拒否される	Callback URL、HTTPS、許可した redirect URI、ドメイン、ポート
コールバック後に未紐付けと表示される	fn-knock で外部アカウントと TOTP の紐付けを先に完了しているか
LDAP サービスが利用不可と表示される	fn-knock の実行環境から、ディレクトリの DNS、ポート、TLS 証明書チェーン、システム時刻を確認
LDAP 認証情報が正しくても失敗する	Base DN、ユーザーフィルター、バインド方式、安定 ID、ユーザー名属性を確認。検索結果は 1 件である必要あり
ログイン後もアクセスを拒否される	紐付け先 TOTP のサービススコープと、対象 Host のポリシー

• QQ クイックログインの連携
• TOTP 認証アプリ
• パスキー
• 認証・セッション・サービススコープ