Aptli

身份验证

身份验证会在授予访问 Aptli 权限前确认您的身份。Aptli 支持用户名/密码登录、OAuth 单点登录（Google、GitHub、Microsoft、Keycloak）和双因素认证。本节介绍如何使用和配置每种方式、管理账户锁定以及处理密码重置。

当前登录方式

登录页面展示可用的认证方式，包括 OAuth 提供商

可配置的身份验证方式：

用户名/密码（默认）：

  • 电子邮件 + 密码组合
  • 密码要求：至少 8 个字符，满足复杂度规则
  • 闲置后自动注销（可配置，默认 1 天）

OAuth 提供商：

  • GitHub OAuth
  • Google OAuth
  • 可配置其他提供商（联系支持团队）

配置： 导航至应用设置 → 身份验证 → 有效登录方式

  • 至少需启用一种方式
  • 多种方式可同时激活
  • 用户可在登录界面选择首选方式

双因素认证（2FA）

启用双因素认证：

  1. 导航至用户个人资料页面
  2. 点击"启用双因素认证"
  3. 使用验证器应用（如 Google Authenticator、Authy 等）扫描 QR 码
  4. 输入 6 位验证码确认
  5. 保存恢复码（以防手机丢失）

使用双因素认证登录：

  1. 输入电子邮件和密码（或 OAuth）
  2. 系统提示输入 6 位验证码
  3. 打开身份验证器应用
  4. 输入当前验证码（每 30 秒刷新一次）
  5. 访问权限授予

恢复码：

  • 双因素认证设置时生成 10 个一次性代码
  • 安全存储（密码管理器、打印副本）
  • 当验证器不可用时使用
  • 每个代码仅限使用一次

禁用双因素认证：

  • 导航至用户个人资料
  • 点击"禁用双因素认证"
  • 输入当前 6 位验证码（或恢复码）
  • 确认禁用

识别未启用双因素认证的用户

管理员视图：

  1. 导航至管理员 → 用户
  2. 添加列："2FA 已启用"（布尔型）
  3. 筛选条件："2FA 已启用 = false"
  4. 导出列表以便后续跟进

强制执行： 应用设置 → 身份验证 → 要求使用双因素认证

  • 启用后强制所有用户设置双因素认证
  • 宽限期可配置（例如 30 天）
  • 宽限期结束后，用户必须启用双因素认证才能登录

通知活动：

  • 向未启用双因素认证的用户群发邮件
  • 附上设置说明
  • 强调安全优势
  • 设定合规截止日期

OAuth 提供商设置

OAuth 提供商（Google、GitHub、Microsoft、Keycloak）由系统管理员配置。配置详情请参阅 OAuth 配置指南。

为用户账户添加 OAuth

现有用户名/密码用户操作指南：

  1. 使用电子邮件和密码登录
  2. 导航至用户个人资料页面
  3. 点击"关联 OAuth 账户"
  4. 选择提供商（GitHub 或 Google）
  5. 通过提供商授权
  6. OAuth 账户关联成功（现可通过任一方式登录）

新用户须知：

  • 首次通过 OAuth 登录将自动创建账户
  • OAuth 提供商的电子邮件必须属于允许的域名范围
  • 账户仅通过 OAuth 登录创建（不设置密码）
  • 后续可从个人资料中添加密码

电子邮件验证

新用户流程：

  1. 用户注册（或管理员创建账户）
  2. 向用户电子邮件发送验证邮件
  3. 邮件内含 10 分钟有效期的验证令牌
  4. 用户点击邮件中的链接
  5. 账户验证成功（现可登录）

验证要求：

  • 电子邮件未验证前无法登录（任何方式）
  • 包含 OAuth 用户（即使提供商已验证，电子邮件仍需验证）

重新发送验证邮件： 管理员可从用户资料页重新发送：

  1. 导航至管理员 → 用户
  2. 打开用户资料页
  3. 点击"重新发送验证邮件"
  4. 系统发送新的 10 分钟有效令牌

手动验证： 拥有 usersUpdate 权限的管理员可手动验证：

  1. 导航至用户个人资料
  2. 将"电子邮件验证"日期设置为当前日期
  3. 保存（用户现可登录）

登录安全

最大登录尝试次数：

  • 默认值：5 次失败尝试
  • 可在应用设置中配置
  • 超出最大尝试次数后：账户强制锁定
  • 解锁需具备 usersUpdate 权限的管理员操作

强制锁定：

  • 账户无法登录（任何方式）
  • 用户资料页显示"强制锁定"标识
  • 解锁：管理员点击"解锁账户"操作
  • 重置：失败尝试计数器重置为 0

会话过期：

  • 自动注销： 闲置超时（默认 1 天）
    • 读写数据将重置倒计时
    • 可通过应用设置单独配置
  • 服务器会话超时： 服务器端会话超时（默认 1 周）
    • 强制重新登录（无论是否有活动）
    • 长时会话的安全防护措施
  • 会话过期： 绝对最大会话时长（默认 1 周）
    • 防止无限期会话

单一活动会话：

  • Aptli 每个账户同一时间仅允许一个活动会话
  • 在新设备上登录会使其他设备退出登录
  • 在已被退出的设备上会看到提示，并需要重新登录
  • 同一浏览器配置内的多个标签页或窗口共享一个会话——它们不会互相退出

强制注销

管理员操作：

  1. 导航至管理 → 用户
  2. 打开用户个人资料
  3. 操作 → 强制注销
  4. 用户会话立即终止
  5. 用户必须重新登录

使用场景：

  • 安全事件（账户遭入侵）
  • 用户在公共电脑上未关闭会话
  • 管理员锁定（待调查处理）

登录故障排除

用户无法找到账户

检查步骤：

  1. 导航至管理 → 用户
  2. 按电子邮件筛选（区分大小写）
  3. 若未找到：账户可能已被删除
  4. 点击"查看已删除"按钮（需 viewDeleted 权限）
  5. 若在已删除列表中找到：恢复账户（需 usersCreate 权限）

强制锁定

检查步骤：

  1. 导航至用户个人资料
  2. 查找"强制锁定"标识
  3. 若存在：点击"解锁账户"（需 usersUpdate 权限）
  4. 用户现可登录

电子邮件未验证

检查步骤：

  1. 导航至用户个人资料页面
  2. "电子邮件验证"字段应显示日期
  3. 若为空白：重新发送验证邮件 或 手动设置日期
  4. 未验证用户无法通过任何方式登录

域名验证失败

处理：

  1. 导航至应用设置 → 身份验证
  2. 检查"允许的域名"列表
  3. 确认用户电子邮件域名是否包含在内
  4. 若缺失：添加域名 或 手动创建账户（绕过域名验证）

OAuth 无法正常工作

检查事项：

  1. 验证环境变量设置（CLIENT_ID、CLIENT_SECRET）
  2. 检查回调 URL 是否与提供商配置匹配
  3. 测试：注销后点击"使用提供商登录"
  4. 查看浏览器控制台中的错误信息
  5. 在提供商控制台中检查认证尝试记录

密码重置

用户主动操作：

  1. 在登录页面点击"忘记密码"
  2. 输入电子邮件地址
  3. 重置邮件发送（含 10 分钟有效令牌）
  4. 点击邮件中的链接
  5. 输入新密码
  6. 密码重置完成（现可登录）

管理员操作： 具备 usersUpdate 权限的管理员可执行重置：

  1. 导航至用户个人资料页面
  2. 操作 → 重置密码
  3. 生成临时密码
  4. 向用户发送含临时密码的邮件
  5. 用户首次登录时必须修改密码

最佳实践

启用双因素认证：

  • 所有管理员账户必须启用
  • 鼓励所有用户启用
  • 设定合规截止日期

尽可能使用 OAuth：

  • 减轻密码负担
  • 借助提供商的安全性
  • 简化账户恢复流程

监控失败登录：

  • 每周审查强制锁定账户
  • 锁定模式表明存在密码猜测攻击
  • 启用双因素认证强制执行

常规会话过期：

  • 勿将闲置超时时间设得太长（24 小时为宜）
  • 服务器会话超时可防止无限期会话
  • 在安全性与用户便利性间取得平衡

允许的域名：

  • 严格控制列表（仅限组织域名）
  • 外部承包商 = 手动创建（绕过域名检查）
  • 每季度审核（移除未使用域名）