注册、登录与 SSO

这一篇讲什么

管理员视角的登录体系管理：谁可以注册、MFA 和 Passkey 策略、怎么接外部身份提供商。 用户自己怎么绑 MFA / Passkey / 外部身份，见 账号与安全；config.toml 里的静态密钥字段，见 登录与会话。

公开注册开关

管理 -> 系统设置 -> 用户管理 -> 允许公开注册新用户

关闭后：

• 外部用户不能再从登录页创建新账号
• 第一个管理员初始化流程仍然存在
• 管理员在后台手动创建的用户仍然可以使用

本地账号邮箱白名单 / 黑名单

如果站点只允许公司邮箱注册，或者要阻止一次性邮箱，可以在这里配置：

管理 -> 系统设置 -> 用户管理 -> 注册与登录 -> 本地账号邮箱白名单
管理 -> 系统设置 -> 用户管理 -> 注册与登录 -> 本地账号邮箱黑名单

这两项只作用于本地账号：公开注册时填写的邮箱，以及用户在 设置 -> 安全 里改绑的本地邮箱。它们不会限制第三方 SSO 返回的外部身份；外部认证的邮箱域名限制在 管理 -> 外部认证 的 provider 规则里配置。

名单项可以写完整邮箱，也可以写精确域名：

alice@example.com
example.com
@example.com

example.com 和 @example.com 等价，只匹配 user@example.com，不会自动匹配 user@sub.example.com。国际化域名需要写 punycode 形式。

规则顺序：

• 黑名单优先于白名单
• 白名单为空时，表示不启用白名单限制
• 黑名单为空时，表示不额外阻止邮箱
• 两个名单都为空时，所有合法邮箱都可以用于本地注册和本地邮箱改绑

邮箱验证码 MFA 策略

管理员可以在后台开启邮箱验证码 MFA：

管理 -> 系统设置 -> 认证与 Cookie -> 要求邮箱验证码 MFA

开启后，已验证邮箱的用户在密码或外部身份通过后，可以通过 8 位邮箱验证码完成二次验证。这个功能依赖完整可用的邮件投递配置；SMTP 主机和发件人地址不能为空，SMTP 用户名和密码必须同时填写或同时留空。

默认规则：

• 邮箱验证码默认 10 分钟有效，但不会超过当前 MFA 登录流程剩余时间
• 同一用户默认 60 秒内不能重复发送
• 只开启 要求邮箱验证码 MFA 时，未启用 TOTP 且邮箱已验证的用户会走邮箱验证码
• 如果还开启 允许 TOTP 使用邮箱兜底，已经启用认证器的用户也可以把邮箱验证码作为额外登录验证方式

谨慎开启邮箱兜底

邮箱验证码依赖邮箱账号安全。安全要求高的部署，通常只把它用于没有认证器的已验证邮箱用户；是否允许 TOTP 用户用邮箱兜底，要按你的安全策略决定。

用户丢失认证器和恢复码时，管理员在 管理 -> 用户 -> 用户详情 -> 安全操作 -> 重置 MFA 重置，见 用户与团队。

Passkey 开关

管理员可以在后台临时关闭 Passkey 登录入口：

管理 -> 系统设置 -> 用户管理 -> 注册与登录 -> 允许使用 Passkey 登录

关闭后，用户不能再用已登记的 Passkey 完成登录，但已有 Passkey 不会被删除。重新开启后，原来登记过的 Passkey 仍然可以继续使用。

正式部署要先填对 管理 -> 系统设置 -> 站点配置 -> 公开站点地址，并使用 HTTPS；本地 localhost / 127.0.0.1 调试例外。浏览器通常只在安全上下文里开放完整 Passkey 能力。

外部认证接入顺序

管理员入口是 管理 -> 外部认证。当前支持六类 provider：

类型	适合场景
oidc / OpenID Connect	标准 OIDC 身份提供商；优先选择
generic_oauth2 / 通用 OAuth2	只有 OAuth2 授权码 + UserInfo 接口，或需要手动填 endpoint 的提供商
github	GitHub OAuth App 登录
qq	QQ 互联网站登录
google	Google OIDC 登录
microsoft	Microsoft Entra ID / Microsoft Account OIDC 登录

推荐接入顺序：

1. 管理 -> 系统设置 -> 站点配置 -> 公开站点地址 填成真实外部访问地址
2. 确认反向代理已经处理 HTTPS、Host、真实客户端 IP 和大请求体
3. 在身份提供商侧创建应用，准备 Client ID（confidential client 再准备 Client Secret）
4. 在 管理 -> 外部认证 创建 provider，保存后复制 AsterDrive 生成的重定向 URI
5. 把重定向 URI 登记到身份提供商侧
6. 决定账号绑定策略（见下节）
7. 用真实账号完整跑一遍登录、绑定、MFA 和邮箱补验路径

先配公开站点地址

外部认证的重定向 URI 依赖 公开站点地址。如果这里没填对，身份提供商回调会落到错误地址。改公开站点地址后，provider 侧登记的 redirect URI 也要同步更新。

账号绑定策略

AsterDrive 不把邮箱当成唯一身份来源。外部身份会优先按 identity_namespace + subject 匹配已有绑定。

策略	默认值	说明
要求已验证邮箱	开	provider 必须返回可用邮箱且 email_verified=true，否则进入补验或失败路径
按已验证邮箱自动绑定	关	只有 provider 返回 email_verified=true，并且本地存在唯一同邮箱用户时，才会自动绑定
自动创建本地用户	关	未绑定外部身份可以创建本地普通用户；仍受公开注册开关、邮箱域名和邮箱验证策略约束

保守建议：

• 对 OIDC 这类可信 provider，可以开启”要求已验证邮箱”
• 对不会可靠返回 email_verified=true 的 provider，不要开启”按已验证邮箱自动绑定”
• GitHub 专用 provider 只接受已验证主邮箱；QQ 不返回邮箱；Microsoft 不把 email 当作已验证主邮箱——这几家的细节和逐字段配置见 外部认证

如果外部身份不能直接登录，用户会走登录并绑定已有账号，或通过邮箱补验继续。邮箱补验依赖 管理 -> 系统设置 -> 邮件投递 的外部登录邮箱验证邮件模版，配置见 邮件投递。

删除提供商会删除对应外部身份绑定，但不会删除已经存在的本地用户。用户自己查看和解绑外部身份的入口在 设置 -> 安全 -> 外部身份。

上线前验收

• 保存时的测试按钮只检查 provider endpoint 配置和 discovery / endpoint 可达性，不会替你完成真实授权码登录
• 上线前必须用真实账号跑一次：登录、自动创建、自动绑定、MFA 二次验证、邮箱补验
• 每个 provider 的字段说明、默认 scope、claim 映射和常见报错（含 Microsoft AADSTS 系列），见 外部认证

哪些功能依赖邮件配置

下面这些功能没邮件就用不了：

• 公开注册后的激活邮件
• 登录页的找回密码
• 设置 -> 安全 里的邮箱改绑确认邮件
• 外部认证无法直接匹配本地账号时的邮箱验证流程
• 邮箱验证码 MFA

先配通邮件，再开放注册

顺序反了的话，新用户账号已经创建出来，却收不到激活邮件，只会卡在”等待激活”。配置顺序见 邮件投递。