Apereo CAS 配置解析:cas.ticket.tst 如何控制 TST 瞬态会话票据的过期策略

原创2026-10-15 16:44:331,419 阅读
文章标签:后端认证鉴权单点登录身份认证

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 判定逻辑为:

  1. 使用次数判定:ticketState.getCountOfUses() >= numberOfUses 时返回过期(源码注释:"Ticket usage count is greater than or equal to");
  2. 超时判定:当前时间 > 创建时间 + timeToKillInSeconds 时返回过期;
  3. 票据状态为 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 票据生命周期配置的索引:

可以看到,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 等跨请求状态跟踪场景。
登录后查看全文
cas