身份验证配置

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

身份验证配置简介

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

配置分区

基本身份验证

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

• 开关与字段

OAuth 集成

• 身份验证-OAuth 集成 GitHub

• 身份验证-OAuth 集成 Discord

• 身份验证-OAuth 集成 OIDC

• 身份验证-OAuth 集成 Telegram

• 身份验证-OAuth 集成 LinuxDO

• 身份验证-OAuth 集成 微信

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

• OAuth 登录与绑定流程

1. 在提供商后台登记应用名称、主页和该提供商要求的回调地址。
2. 在本页填写凭证和端点，保存后再开启提供商。

通行密钥认证

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

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. OAuth state 当前有效期约 10 分钟；绑定 state 还会关联发起用户和会话，不能跨会话复用。
2. 同一用户对同一自定义提供商只能保留一个绑定，同一提供商账号也不能绑定到多个本地用户。
3. 禁用提供商只会阻止后续登录和绑定，不会删除历史绑定。
4. 删除提供商前必须先由用户在安全与访问页解绑，或由有权限的管理员在用户管理中解除全部绑定；仍有任意绑定时，删除请求会被拒绝。

登录验证与安全

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

• 统一登录验证：当用户已启用 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 信封加密后随请求提交。
• 服务端使用私钥解密校验密码。

保存与生效

保存方式见系统设置概览，生效与多实例同步规则见生效范围与多实例同步，浏览器何时显示新值见前端显示与缓存，密钥字段不回显、留空保留的规则见敏感配置与审计记录。未特别说明时，保存后处理该请求的节点立即使用新值，其他节点随系统设置同步（默认 60 秒）；各配置项读取新值的时机如下：

补充说明

• 开启顺序：开启 GitHub、Discord、OIDC、LinuxDO 或微信登录，以及电子邮件域限制、Turnstile 前，先填写并保存对应的凭证或配置，再开启开关并保存；对应配置未保存时开启会被拒绝，提示见常见问题。
• 没有改动：OAuth 集成和通行密钥认证没有改动时提示「没有需要保存的更改」。
• 未保存的修改：OAuth 集成有未保存的修改时离开页面，会弹出「未保存的更改」确认。
• 登录页和注册页：登录方式、注册入口和 Turnstile 组件的显示来自浏览器缓存的站点状态；服务端已按新设置判断，已打开的页面刷新后才显示新内容。通行密钥、OIDC 显示名称和自定义 OAuth 保存后，执行保存的浏览器自动更新。

注意事项

登录与回调

• 回调一致性：浏览器公开地址、ServerAddress、提供商登记回调与反向代理转发的 Host/Proto 必须一致。
• 验证证明与 state 一次性：失败后不要反复刷新同一地址，应重新发起登录或绑定。
• 统一登录验证：2FA/Passkey 用户需在主认证后完成验证质询（约 5 分钟）。

凭证与域名

• Passkey 与域名强绑定：改域名/协议后需重新核对主域名、兼容的通行密钥域名、允许使用通行密钥的网站和 ServerAddress；旧域名应保留在兼容域名中。
• Turnstile：需站点密钥和密钥同时正确、Cloudflare 可达、token 有效，且只有一个全局开关。保护的流程见机器人保护。
• Telegram 迁移：若此前用旧 Login Widget，需在 BotFather 的 Login Widget 中登记 /oauth/telegram 回调地址并取得 Client ID 和 Client Secret；现有绑定可继续使用。telegram 标识符（slug）保持内置保留。
• 密码加密的密钥共用：密钥在启动时自动生成并存入数据库，各节点需连接同一数据库。

常见问题

相关文档

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