Apereo CAS 配置解析:cas.ticket.tst 如何控制 TST 瞬态会话票据的过期策略
Apereo CAS 配置解析:cas.ticket.tst 如何控制 TST 瞬态会话票据的过期策略
Apereo CAS 的 TST(Transient Session Ticket,瞬态会话票据)是一种以票据注册表(Ticket Registry)为底层存储、用于跟踪与某次会话绑定的短期活动的票据机制。本文围绕 cas.ticket.tst 配置项展开,结合仓库源码剖析其两个核心参数(使用次数、存活时长)如何被解析、组装成过期策略,并在票据工厂中生效,帮助你既能正确配置 TST 生命周期,也能理解其在集群会话跟踪中的底层实现。
一、什么是 Transient Session Ticket(TST)
TST 过期策略决定的是 CAS 能够跟踪与某个会话绑定的特定活动的持续时长(即原文档给出的定义)。
从源码的类注释可以看到 TST 的设计意图(见 TransientSessionTicket.java):
- 把票据注册表当作分布式会话存储:TST 允许 CAS 将票据注册表用作"分布式会话存储",来存放短生命周期的、非特定类型的对象。其目标是封装那些原本由应用容器 session(如 HTTP Session)跟踪的对象,从而让集群环境下需要"会话感知"的操作摆脱对单机 session 的依赖;
- 存入的值必须可序列化:放入 TST 的对象/值要求可序列化(
Serializable),与票据属性本身的序列化要求一致,具体取决于底层票据注册表的设计; - 典型场景:类注释指出,当 CAS 作为另一个身份提供者的代理(proxy)时——例如委派认证流程中需要跨集群保存当前应用会话/请求的结果并在之后回忆起来——瞬态票据的典型用武之地就出现了;
- 票据前缀固定为
TST(接口常量PREFIX = "TST"),该机制自 CAS 5.3.0 起引入。
其默认实现 TransientSessionTicketImpl.java 的注释进一步说明:TST 在委派认证请求到达、需要移交给某个身份提供者时签发,"代表 CAS 服务器在那一刻的状态",并携带一个 Service 引用与属性 Map。
从源码结构看,TST 在仓库中被大量 webflow action 复用,例如账户注册的 SubmitAccountRegistrationAction.java、Duo 认证流程的 DuoSecurityUniversalPromptPrepareLoginAction,以及 OAuth/OIDC 的 nonce 校验等模块,均为"跨请求保存中间状态"的典型用例。
二、配置项:cas.ticket.tst 全解析
原文档主体引用的是 cas.ticket.tst 前缀下的配置目录(properties catalog)。这些配置项由 TransientSessionTicketProperties.java 定义,并通过 TicketProperties.java 中名为 tst 的嵌套字段挂载到 cas.ticket 之下;整个配置树的前缀由 CasConfigurationProperties.java 中的 @ConfigurationProperties(prefix = "cas") 确定。
| 配置项(kebab-case) | 默认值 | 含义 |
|---|---|---|
cas.ticket.tst.number-of-uses |
1 |
控制票据在 CAS 服务器内部可被使用的次数(源码注释:"Controls number of times a ticket can be used within CAS server")。使用次数达到该值后票据即视为过期 |
cas.ticket.tst.time-to-kill-in-seconds |
PT5M(5 分钟) |
票据签发后经过多久失效。字段虽以 "in-seconds" 命名,但实际接受 ISO-8601 时长字符串(带 @DurationCapable 注解),如 PT5M、PT30S、PT1H,加载时统一换算为秒 |
一个可直接复制的 YAML 配置示例(基于 TransientSessionTicketExpirationPolicyBuilderTests.java 中使用的测试属性):
cas:
ticket:
tst:
# 票据最多允许被使用的次数;达到该次数后票据过期
number-of-uses: 2
# 存活时间(ISO-8601 时长),此处为 5 秒
time-to-kill-in-seconds: 5
两点需要注意的取值约束:
- 两个参数最终都会传入过期策略构造器,而 MultiTimeUseOrTimeoutExpirationPolicy.java 的构造器中有断言
numberOfUses > 0与timeToKillInSeconds > 0,因此两者都必须大于 0,配置为 0 或负数会导致运行期异常; time-to-kill-in-seconds支持纯数字秒值,也支持PT...形式的 ISO-8601 时长,默认值PT5M即 5 分钟。
三、过期策略的构建链:从配置到 Policy 对象
3.1 策略构建器
配置到过期策略的转换发生在 TransientSessionTicketExpirationPolicyBuilder.java:
public ExpirationPolicy toTransientSessionTicketExpirationPolicy() {
val tst = casProperties.getTicket().getTst();
val timeToKillInSeconds = Beans.newDuration(tst.getTimeToKillInSeconds()).toSeconds();
return new MultiTimeUseOrTimeoutExpirationPolicy.TransientSessionTicketExpirationPolicy(
tst.getNumberOfUses(), timeToKillInSeconds);
}
即:读取 cas.ticket.tst 两个字段,用 Beans.newDuration(...) 把 ISO-8601 时长解析成秒,再构造 MultiTimeUseOrTimeoutExpirationPolicy.TransientSessionTicketExpirationPolicy(该策略类的 @since 为 6.1.0)。构建器 Bean 由 CasCoreTicketsConfiguration.java 注册进 Spring 容器。
3.2 判定逻辑:次数 或 超时,任一命中即过期
TransientSessionTicketExpirationPolicy 继承自 MultiTimeUseOrTimeoutExpirationPolicy.java,其 isExpired 判定逻辑为:
- 使用次数判定:
ticketState.getCountOfUses() >= numberOfUses时返回过期(源码注释:"Ticket usage count is greater than or equal to"); - 超时判定:
当前时间 > 创建时间 + timeToKillInSeconds时返回过期; - 票据状态为
null时直接视为过期。
也就是说,TST 的生命周期由"次数上限"与"超时上限"双重约束,先到者为准。
3.3 工厂签发与按票据覆盖策略
Ticket 工厂 签发流程:用 HostNameBasedUniqueTicketIdGenerator 生成带 TST 前缀的唯一票据 ID,再调用 TransientSessionTicketFactory.buildExpirationPolicy(...) 获取策略,最终构造 TransientSessionTicketImpl。值得注意的是 TransientSessionTicketFactory.java 中的静态方法:
static ExpirationPolicy buildExpirationPolicy(final ExpirationPolicyBuilder expirationPolicyBuilder,
final Map<String, Serializable> properties) {
var expirationPolicy = expirationPolicyBuilder.buildTicketExpirationPolicy();
if (properties.containsKey(ExpirationPolicy.class.getName())) {
expirationPolicy = (ExpirationPolicy) properties.remove(ExpirationPolicy.class.getName());
}
return expirationPolicy;
}
这意味着:调用方可以在创建 TST 时通过属性 Map 显式传入一个自定义 ExpirationPolicy 来覆盖全局的 cas.ticket.tst 配置,全局配置只作为缺省策略。此外工厂还会在 service 不为空时把租户 ID 写入票据(ticket.setTenantId(service.getTenant())),用于多租户场景。
四、测试用例验证:次数用尽即过期
仓库中的单元测试 TransientSessionTicketExpirationPolicyBuilderTests.java 以 cas.ticket.tst.number-of-uses=2、cas.ticket.tst.time-to-kill-in-seconds=5 启动 Spring 上下文,并断言了完整的过期行为:
val ticket = new DefaultTransientSessionTicketFactory(builder).create(RegisteredServiceTestUtils.getService());
assertFalse(ticket.isExpired()); // 新建后未过期
ticket.update();
assertFalse(ticket.isExpired()); // 第 1 次使用后仍未过期(上限为 2)
ticket.update();
assertTrue(ticket.isExpired()); // 第 2 次使用达到上限,判定过期
该测试直接印证了第二节表格中 number-of-uses 的语义:使用次数达到配置值时票据立即失效,无需等待超时。
五、与其他票据过期策略的关系
TST 策略文档位于 ticketing 文档目录 docs/cas-server-documentation/ticketing 下,与其余票据类型策略文档并列,可作为整套 CAS 票据生命周期配置的索引:
- Configuring-Ticket-Expiration-Policy.md:票据过期策略总览;
- Configuring-Ticket-Expiration-Policy-TGT.md:TGT(SSO 会话票据)过期策略;
- Configuring-Ticket-Expiration-Policy-ST.md:ST 过期策略;
- Configuring-Ticket-Expiration-Policy-PT.md 与 Configuring-Ticket-Expiration-Policy-PGT.md:代理票据(PT)与 PGT 策略。
可以看到,PT/ST 与 TST 共享同一套 MultiTimeUseOrTimeoutExpirationPolicy 家族(其内部静态类分别对应 Proxy/Service/TransientSession 三种票据),配置风格一致(number-of-uses + time-to-kill-in-seconds),区别主要在于各自的前缀与作用对象:TGT 管理的是 SSO 会话级生命周期,而 TST 管理的是与单次会话活动绑定的、更短命的瞬态状态。因此在调优时,TST 参数通常应显著小于 TGT 的会话时长——例如默认 5 分钟的 PT5M 就明显短于典型 SSO 会话——以便跨请求的中间状态在流程结束后被及时回收,避免票据注册表中滞留无用的瞬态数据。
六、小结
cas.ticket.tst.number-of-uses(默认 1)与cas.ticket.tst.time-to-kill-in-seconds(默认PT5M,支持 ISO-8601 时长)共同决定 TST 的有效期,二者都必须大于 0;- 过期判定为"次数用尽或超时"的或逻辑,由
MultiTimeUseOrTimeoutExpirationPolicy.TransientSessionTicketExpirationPolicy实现; - 策略由
TransientSessionTicketExpirationPolicyBuilder从全局配置构建,但创建票据时可通过属性 Map 传入自定义策略进行覆盖; - TST 本质是"以票据注册表为底座的分布式临时会话存储",值必须可序列化,广泛服务于账户注册、OAuth/OIDC nonce、多因素认证 webflow 等跨请求状态跟踪场景。