安全策略
功能概述
认证安全策略(Security)是 Agentbase 项目级的身份安全控制中枢(路由:/console/project-{region}-{project}/auth/security)。在企业生产环境(如示例项目 **企业智能客服与知识中台**,Project ID:enterprise-ai-hub-210)中,安全管理员可通过该页面的七张核心配置卡片,一站式定义项目的终端用户注册总量上限(Users limit)、登录会话有效期(Session length)、单用户最大并发在线设备数(Sessions limit)、企业级密码合规策略(Password policies:历史密码防重用、弱密码字典拦截、个人敏感信息防包含)、会话安全告警与改密自动踢出(Session security)、面向测试与移动应用商店审核的模拟手机号(Mock phone numbers),以及多租户团队成员之间的隐私可见性边界(Memberships privacy)。
此外,结合 Agentbase 的多因素认证(MFA,涵盖 TOTP 验证器应用、邮箱 OTP、短信验证码与一次性恢复码),企业可以在不改动前端业务代码结构的前提下,快速满足金融、政务与大型企业内控对身份鉴别、口令复杂度、并发会话管控及多因子核验的等保与合规要求。所有在 Auth → Security 页面保存的策略均实时写入项目元数据,并立即对整个项目的后续认证请求生效。
核心概念与架构
Agentbase 在终端用户发起注册、登录、修改密码、创建多因素挑战(MFA Challenge)及查询团队成员列表的各个环节,均嵌入了同步策略拦截器(Policy Enforcers)。下图展示了项目级安全策略在用户认证全链路中的执行位置与控制逻辑:
flowchart TB
subgraph RegAndPass["注册与密码合规门禁 (Registration & Password Policies)"]
RegReq["新用户自助注册请求"]
LimitGate{"1. Users limit 检查<br/>当前用户数 < 注册上限?"}
PassChange["设置 / 重置密码请求"]
DictGate{"2. Password dictionary<br/>命中常见弱密码库?"}
PersonalGate{"3. Disallow personal data<br/>含姓名/邮箱/手机号片段?"}
HistGate{"4. Password history<br/>与最近 N 次历史密码重复?"}
end
subgraph LoginAndMFA["登录、MFA 与并发会话门禁 (Session & MFA Enforcement)"]
LoginReq["账号密码 / OAuth2 / 手机验证码登录"]
MockCheck{"命中 Mock phone numbers?<br/>(仅限测试/审核演示号段)"}
MFAGate{"用户已开启 MFA?<br/>(TOTP / Email / Phone / 恢复码)"}
ConcGate{"5. Sessions limit 检查<br/>活跃会话数 > 并发上限?"}
EvictOld["自动驱逐该用户最旧会话<br/>(FIFO 淘汰)"]
IssueSession["签发新 Session<br/>按 Session length 计算过期时间"]
AlertHook{"6. Session alerts 开启?"}
SendAlert["异步发送新会话登录提醒邮件"]
end
subgraph RuntimePrivacy["运行时改密失效与隐私脱敏"]
InvalidateGate{"7. Invalidate sessions 开启?<br/>(用户改密后触发)"}
ClearSessions["销毁该用户既有活跃会话"]
TeamQuery["客户端查询团队成员列表"]
PrivacyFilter["8. Memberships privacy 过滤<br/>按需隐藏 Name / Email / MFA status"]
end
RegReq --> LimitGate
LimitGate -->|未超限| PassChange
PassChange --> DictGate --> PersonalGate --> HistGate
HistGate -->|全部通过| LoginReq
LoginReq --> MockCheck --> MFAGate
MFAGate -->|MFA 验证通过或未启用| ConcGate
ConcGate -->|超限| EvictOld --> IssueSession
ConcGate -->|未超限| IssueSession
IssueSession --> AlertHook -->|是| SendAlert
PassChange --> InvalidateGate -->|是| ClearSessions
TeamQuery --> PrivacyFilter核心安全概念与机制说明
| 安全控制域 | 核心策略项 | 运行时执行语义与技术边界 |
|---|---|---|
| 总量防刷控制 | Users limit(用户注册上限) | 限制项目内可容纳的最大终端用户总数(Unlimited 或 1–10,000)。仅拦截客户端自助新注册;管理员从 Console 手动创建用户或通过团队邀请创建成员不受此上限阻断。 |
| 会话生命周期 | Session length(会话有效期) | 定义新创建或续期会话的存活时长(支持按 Days、Hours、Minutes、Seconds 配置)。修改该配置仅影响保存后新创建或续期的会话,不会立即注销线上已有会话。 |
| 并发设备淘汰 | Sessions limit(并发会话上限) | 限制单个终端用户可同时保持在线的最大设备/会话数(范围 1–100)。在下一次新登录成功时触发评估:若超出上限,系统按先进先出(FIFO)自动挤掉并销毁该用户最早创建的旧会话。 |
| 口令强度合规 | Password history / dictionary / personal data | 强制校验新设置的密码:不得与最近 1–20 次历史密码重复、不得命中内置的数万条常见弱密码字典(如 12345678、password)、不得包含用户自身的姓名、邮箱前缀或手机号片段。 |
| 会话主动防御 | Session alerts & Invalidate sessions | Session alerts:检测到新设备登录创建会话时自动向用户邮箱发送安全提醒邮件;Invalidate:用户修改密码后自动使其名下所有既有会话立即失效,阻断潜在盗号者继续持旧令牌访问。 |
| 多因素认证(MFA) | TOTP / Email / Phone / Recovery Codes | 当账号开启 MFA 后,第一因子(如账号密码)验证通过后仅返回需二次核验的中间态(user_more_factors_required),客户端必须完成验证器 App 动态码(TOTP)、邮箱验证码或短信验证码挑战后才能正式访问受保护资源。 |
| 测试沙箱能力 | Mock phone numbers(模拟手机号) | 允许预先登记最多 10 组虚拟测试手机号(9–16 位)与固定 6 位数字验证码。登录该号码时不调用真实短信网关,直接校验预设验证码,专用于自动化 E2E 回归测试或 Apple App Store / 移动端应用市场审核演示。 |
| 多租户成员隐私 | Memberships privacy(团队成员隐私) | 控制同一团队的普通成员在客户端查询成员列表时,能否看到其他成员的 Name(姓名)、Email(邮箱)和 MFA status(多因素认证状态)。关闭对应复选框仅在响应中隐藏脱敏,不删除底层数据。 |
角色、入口与关联关系
控制台入口与快捷键
- 导航路径:登录 Agentbase Console → 进入项目
企业智能客服与知识中台(enterprise-ai-hub-210)→ 左侧导航栏 Auth → 点击顶部 Security 页签。 - 路由地址:
/console/project-{region}-{project}/auth/security - 全局快捷键:在控制台任意页面按下
g后紧接着按e,即可通过命令中心直达 Auth → Security 页面。 - 操作权限门禁:查看与修改项目级 Auth 安全策略需要组织管理权限(
owner、admin、developer角色)。
与其他模块的关联关系
- 与用户管理(Auth Users)联动:
- 在 Security 页开启密码策略后,管理员在 Auth → Users 创建用户或重设密码、以及终端用户在客户端修改密码时,均受相同密码规则约束。
- 若某用户的 TOTP 验证器设备遗失,管理员可前往 Auth → Users → 用户详情 → Overview → Multi-factor authentication 卡片点击 Delete authenticator 解除绑定。
- 与邮件模板(Auth Templates)联动:
- 开启 Session security → Session alerts 后,系统发送的新会话告警邮件内容由 Auth → Templates 中的 Session alert 模板定义(包含
{{device}}、{{ipAddress}}、{{country}}变量)。 - 使用邮箱作为 MFA 第二因子时,验证码邮件内容由 2FA verification 模板定义。
- 开启 Session security → Session alerts 后,系统发送的新会话告警邮件内容由 Auth → Templates 中的 Session alert 模板定义(包含
- 与团队管理(Auth Teams)联动:
- Memberships privacy 卡片的勾选状态直接决定客户端调用
teams.listMemberships(teamId)时返回的成员字段可见性。
- Memberships privacy 卡片的勾选状态直接决定客户端调用
功能详解与操作指南
进入 Auth → Security 页面后,从上至下依次排列七张策略配置卡片。每张卡片支持独立修改并点击右下角的 Update 按钮立即保存生效:
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
1. 七大安全策略卡片参数详解與推荐配置
下表汇总了每张卡片的配置字段、取值范围、系统默认行为以及面向生产环境(如 enterprise-ai-hub-210)的推荐安全基线:
| 卡片名称 | 配置字段 | 取值范围与约束 | 生产环境推荐基线(enterprise-ai-hub-210) | 关键行为与生效时机说明 |
|---|---|---|---|---|
| Users limit | Unlimited / Limited + 数量输入框 | Unlimited(不限)或 Limited(1–10000;输入 0 保存等同于 Unlimited) | 公开 ToC/ToB 门户选 Unlimited;内部封闭试点项目可设 Limited(如 500) | 仅限制客户端新用户注册接口;Console 管理员手动创建用户或团队邀请不受限制。 |
| Session length | 时长数值 + 时间单位下拉框 | 单位可选 Days(天)、Hours(小时)、Minutes(分钟)、Seconds(秒) | 企业内部客服坐席建议设为 7 Days 或 24 Hours;高敏管理端建议 8 Hours | 仅在新建会话或会话续期时按当前配置计算过期时间;保存修改本身不会立即踢出当前在线用户。 |
| Sessions limit | 最大并发会话数(Maximum number of active sessions per user) | 整数,1–100 | 建议设为 3 或 5(允许用户同时在桌面浏览器、移动端与平板登录);严格单点登录可设为 1 | 仅在该用户下一次新登录时触发检查:若当前活跃会话数已达上限,系统自动注销该用户最早创建的会话。 |
| Password policies | Password history(密码历史) | 开关 + 历史记忆条数 Limit(1–20;保存 0 表示关闭) | 开启,并将 Limit 设为 5(禁止重复使用最近 5 次用过的密码) | 服务端安全保存历史密码哈希摘要,仅在用户新设置或修改密码时比对,不影响既有密码登录。 |
| Password policies | Password dictionary(弱密码字典) | 布尔开关(开 / 关) | 开启 | 拒绝常见弱口令与高频泄露密码(如 password123、qwertyuiop、admin888)。 |
| Password policies | Disallow personal data(禁止包含个人信息) | 布尔开关(开 / 关) | 开启 | 校验新密码中不得包含该用户自身的 Name、Email(含邮箱前缀)或 Phone 的任何子串片段。 |
| Session security | Session alerts(新会话邮件提醒) | 布尔开关(开 / 关) | 开启(需确保项目 SMTP 已正常配置) | 每当用户账号产生新的登录会话时,自动向其绑定邮箱发送含登录设备、IP 与国家信息的提醒邮件。 |
| Session security | Invalidate(修改密码后失效全部会话) | 布尔开关(开 / 关) | 开启 | 当用户完成密码修改或重置后,服务端立即清理并销毁该用户的所有既有会话,强制重新登录。 |
| Mock phone numbers | 模拟手机号列表(Phone number + Verification code) | 最多添加 10 条;手机号长 9–16 位,验证码固定为 6 位数字 | 仅在 SIT 测试或移动应用提审期间按需配置(如 +8619900000001 对应验证码 123456);生产环境清空或仅保留专用沙箱号 | 付费/授权能力:云端需对应套餐,自托管需开启授权。使用模拟号登录时跳过真实短信发送。 |
| Memberships privacy | Name / Email / MFA status 三个复选框 | 默认全部勾选(公开展示给同团队成员) | 跨企业客户共用的外部团队(如含 vip_guest 的团队)建议取消勾选 Email 与 MFA status,仅保留 Name | 取消勾选不会删除用户数据,仅在客户端查询团队成员列表时将对应字段脱敏隐藏,防止客户间信息泄露。 |
2. 多因素认证(MFA)端到端工作流指南
Agentbase 支持终端用户自主绑定并开启多因素认证(MFA),支持四种核验因子:
- TOTP 验证器应用(Authenticator App):兼容 Google Authenticator、Microsoft Authenticator、1Password 等标准 TOTP 应用(动态 6 位验证码,每 30 秒轮换)。
- 邮箱二次验证(Email MFA):向用户已验证(
emailVerification = true)的绑定邮箱发送一次性 6 位验证码。 - 手机短信二次验证(Phone MFA):向用户已验证(
phoneVerification = true)的绑定手机号发送一次性 6 位短信验证码。 - 一次性恢复码(Recovery Codes):开启 MFA 时生成的一组备用恢复码,供手机遗失或无法接收验证码时应急核验。
客户端集成 MFA 登录与挑战核验代码示例(agentbase-web-sdk@2.10.0)
当用户(如高级支持专家李娜 user_lina_002)已开启 MFA 时,前端登录与完成二次核验的标准流程如下:
import { Client, Account, AuthenticationFactor } from 'agentbase-web-sdk'; // 版本固定 @2.10.0
const client = new Client()
.setEndpoint('https://appbuild.oceanbase.com/v1')
.setProject('enterprise-ai-hub-210');
const account = new Account(client);
async function signInWithMFA(email, password, getTotpCodeFromUI) {
// 第一步:常规邮箱密码登录,创建初始会话
await account.createEmailPasswordSession(email, password);
try {
// 尝试读取当前账号信息;若该用户启用了 MFA 且尚未完成二次验证,服务端将抛出 user_more_factors_required
const user = await account.get();
return user;
} catch (error) {
if (error.type === 'user_more_factors_required') {
// 第二步:查询该用户可用的 MFA 因子(如 totp / email / phone)
const factors = await account.listMfaFactors();
// 第三步:发起 TOTP(或 Email / Phone)挑战
const challenge = await account.createMfaChallenge(
factors.totp ? AuthenticationFactor.Totp : AuthenticationFactor.Email
);
// 第四步:引导用户输入 6 位动态验证码并完成挑战核验
const otpCode = await getTotpCodeFromUI();
await account.updateMfaChallenge(challenge.$id, otpCode);
// 核验通过后,当前会话正式升级为完全授权状态
return await account.get();
}
throw error;
}
}3. 配置模拟手机号(Mock phone numbers)操作步骤
在进行自动化 E2E 测试(如验证短信验证码登录流)或向应用商店提交审核演示账号时,频繁调用真实短信通道不仅产生费用,还容易触发运营商频控:
- 在 Auth → Security 页面向下滚动至 Mock phone numbers 卡片。
- 点击 Add number 按钮新增一行配置:
- Phone number:输入 9–16 位测试专用虚拟手机号(例如
+8619900000001)。 - Verification code:输入固定的 6 位数字验证码(例如
654321)。
- Phone number:输入 9–16 位测试专用虚拟手机号(例如
- 最多可添加 10 条模拟号码记录,填写完成后点击卡片右下角的 Update 保存。
- 测试验证:在客户端调用
account.createPhoneToken(ID.unique(), '+8619900000001')时,系统不会向短信网关发起请求,直接返回成功;随后调用account.createSession(userId, '654321')即可直接创建真实有效的终端用户会话。
常见问题与排障
Q1:我将 Session length 从 365 天缩短为 1 天,并将 Sessions limit 从 10 改为 1,为什么当前已经登录的用户没有立刻掉线?
原因分析: 这是 Agentbase 为避免配置变更引发线上大规模突发雪崩而设计的平滑过渡机制:
- Session length 仅在会话新建或续期时用于计算到期时间戳,修改配置本身不会回写或销毁数据库中已存在的活跃会话。
- Sessions limit 仅在该用户下一次发起新登录时执行并发数检查与最旧会话淘汰。
解决方案: 如果需要让某个特定用户(如离职员工或异常账号)的所有在线设备立即强制下线,请前往 Auth → Users,点开该用户详情页,切换到 Sessions 页签,点击右上角的 Sign out all sessions(或直接在该用户的 Overview 页签点击 Block account 封禁账号)。
Q2:开启了 Password dictionary 和 Disallow personal data 后,之前已经注册的老用户使用旧的简单密码还能登录吗?
回答: 可以正常登录。所有的密码合规策略(Password history、Password dictionary、Disallow personal data)仅在创建新用户、用户修改密码或重置密码(即对密码字段执行写操作)时触发校验,系统不会在常规登录验证时强制拦截历史存量密码(因为服务端只存储不可逆的密码哈希值,不保存明文)。若需强制存量用户升级密码强度,可引导用户走密码重置(Reset password)流程。
Q3:用户开启了 TOTP 多因素认证后更换了新手机,无法生成 6 位动态验证码且未保存恢复码,如何解锁账号?
解决步骤:
- 管理员登录 Agentbase Console,进入项目 Auth → Users。
- 搜索并点击进入该用户的详情页(
/auth/user-{userId})。 - 在 Overview 页签底部找到 Multi-factor authentication 卡片。
- 点击
TOTP (One-time code)右侧的 Delete authenticator 按钮并在弹窗中确认(注意:删除验证器操作不可逆)。或直接将用户的 MFA 总开关暂时关闭,待用户登录后重新绑定新手机的验证器 App。
相关文档
- 认证概览(Auth Overview):了解项目身份认证整体架构与凭据类型。
- 用户管理(Users):单点管理用户的 MFA 状态、强制注销活跃会话与封禁账户。
- 团队管理(Teams):了解团队成员关系以及与 Memberships privacy 策略的配合使用。
- 邮件模板(Templates):自定义 Session alert(新会话提醒)与 2FA verification(MFA 验证码)邮件内容。