Apereo CAS Simple MFA 令牌管理完全指南:内部 Ticket Registry 存储与外部 REST 托管两种模式

原创2026-10-14 21:59:171,377 阅读
文章标签:后端认证鉴权单点登录身份认证

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 的令牌生命周期都围绕统一服务接口展开。以默认模式为例,完整链路如下:

  1. 生成(generate):CasSimpleMultifactorSendTokenAction.doExecuteInternal 调用 multifactorAuthenticationService.generate(principal, service) 创建令牌。若 webflow 上下文中已存在未过期令牌则复用,否则新生成(见 CasSimpleMultifactorSendTokenAction.java);
  2. 派发(communication):依据 CasSimpleMultifactorTokenCommunicationStrategy 决定的策略(SMS / PHONE / EMAIL / NOTIFICATION 四种通道,见 CasSimpleMultifactorTokenCommunicationStrategy.java),通过 CommunicationsManager 将验证码发给用户;
  3. 存储(store):任一派发通道成功后,调用 store(token) 将票据写入 Ticket Registry(默认实现为新增或更新票据),并把存储后的票据 ID 记录到 flow credential 的 ticketId 字段(trackStoredToken),以便无状态注册表场景下正确比对;
  4. 验证(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 限流开启,防止暴力枚举。
登录后查看全文
cas