Apereo CAS Simple MFA 令牌管理完全指南:内部 Ticket Registry 存储与外部 REST 托管两种模式
Apereo CAS Simple MFA 令牌管理完全指南:内部 Ticket Registry 存储与外部 REST 托管两种模式
Simple MFA(Simple Multifactor Authentication)是 Apereo CAS 提供的一种轻量级多因素认证方案,它向用户的邮箱、手机或应用内通知发送一次性验证码(Token/Code)。本文聚焦该方案中最关键的一环——令牌(Token)的生成、存储与验证管理:CAS 既可以完全自主地管理令牌(默认模式,基于 Ticket Registry 并受可配置过期策略约束),也可以将令牌的生成与校验全权委托给外部 REST 服务。读完本文,你将掌握 Simple MFA 令牌的两种管理模式、全部核心配置项及其默认值、底层源码实现原理,并能够根据实际负载与安全需求正确调整令牌长度、类型和存活时间。
一、两种令牌管理模式总览
令牌的管理与签发可以由 CAS 直接负责,也可以外包给外部系统与 REST 服务,二者互斥择一使用:
| 模式 | 管理主体 | 存储位置 | 适用场景 |
|---|---|---|---|
| 默认模式(CAS 自管) | CAS 自身 | Ticket Registry | 开箱即用、无需额外系统;令牌的生成、验证完全由 CAS 依据预配置策略与组件完成 |
| REST 模式(外部托管) | 外部 REST API | 外部系统 | 需要与企业已有令牌服务/短信网关集成,或希望令牌生命周期完全由外部系统控制 |
从源码结构看,两种模式的切换由配置类 CasSimpleMultifactorAuthenticationRestConfiguration 与 CasSimpleMultifactorAuthenticationConfiguration 共同决定(位于 support/cas-server-support-simple-mfa/src/main/java/org/apereo/cas/config):当配置了 REST 端点属性时,CAS 装配 RestfulCasSimpleMultifactorAuthenticationService;否则装配默认的 DefaultCasSimpleMultifactorAuthenticationService。两者都实现统一的 CasSimpleMultifactorAuthenticationService 接口,暴露 generate、store、validate、fetch、update 五个核心方法,因此 webflow 层(发送、验证 action)无需关心底层采用哪种模式。
二、默认模式:CAS 自行管理令牌
在默认情况下,CAS 签发的每个 Simple MFA 令牌都会被封装为一个 CASMFA 前缀的票据(Ticket),并通过 Ticket Registry 进行跟踪,同时被赋予一个可配置的过期策略。整个生命周期(生成 → 发送 → 用户输入 → 验证 → 销毁)完全由 CAS 内部的预配置策略与组件负责。
2.1 令牌的数据结构
令牌在 CAS 内部被建模为 CasSimpleMultifactorAuthenticationTicket(见 CasSimpleMultifactorAuthenticationTicket.java):
- 票据前缀固定为
CASMFA,即令牌的完整 ID 形如CASMFA-<code>; - 票据实现了
ServiceAwareTicket与PropertiesAwareTicket,可携带关联的 Service 以及任意可序列化属性; - 属性键
principal(见 CasSimpleMultifactorAuthenticationConstants.java)用于记录该令牌所属的认证主体(Principal),这是后续验证阶段进行"令牌与登录者匹配"判定的关键依据; - 属性键
code用于无状态 Ticket Registry 场景:当令牌被以另一个 ID 存储时,用户实际输入的正确验证码保存在code属性中,验证时通过CasSimpleMultifactorAuthenticationTicket.getCode(ticket)静态方法优先读取该属性,否则回退到票据 ID 本身。
CasSimpleMultifactorAuthenticationTicketImpl 继承自 AbstractTicket,并借助 Jackson 注解支持序列化,从而可以持久化到任意 Ticket Registry(内存、Redis、MongoDB、JPA 等)中(实现见 CasSimpleMultifactorAuthenticationTicketImpl.java)。
2.2 过期策略:硬超时(HardTimeout)
令牌的有效期由专用构建器 CasSimpleMultifactorAuthenticationTicketExpirationPolicyBuilder.java 生成。从源码可以确认,它读取 cas.authn.mfa.simple.token.core.timeToKillInSeconds 配置,并构造一个 HardTimeoutExpirationPolicy(硬超时过期策略)——即令牌从创建时刻起经过指定秒数后立即失效,无法续期:
val simple = casProperties.getAuthn().getMfa().getSimple();
return new HardTimeoutExpirationPolicy(simple.getToken().getCore().getTimeToKillInSeconds());
该构建器在 CasSimpleMultifactorAuthenticationConfiguration.java 中被注册为 casSimpleMultifactorAuthenticationTicketExpirationPolicy Bean,并在令牌创建时经 CasSimpleMultifactorAuthenticationTicketFactory.buildExpirationPolicy(...) 注入到新票据中(见 CasSimpleMultifactorAuthenticationTicketFactory.java)。
三、核心配置参数详解(cas.authn.mfa.simple.token.core.*)
Simple MFA 令牌的核心配置集中在 cas.authn.mfa.simple.token.core 命名空间下,属性模型定义于 CoreCasSimpleMultifactorAuthenticationTokenProperties.java。下表列出全部参数、默认值与含义:
| 配置项 | 默认值 | 含义 |
|---|---|---|
cas.authn.mfa.simple.token.core.time-to-kill-in-seconds |
30 |
令牌在 CAS 中被视为有效的存活时间(秒),由硬超时过期策略强制执行。考虑到用户读取邮件/短信并输入验证码的耗时,默认 30 秒通常需要按业务体验调大(如 120~300) |
cas.authn.mfa.simple.token.core.token-length |
6 |
生成令牌的长度(字符或数字个数)。注意:长度过小(小于 6 位)在高负载下极易产生碰撞 |
cas.authn.mfa.simple.token.core.token-type |
NUMERIC |
令牌使用的字符类型,取值为枚举 TokenType,见下方说明 |
3.1 token-type 三种取值
token-type 对应源码中的枚举 TokenType,直接影响 CasSimpleMultifactorAuthenticationUniqueTicketIdGenerator 的随机码生成方式(见 CasSimpleMultifactorAuthenticationUniqueTicketIdGenerator.java):
| 取值 | 生成方式 | 典型用途 |
|---|---|---|
NUMERIC |
RandomUtils.randomNumeric(tokenLength),纯数字 |
短信/电话播报场景,用户口述输入最友好,为默认值 |
ALPHANUMERIC |
RandomUtils.randomAlphanumeric(tokenLength),字母+数字混合 |
验证码安全性更高但输入不便 |
ALPHABETIC |
RandomUtils.randomAlphabetic(tokenLength),纯字母 |
特定场景定制 |
生成的随机码最终拼上 CASMFA- 前缀成为完整票据 ID:return prefix + SEPARATOR + code;。
3.2 关键使用警告:短验证码碰撞风险
使用警告! 生成较短长度(即小于
6个字符或数字)的验证码,在较高负载下可能导致验证码创建碰撞。CAS 会针对每次尝试重试以生成并保留唯一验证码,但若始终无法生成并保留唯一验证码,最终可能放弃尝试。
这一警告在原文档与配置模型源码的 Javadoc 中均有明确声明。其底层实现位于 DefaultCasSimpleMultifactorAuthenticationService.java:生成流程通过 FunctionUtils.doAndRetry(..., MAX_ATTEMPTS) 包装,其中 MAX_ATTEMPTS = 5。每次生成后都会查询 ticketRegistry.getTicket(token.getId()) 检查是否已存在同 ID 票据,若已存在则抛出 IllegalArgumentException 触发重试,最多重试 5 次:
return FunctionUtils.doAndRetry(() -> {
val token = FunctionUtils.doAndThrow(() -> mfaFactory.create(service, properties), RuntimeException::new);
val trackingToken = ticketRegistry.getTicket(token.getId());
if (trackingToken != null) {
throw new IllegalArgumentException("Token: " + trackingToken.getId() + " already exists in ticket registry");
}
return token;
}, MAX_ATTEMPTS);
因此,生产环境务必保持默认的 6 位及以上长度;如确需缩短,应同步评估并发签发峰值与碰撞概率,并接受极少数用户可能收不到验证码的兜底重发体验。
四、REST 模式:将令牌管理外包给外部系统
除了 CAS 自管,令牌的管理与签发也可以完全外包给外部系统与 REST 服务。此时 CAS 通过 RestfulCasSimpleMultifactorAuthenticationService.java 与外部端点交互,整个令牌的生成、存储、验证、查询与更新均由外部 API 裁决。
4.1 REST 配置属性
REST 模式的配置位于 cas.authn.mfa.simple.token.rest 命名空间,属性模型 RestfulCasSimpleMultifactorAuthenticationTokenProperties.java 继承自 CAS 通用的 RestEndpointProperties,核心参数如下:
| 配置项 | 含义 |
|---|---|
cas.authn.mfa.simple.token.rest.url |
外部 REST 端点的基础地址,必须指向提供令牌管理能力的服务 |
cas.authn.mfa.simple.token.rest.headers |
附加到每次 REST 请求的 HTTP 头(Map 形式) |
cas.authn.mfa.simple.token.rest.basic-auth-username / basic-auth-password |
调用外部端点时的 Basic Auth 凭证 |
cas.authn.mfa.simple.token.rest.maximum-retry-attempts |
请求失败时的最大重试次数 |
4.2 REST 端点契约
结合 RestfulCasSimpleMultifactorAuthenticationService 源码,外部服务需要按以下契约提供能力(除 new 外均基于 url 拼接):
| 方法 | HTTP 方法与路径 | 请求体 | 期望响应 |
|---|---|---|---|
生成令牌 generate |
POST {url}/new |
序列化后的 Principal(JSON),可附加 service 请求参数 |
2xx,响应体为令牌字符串,CAS 据此创建 CASMFA 票据 |
存储令牌 store |
POST {url} |
序列化后的令牌票据(JSON) | 非 4xx/5xx 即视为成功 |
验证令牌 validate |
POST {url}/{token} |
序列化后的已解析 Principal(JSON) | 2xx,响应体为序列化后的 Principal 对象 |
查询主体 fetch |
GET {url}/{token} |
无 | 2xx,响应体为序列化后的 Principal 对象 |
更新主体 update |
PUT {url} |
{"principal": ..., "attributes": ...}(JSON) |
2xx |
需要注意:REST 模式下令牌 ID 的 CASMFA- 前缀规范化、Principal 匹配校验等逻辑仍由 BaseCasSimpleMultifactorAuthenticationService 基类承担(见 BaseCasSimpleMultifactorAuthenticationService.java),外部系统主要负责"发号"与"验号"。
五、源码级流程:令牌从生成到验证的完整链路
无论采用哪种模式,Simple MFA 的令牌生命周期都围绕统一服务接口展开。以默认模式为例,完整链路如下:
- 生成(generate):
CasSimpleMultifactorSendTokenAction.doExecuteInternal调用multifactorAuthenticationService.generate(principal, service)创建令牌。若 webflow 上下文中已存在未过期令牌则复用,否则新生成(见 CasSimpleMultifactorSendTokenAction.java); - 派发(communication):依据
CasSimpleMultifactorTokenCommunicationStrategy决定的策略(SMS/PHONE/EMAIL/NOTIFICATION四种通道,见 CasSimpleMultifactorTokenCommunicationStrategy.java),通过CommunicationsManager将验证码发给用户; - 存储(store):任一派发通道成功后,调用
store(token)将票据写入 Ticket Registry(默认实现为新增或更新票据),并把存储后的票据 ID 记录到 flow credential 的ticketId字段(trackStoredToken),以便无状态注册表场景下正确比对; - 验证(validate):用户回填验证码后,
DefaultCasSimpleMultifactorAuthenticationService.validate依次执行:① 通过 bucket4j 令牌桶对同一 Principal 的验证尝试做限流(BucketConsumer.consume),被限流则直接抛出FailedLoginException;② 从 Registry 查回票据并调用validateTokenForPrincipal校验票据携带的principal属性与当前已解析 Principal 是否一致;③ 校验通过后立即删除该令牌(一次性使用),失败则同样删除并抛出FailedLoginException。
其中 bucket4j 限流开关由 cas.authn.mfa.simple.bucket4j.enabled 控制,对应的 mfaSimpleMultifactorBucketConsumer Bean 在 CasSimpleMultifactorAuthenticationConfiguration.java 中按条件装配(未启用时退化为 BucketConsumer.permitAll)。这从源码层面印证了:Simple MFA 令牌验证具备限流保护 + 主体绑定 + 一次性消费三重安全机制。
相关单元测试可进一步佐证上述行为,例如 CasSimpleMultifactorAuthenticationTicketFactoryTests.java、DefaultCasSimpleMultifactorAuthenticationServiceTests.java 与 RestfulCasSimpleMultifactorAuthenticationServiceTests.java。
六、总结与选型建议
- 默认(CAS 自管)模式适合大多数场景:零外部依赖,令牌经 Ticket Registry 跟踪、受
HardTimeoutExpirationPolicy约束、支持多种 Ticket Registry 持久化,且默认 6 位数字、30 秒存活的参数可直接运行。 - REST(外部托管)模式适合已具备独立令牌服务的企业:CAS 仅充当前端编排,令牌的生成与校验完全交由外部 API,同时保留主体绑定与限流等安全语义。
- 无论哪种模式,都建议:令牌长度保持 ≥ 6 位以避免碰撞;按业务体验适当调大
time-to-kill-in-seconds;对验证入口保持 bucket4j 限流开启,防止暴力枚举。