安全策略
功能概述
认证安全策略(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),支持验证器应用、邮箱、短信及恢复码等因子。客户端需要接入相应的验证交互;具体策略和合规要求应结合业务及部署环境核实。
核心概念与架构
Agentbase 在注册、登录和修改密码等操作中应用项目安全策略。下表说明各项策略及其生效边界。
核心安全概念与机制说明
| 安全控制域 | 核心策略项 | 运行时执行语义与技术边界 |
|---|---|---|
| 总量防刷控制 | Users limit(用户注册上限) | 限制项目内可容纳的最大终端用户总数(Unlimited 或 1–10,000)。在普通项目中,非特权且非应用身份发起的团队邀请如果需要新建用户,也会检查上限;邀请已有用户不会触发此新增用户检查。特权或应用身份及 Console 项目不受该邀请检查约束。 |
| 会话生命周期 | Session length(会话有效期) | 定义新创建或续期会话的存活时长(支持按 Days、Hours、Minutes、Seconds 配置)。缩短时长后,后台清理可能按创建时间清除已超过新时长的旧会话;不要假设保存配置会立即注销已有会话。 |
| 并发设备淘汰 | Sessions limit(并发会话上限) | 限制单个终端用户可同时保持在线的最大设备/会话数(范围 1–100)。在下一次新登录成功时触发评估:若超出上限,系统按先进先出(FIFO)自动挤掉并销毁该用户最早创建的旧会话。 |
| 密码策略 | Password history / dictionary / personal data | 可配置历史密码、弱密码字典和个人信息检查。创建用户、自助改密、管理员改密及密码找回的校验路径并不完全相同;例如自助改密会按开关检查个人信息,密码找回路径未执行同一检查。启用策略后应分别验证业务使用的路径。 |
| 会话主动防御 | Session alerts & Invalidate sessions | 会话提醒:部分登录会在满足条件时将提醒邮件加入队列;不判断设备是否为新设备,也不保证送达。启用 Invalidate 后,自助改密在识别到当前会话时删除其他会话并保留当前会话;管理员修改用户密码时删除该用户的所有会话。密码找回路径不自动删除会话;需要全部下线时应显式撤销并核验。 |
| 多因素认证(MFA) | TOTP / Email / Phone / Recovery Codes | 账号开启 MFA 后,邮箱密码登录成功会先创建初始会话;在该会话完成所需因子验证前访问受保护接口,可能返回 user_more_factors_required。客户端应引导用户完成可用的第二因子挑战后再重试。 |
| 测试沙箱能力 | Mock phone numbers(模拟手机号) | 允许预先登记最多 10 组虚拟测试手机号(9–16 位)与固定 6 位数字验证码。登录该号码时不调用真实短信网关,直接校验预设验证码,专用于自动化 E2E 回归测试或 Apple App Store / 移动端应用市场审核演示。 |
| 多租户成员隐私 | Memberships privacy(团队成员隐私) | 控制同一团队的普通成员在客户端查询成员列表时,能否看到其他成员的 Name(姓名)、邮箱和 MFA 状态(多因素认证状态)。关闭对应复选框仅在响应中隐藏脱敏,不删除底层数据。 |
角色、入口与关联关系
控制台入口与快捷键
导航路径:登录 Agentbase Console → 进入项目
企业智能客服与知识中台(enterprise-ai-hub-210)→ 左侧导航栏 认证 → 点击顶部 安全 页签。路由地址:
/console/project-{region}-{project}/auth/security全局快捷键:在控制台任意页面按下
g后紧接着按e,即可通过命令中心直达 认证 → 安全 页面。操作权限门禁:查看与修改项目级 Auth 安全策略需要组织管理权限(
owner、admin、developer角色)。
与其他模块的关联关系
与用户管理(Auth Users)联动:
在 安全 页开启密码策略后,管理员在 认证 → 用户 创建用户或重设密码、以及终端用户在客户端修改密码时,使用的校验路径可能不同;请分别验证每种操作。
若某用户的 TOTP 验证器设备遗失,管理员可前往 认证 → 用户 → 用户详情 → 概览 → 多因素认证 卡片点击 删除验证器 解除绑定。
与邮件模板(Auth Templates)联动:
开启 会话安全 → 会话提醒 后,系统发送的新会话告警邮件内容由 认证 → 模板 中的 Session alert 模板定义(包含
{{device}}、{{ipAddress}}、{{country}}变量)。使用邮箱作为 MFA 第二因子时,验证码邮件内容由 2FA verification 模板定义。
与团队管理(Auth Teams)联动:
成员关系隐私 卡片的勾选状态直接决定客户端调用
teams.listMemberships(teamId)时返回的成员字段可见性。
功能详解与操作指南
进入认证 → 安全策略页面后,可以分别修改各项设置,并点击对应卡片中的保存。实际可修改的选项取决于项目权限:
图:2.12.0 测试项目的密码策略区域;实际策略请根据安全需求设置。
1. 七大安全策略卡片参数详解與推荐配置
下表汇总了每张卡片的配置字段、取值范围、系统默认行为以及面向生产环境(如 enterprise-ai-hub-210)的推荐安全基线:
| 卡片名称 | 配置字段 | 取值范围与约束 | 生产环境推荐基线(enterprise-ai-hub-210) | 关键行为与生效时机说明 |
|---|---|---|---|---|
| 用户数量限制 | Unlimited / Limited + 数量输入框 | 打开“不限制”,或关闭后填写 1–10000 | 公开 ToC/ToB 门户选 Unlimited;内部封闭试点项目可设 Limited(如 500) | 普通项目中,非特权且非应用身份邀请新用户时也会检查上限;邀请已有用户、特权或应用身份以及 Console 项目不受该邀请检查约束。 |
| 会话时长 | 时长数值 + 时间单位下拉框 | 单位可选天、小时、分钟或秒;换算后服务端上限为 31536000 秒 | 企业内部客服坐席建议设为 7 Days 或 24 Hours;高敏管理端建议 8 Hours | 控制台提示缩短有效期可能使已登录用户退出;调整前应在目标环境验证现有会话行为。 |
| 会话数量限制 | 最大并发会话数(Maximum number of active sessions per user) | 整数,1–100 | 建议设为 3 或 5(允许用户同时在桌面浏览器、移动端与平板登录);严格单点登录可设为 1 | 仅在该用户下一次新登录时触发检查:若当前活跃会话数已达上限,系统自动注销该用户最早创建的会话。 |
| 密码策略 | 密码历史 | 使用开关启停;开启后服务端接受历史条数 1–20,接口值 0 表示关闭 | 开启,并将 Limit 设为 5(禁止重复使用最近 5 次用过的密码) | 服务端安全保存历史密码哈希摘要,仅在用户新设置或修改密码时比对,不影响既有密码登录。 |
| Password policies | Password dictionary(弱密码字典) | 布尔开关(开 / 关) | 开启 | 拒绝常见弱口令与高频泄露密码(如 password123、qwertyuiop、admin888)。 |
| Password policies | Disallow personal data(禁止包含个人信息) | 布尔开关(开 / 关) | 开启 | 适用路径会检查密码是否包含完整用户 ID、完整邮箱或邮箱前缀、完整姓名、完整手机号(含或不含加号);不会检查这些字段的任意片段。不同密码操作的校验路径可能不同。 |
| 会话安全 | 会话提醒(新会话邮件提醒) | 布尔开关(开 / 关) | 开启(需确保项目 SMTP 已正常配置) | 符合条件时将含设备、IP 与国家信息的提醒邮件加入队列;不保证送达,触发条件见下文。 |
| 会话安全 | Invalidate(修改密码时处理会话) | 布尔开关(开 / 关) | 开启 | 自助改密仅在识别到当前会话时删除其他会话、保留当前会话;管理员改密删除该用户所有会话;找回密码不会通过此路径自动删除会话。需全部下线时请显式撤销会话并核验。 |
| 模拟手机号 | 模拟手机号列表(Phone number + Verification code) | 最多添加 10 条;手机号长 9–16 位,验证码固定为 6 位数字 | 仅在 测试环境或移动应用提审期间按需配置(如 +8619900000001 对应验证码 123456);生产环境清空或仅保留专用沙箱号 | 付费/授权能力:云端需对应套餐,自托管需开启授权。使用模拟号登录时跳过真实短信发送。 |
| 成员关系隐私 | Name / 邮箱 / MFA 状态 三个复选框 | 默认全部勾选(公开展示给同团队成员) | 跨企业客户共用的外部团队(如含 vip_guest 的团队)建议取消勾选 Email 与 MFA status,仅保留 Name | 取消勾选不会删除用户数据,仅在客户端查询团队成员列表时将对应字段脱敏隐藏,防止客户间信息泄露。 |
会话提醒触发条件:开启 Session alerts 后,邮箱密码登录创建会话时,仅当该用户的会话总数不等于 1 才将提醒邮件加入队列;令牌创建会话还要求用户有邮箱,且令牌类型不是 Magic URL 或邮箱令牌。这里检查的是会话数量,不比较设备;首次会话通常不会触发。同一设备的后续会话也可能触发。邮件是否送达取决于邮件服务和队列处理结果。
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.12.0)
当用户(如高级支持专家李娜 user_lina_002)已开启 MFA 时,前端登录与完成二次核验的标准流程如下:
运行前将 <APPBASE_ENDPOINT_WITH_V1> 和 <APPBASE_PROJECT_ID> 替换为已确认的目标 API 地址和项目 ID。未替换时 SDK 会拒绝无效地址,不会发送请求。
import { Client, Account, AuthenticationFactor } from 'agentbase-web-sdk'; // 版本固定 @2.12.0
const client = new Client()
.setEndpoint('<APPBASE_ENDPOINT_WITH_V1>')
.setProject('<APPBASE_PROJECT_ID>');
const account = new Account(client);
async function signInWithMFA(email, password, chooseFactorFromUI, getCodeFromUI) {
await account.createEmailPasswordSession(email, password);
try {
return await account.get();
} catch (error) {
if (error.type !== 'user_more_factors_required') throw error;
const factors = await account.listMfaFactors();
const available = [
factors.totp && AuthenticationFactor.Totp,
factors.email && AuthenticationFactor.Email,
factors.phone && AuthenticationFactor.Phone,
factors.recoveryCode && 'recoveryCode',
].filter(Boolean);
if (available.length === 0) throw new Error('No MFA factor available');
const factor = await chooseFactorFromUI(available);
if (!available.includes(factor)) throw new Error('Invalid MFA factor selection');
const challenge = await account.createMfaChallenge(factor);
const code = await getCodeFromUI(factor);
await account.updateMfaChallenge(challenge.$id, code);
return await account.get();
}
}当前 Web SDK 枚举中的 Recoverycode 值与服务端恢复码因子大小写不同;本 JavaScript 示例显式传入服务端接受的 recoveryCode。若使用 TypeScript 且 SDK 类型不接受该值,请核对 SDK 版本或通过 REST 接口传入 recoveryCode。
3. 配置模拟手机号(Mock phone numbers)操作步骤
在进行自动化 E2E 测试(如验证短信验证码登录流)或向应用商店提交审核演示账号时,频繁调用真实短信通道不仅产生费用,还容易触发运营商频控:
在 认证 → 安全 页面向下滚动至 模拟手机号 卡片。
点击 添加号码 按钮新增一行配置:
Phone number:输入 9–16 位测试专用虚拟手机号(例如
+8619900000001)。Verification code:输入固定的 6 位数字验证码(例如
654321)。
最多可添加 10 条模拟号码记录,填写完成后点击卡片右下角的 Update 保存。
测试验证:先确认目标环境已满足短信服务配置、权限及部署策略;模拟号码不会绕过这些前置检查。通过检查且命中模拟号码后,调用
account.createPhoneToken(ID.unique(), '+8619900000001')不会发送真实短信,再用返回的用户 ID 和预设验证码调用account.createSession(userId, '654321')创建会话。
常见问题与排障
Q1:我将 Session length 从 365 天缩短为 1 天,并将 Sessions limit 从 10 改为 1,为什么当前已经登录的用户没有立刻掉线?
原因分析: 这是 Agentbase 为避免配置变更引发线上大规模突发雪崩而设计的平滑过渡机制:
会话时长 在会话新建或续期时用于计算到期时间戳。缩短时长后,后台清理可能按创建时间清除超过新时长的旧会话;保存配置不代表立即全部下线。
Sessions limit 仅在该用户下一次发起新登录时执行并发数检查与最旧会话淘汰。
解决方案: 如果需要让某个特定用户(如离职员工或异常账号)的所有在线设备立即强制下线,请前往 认证 → 用户,点开该用户详情页,切换到 Sessions 页签,点击右上角的 退出所有会话(或直接在该用户的 概览 页签点击 封禁账户 封禁账号)。
Q2:开启了 Password dictionary 和 Disallow personal data 后,之前已经注册的老用户使用旧的简单密码还能登录吗?
回答: 已有密码不会因为开启新策略而被自动修改;具体登录结果仍取决于账号状态与其他认证要求。创建用户、自助改密、管理员改密和密码找回的校验路径不同,不能假设每条路径都执行完全相同的策略。需要更新弱密码时,请按实际部署环境验证相应密码策略与会话撤销效果。
Q3:用户开启了 TOTP 多因素认证后更换了新手机,无法生成 6 位动态验证码且未保存恢复码,如何解锁账号?
解决步骤:
管理员登录 Agentbase Console,进入项目 认证 → 用户。
搜索并点击进入该用户的详情页(
/auth/user-{userId})。在 概览 页签底部找到 多因素认证 卡片。
点击
TOTP (One-time code)右侧的 删除验证器 按钮并在弹窗中确认(注意:删除验证器操作不可逆)。或直接将用户的 MFA 总开关暂时关闭,待用户登录后重新绑定新手机的验证器 App。
相关文档
认证概览(Auth Overview):了解项目身份认证整体架构与凭据类型。
用户管理(Users):单点管理用户的 MFA 状态、强制注销活跃会话与封禁账户。
团队管理(Teams):了解团队成员关系以及与 成员关系隐私 策略的配合使用。
邮件模板(Templates):自定义 Session alert(新会话提醒)与 2FA verification(MFA 验证码)邮件内容。
