绑定 QQ 快捷登录
QQ 快捷登录把一个 QQ 账号绑定到指定的 TOTP 凭据。绑定后，访问者可在登录页选择 QQ 完成验证；它继承该 TOTP 的服务范围和会话策略，不是独立的用户或管理员身份。
fn-knock 已提供 QQ 的内置接入，无需到 QQ 开放平台注册应用，也不需要填写 Client ID、Client Secret、Issuer 或回调地址。
绑定成功后，登录页会显示“使用 QQ 登录”。访问者完成人机验证后，即可通过已绑定的 QQ 账号登录。
使用前确认
- 当前使用
TOTP 登录模式。账号密码登录模式不显示也不接受 QQ 登录。 - 已创建目标 TOTP 凭据，并保留了另一个可用的 TOTP 或恢复方式。QQ 不应成为唯一恢复手段。
- 认证 Host 是最终对外可访问的 HTTPS 地址，例如
https://auth.example.com；不能使用localhost、容器名、内网 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 身份不能同时绑定到另一个 TOTP。若需要调整归属，先在原 TOTP 的“外部账号绑定”中删除旧绑定，再为新的 TOTP 生成邀请。
3. 验证登录
使用无痕窗口或未登录浏览器打开认证 Host，或直接打开一个受保护的业务 Host。登录页出现 使用 QQ 登录 后，完成 QQ 授权并确认可以回到原业务地址。
最后检查该 TOTP 的服务范围：QQ 登录只能进入这个 TOTP 被允许访问的 Host。局域网和回环来源可能触发 local_exempt，请用移动网络等真实外部链路做最终验证。
回调地址为什么不需要手工登记
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 的访问策略 |