QQ クイックログインの連携
QQ クイックログインでは、QQ アカウントを指定した TOTP 認証情報へ紐付けます。紐付け後、利用者はログインページで QQ を選んで認証できます。QQ はその TOTP のサービススコープとセッションポリシーを継承するため、独立したユーザー ID や管理者 ID ではありません。
fn-knock には QQ 連携が組み込まれています。QQ オープンプラットフォームでアプリを登録する必要はなく、Client ID、Client Secret、Issuer、コールバック URL の入力も不要です。
紐付けに成功すると、ログインページに「QQでログイン」と表示されます。利用者はボット対策認証を完了した後、紐付け済みの QQ アカウントでログインできます。
利用前の確認
- 現在のモードが
TOTP ログインモードであること。パスワードログインモードでは QQ のログイン項目が表示されず、QQ ログインも受け付けません。 - 対象の TOTP 認証情報を作成済みで、別の利用可能な TOTP または復旧手段も残してあること。QQ だけを唯一の復旧手段にしないでください。
- 認証 Host が、
https://auth.example.comのようにインターネットから最終的にアクセスできる HTTPS アドレスであること。localhost、コンテナ名、LAN 内の IP、誤ったポートは使用できません。 - fn-knock を実行しているデバイスから
https://api.fnknock.cnへアクセスできること。QQ の追加時に、このサービスの OIDC discovery を読み取ります。
認証 Host は QQ の認証フローで、コールバックとクライアントメタデータを動的に提供します。CDN やリバースプロキシで /api/auth/oidc/ 配下の動的レスポンスをキャッシュせず、これらのコールバックパスに別のログイン保護を追加しないでください。前段のプロキシでは、利用者が実際に使用する Host と公開側のプロトコルを維持する必要があります。
1. QQ プロバイダーの追加
管理画面で次の順に進みます。
認証設定 → 上部の操作メニューにある OIDC 設定 → プロバイダーを追加 → QQ → 追加QQ には、手動で入力する接続フィールドはありません。保存時、システムはまずプロバイダーを無効のままにして discovery をテストし、成功した場合にだけ自動的に有効化します。テストに失敗した場合は、デバイスから api.fnknock.cn までの DNS、ネットワーク、TLS の問題を解消してから、もう一度追加してください。
テストの成功は、組み込みサービスを検出できたことだけを示します。次に説明するインターネット経由のコールバック検証の代わりにはなりません。
2. QQ を TOTP 認証情報へ紐付け
認証設定のTOTP 管理へ戻ります。- 権限を付与する TOTP 認証情報の行で、
クイックログインを管理をクリックします。 外部アカウントの紐付けで紐付け用の招待を作成をクリックし、QQを選択してから生成をクリックします。- 対象の QQ アカウントを利用できるブラウザで生成されたリンクを開き、「QQで連携」を選んで認可を完了します。
- 管理画面へ戻り、「外部アカウントの紐付け」一覧に QQ の記録が表示されていることを確認します。
招待リンクは 30 分間有効で、正常に使用されるとその時点で無効になります。このリンクは QQ アカウントを TOTP の権限へ紐付けるための認可情報に相当します。グループチャット、サポートチケット、無関係な相手へ送らないでください。期限が切れた場合や誤送信した場合は、新しいリンクを生成します。
同じ QQ ID を別の TOTP へ同時に紐付けることはできません。紐付け先を変更する場合は、元の TOTP の「外部アカウントの紐付け」で既存の紐付けを削除してから、新しい TOTP 用の招待を生成してください。
3. ログインの検証
シークレットウィンドウまたは未ログインのブラウザで認証 Host を開くか、保護されたサービス用 Host を直接開きます。ログインページに QQでログイン と表示されたら QQ の認可を完了し、元のサービスアドレスへ戻れることを確認します。
最後に TOTP のサービススコープを確認します。QQ ログインでアクセスできるのは、その TOTP に許可された Host だけです。LAN またはループバックの送信元では local_exempt になる場合があるため、モバイルネットワークなど実際の外部経路から最終確認してください。
コールバック URL を手動登録しない理由
組み込みの QQ プロバイダーは、現在の認証 Host に基づいて次のようなアドレスを自動生成します。
https://auth.example.com/api/auth/oidc/callback/<provider-id>同時に、システムは現在のインスタンスのクライアントメタデータを QQ サービスへ提供します。このため、外部サービスの管理画面へ Callback URL をコピーしたり、自分で作成した QQ アプリを登録したりする必要はありません。ドメイン、ポート、前段のプロキシを移行した後は、認証 Host の HTTPS、Host ヘッダーの維持、インターネットからの到達性を再確認し、QQ ログインをもう一度テストしてください。
解除とトラブルシューティング
QQ の紐付けを削除すると、その QQ アカウントでは直ちにログインできなくなりますが、TOTP 自体は削除されません。QQ プロバイダーまたは紐付け先 TOTP を削除した場合も、対応する紐付けは削除されます。TOTP を残しておけば、QQ の認可失敗、アカウント変更、デバイス紛失の際にアクセスを復旧できます。
| 現象 | 最初に確認する項目 |
|---|---|
| ログインページに QQ ボタンがない | 現在のモードが TOTP ログインモードか、QQ プロバイダーのテストに成功して有効になっているか |
| QQ の追加時にテストが失敗する | fn-knock から api.fnknock.cn までの DNS、ネットワーク接続、TLS |
| QQ の認可後にコールバックが失敗する | 認証 Host が最終的な公開 HTTPS アドレスか、リバースプロキシが Host を維持しているか、動的 OIDC パスがキャッシュまたはブロックされていないか |
| QQ が別の認証情報へ紐付け済みと表示される | 元の TOTP の「クイックログインを管理」で既存の紐付けを削除してから、もう一度紐付ける |
| ログインに成功してもサービスへアクセスできない | 紐付け先 TOTP のサービススコープと、対象 Host のアクセスポリシー |