身份验证配置

• 身份验证配置位于 /system-settings/auth，仅 Root 可访问。

身份验证配置简介

身份验证域下有五个独立分区：

配置分区

基本身份验证

• 身份验证-基本身份验证

• 开关与字段

OAuth 集成

• 身份验证-OAuth 集成 GitHub

• 身份验证-OAuth 集成 Discord

• 身份验证-OAuth 集成 OIDC

• 身份验证-OAuth 集成 Telegram

• 身份验证-OAuth 集成 LinuxDO

• 身份验证-OAuth 集成 微信

OAuth 分区以标签页展示内置提供商。先在提供商后台创建应用，再把凭证和回调信息填入本页，最后开启对应开关。

• OAuth 登录与绑定流程

1. 在提供商后台登记应用名称、主页和该提供商要求的回调地址。
2. 在本页填写凭证和端点，保存后再开启提供商。
3. 用未登录窗口测试登录；用已登录的个人设置测试账户绑定。
4. 检查回调后的错误提示、用户绑定记录和服务端日志。

通行密钥认证

• 身份验证-通行密钥认证

Passkey 使用 WebAuthn。启用后，用户可以注册 Passkey 并用它登录。

机器人保护

• 身份验证-机器人保护

「机器人保护」分区对应 Cloudflare Turnstile，包含：

自定义 OAuth

• 身份验证-自定义 OAuth

自定义 OAuth 是身份验证工作区的正式分区，地址为 /system-settings/auth/custom-oauth。
只有 Root 可以在管理页创建、编辑、启用、禁用、发现或删除提供商；
普通管理员只能在具备相应用户管理权限时查看或解除用户绑定。

• 创建、编辑与启停

• 身份验证-添加自定义 OAuth

• 身份验证-编辑自定义 OAuth

1. 点击「添加提供商」，在弹窗顶部「从预设快速设置」中选择预设模板并填写「API 地址」（预设端点按该地址拼接；不填时只带出名称、标识符、图标、作用域和字段映射），或直接填写空白表单。
2. 填写名称、标识符（slug）、客户端凭证、三个端点和所需高级字段；保存前确认回调地址已登记。回调地址可从弹窗中的「OAuth 回调 URL」卡片复制，它随标识符实时更新。
3. 启用状态由弹窗「基本信息」中的「已启用」开关控制（新建时默认开启），列表「状态」列只显示当前状态；停用或重新启用时，在列表中点击编辑，切换开关后保存。只有启用的提供商才会出现在登录页。
4. 编辑已有提供商时，Client Secret 输入框为空表示保留原值。修改端点、字段映射或访问策略后，应重新测试登录和绑定。
5. 修改标识符（slug）前先更新第三方后台的回调登记；保存后旧地址不再对应当前提供商。

• 字段说明

• 高级配置-访问策略

根据提供商返回的用户信息字段执行策略判断。条件和嵌套分组支持 and/or 逻辑。
支持的操作符：eq、ne、gt、gte、lt、lte、in、not_in、contains、not_contains、exists、not_exists。留空则允许所有用户。

• 高级配置-访问被拒绝消息

访问被拒绝时的提示消息。
可用变量：{{provider}}、{{field}}、{{op}}、{{required}}、{{current}}，以及 {{current.roles}} 等路径变量。

• 登录、绑定与生命周期

1. 保存并启用后，用未登录窗口测试登录，再用已登录测试用户验证账户绑定。
2. OAuth state 当前有效期约 10 分钟；绑定 state 还会关联发起用户和会话，不能跨会话复用。
3. 同一用户对同一自定义提供商只能保留一个绑定，同一提供商账号也不能绑定到多个本地用户。
4. 禁用提供商只会阻止后续登录和绑定，不会删除历史绑定。
5. 删除提供商前必须先由用户在个人设置中解绑，或由有权限的管理员在用户管理中解除全部绑定；仍有任意绑定时，删除请求会被拒绝。

登录验证与安全

本节说明与身份验证相关的安全检查边界，其中大多数能力不在本页表单中配置，但影响登录与账户安全。

• 统一登录验证：当用户已启用 2FA 或 Passkey 时，主认证通过后会进入统一的验证质询流程（有效期约 5 分钟），验证通过后才签发会话。这是提升登录安全性的统一机制。直接使用 Passkey 登录时不再追加质询。
• 验证证明一次性消费：这些验证证明绑定到「会话 + 动作」（基于 HMAC 的上下文哈希），且只被消费一次。回调、验证或绑定流程失败后通常需要重新发起，不要重复复用同一个证明。
• 2FA 的边界：2FA 是用户级安全功能，不是本页的全局开关。用户在个人设置中启用和管理 2FA；管理员重置某个用户的 2FA、备用码和登录会话时，应使用用户管理中的「重置 2FA」。
• 绑定/解绑/删除账户：涉及账户绑定变更或删除的操作，也要求再次验证（已启用 2FA 或 Passkey 时使用它们，否则使用密码或第三方登录），避免会话被意外劫持。

密码传输加密

密码传输加密由环境变量 PASSWORD_LOGIN_ENCRYPTION_ENABLED 控制（默认 false），不在页面表单中配置。
开启后，密码登录和敏感操作中的密码验证会由前端使用 RSA-OAEP 加密后提交；注册不在加密范围内，仍提交原始密码。

工作机制：

• 服务端启动时从数据库读取 RSA 私钥，不存在时自动生成（2048 位）并写入数据库；连接同一数据库的节点共用该密钥。
• /api/status 返回 password_login_encryption_enabled 供前端判断是否启用。
• 前端通过 GET /api/user/login/encryption-key 获取公钥；密码使用 RSA-OAEP v1/v2 信封加密后随请求提交。
• 服务端使用私钥解密校验密码。

保存与凭证安全

保存方式见系统设置概览，密钥字段不回显、留空保留的规则见概览中的敏感配置与审计记录。

保存后按以下顺序验证：

1. 按变更前记录与验证完成通用的提示确认与刷新核对。
2. 使用测试账户验证密码登录、注册、邮箱验证码和密码重置。
3. 对每个启用的 OAuth 提供商分别测试登录和绑定，并检查历史绑定是否符合预期。
4. 对自定义 OAuth 额外核对回调地址、字段映射、访问策略和禁用／解绑／删除流程。
5. 在支持 WebAuthn 的 HTTPS 浏览器中测试 Passkey 注册和登录。
6. 若启用了 Turnstile，重复测试所有受保护流程，而不只测试登录。
7. 若开启密码传输加密，确认各节点一致并能正常解密登录。

注意事项

• 回调一致性：浏览器公开地址、ServerAddress、提供商登记回调与反向代理转发的 Host/Proto 必须一致。
• 验证证明与 state 一次性：失败后不要反复刷新同一地址，应重新发起登录或绑定。
• 统一登录验证：2FA/Passkey 用户需在主认证后完成验证质询（约 5 分钟）。
• Turnstile：需站点密钥和密钥同时正确、Cloudflare 可达、token 有效，且只有一个全局开关。
• Passkey 与域名强绑定：改域名/协议后需重新核对主域名、兼容的通行密钥域名、允许使用通行密钥的网站和 ServerAddress；旧域名应保留在兼容域名中。
• Telegram 迁移：若此前用旧 Login Widget，需在 BotFather 的 Login Widget 中登记 /oauth/telegram 回调地址并取得 Client ID 和 Client Secret；现有绑定可继续使用。telegram 标识符（slug）保持内置保留。
• 密码加密：环境变量控制，多节点需一致；密钥在启动时自动生成并存入数据库，各节点需连接同一数据库。

常见问题

• 注册开关已开但注册失败：检查密码注册开关、邮箱验证、发信配置、白名单、别名规则和 Turnstile；再查看后端返回的具体错误。
• 邮箱白名单不生效：确认域名限制已启用、列表非空，且每行是精确域名（不是完整邮箱或通配符）；邮箱域名白名单请使用小写。
• 密码重置仍接受被域名限制的邮箱：当前域名/别名规则重点用于注册验证码流程，密码重置有独立的流程，不应假定两者完全相同。
• OAuth 回调报错或状态失效：检查 ServerAddress、反向代理的 Host/Proto、提供商后台回调登记和一次性流程令牌是否已过期。
• OIDC 保存时报发现文档错误：Well-Known URL 必须以 http:// 或 https:// 开头，且保存页面的浏览器必须能访问该地址；否则清空 Well-Known URL 后手动填写端点，并检查网络策略。
• 自定义 OAuth 的 Auto Detect 仍交换失败：「认证方式」为 Auto Detect 时按请求体参数发送凭证，不会改用 Basic Auth 重试；根据提供商要求明确选择 Params (in body) 或 Header (Basic Auth)。
• 自定义 OAuth 无法删除：先在用户个人设置或用户管理中解除该提供商的全部历史绑定；禁用不会自动解绑。
• 关闭 OAuth 后用户仍显示绑定：关闭只阻止新的登录或绑定，不会清理历史身份；需要到用户管理解除绑定。
• Passkey 在新域名上不可用：重新核对主域名、兼容的通行密钥域名、允许使用通行密钥的网站、HTTPS 和 ServerAddress；管理员可在用户管理重置后让用户重新注册。
• Turnstile 保存成功但所有请求仍失败：同时检查站点密钥、密钥、Cloudflare 站点域名、服务端出网和令牌有效期；保存选项不会代替运行时验证。
• 登录后无会话或验证失败：若用户已启用 2FA/Passkey，确认统一验证质询能够通过；检查验证证明与 OAuth state 是否一次性被消费或已过期。
• 开启密码传输加密后登录失败：检查各节点 PASSWORD_LOGIN_ENCRYPTION_ENABLED 是否一致、是否连接同一数据库。
• Telegram 登录失败：确认已在 BotFather 的 Login Widget 中登记 /oauth/telegram 回调地址，并填写对应的 Client ID 和 Client Secret。

相关文档

• 系统设置概览：系统设置的生效机制、多实例同步、敏感配置与变更验证要求。
• 站点与品牌配置：ServerAddress、Logo、公开内容与侧边栏/顶部导航配置。
• 运维配置：邮件发送方式（SMTP / Resend）与发信凭证。
• 用户管理：重置 2FA、重置 Passkey、管理员权限矩阵。
• 订阅管理：与用户注册/登录相关的权益与分组配置。