Keycloak 18：阶梯认证场景下如何将LoA的Max Age写入访问令牌？

一、将LoA的Max Age写入访问令牌 #

内置ACR映射器无法直接获取LoA的maxAge参数，你可以通过以下两种方式实现：

1. 使用脚本映射器（Script Mapper） #

Keycloak 18支持通过脚本自定义令牌字段，步骤如下：

• 首先在Keycloak配置文件（standalone.xml或domain.xml）中开启脚本支持，找到<spi name="script">节点，确保配置如下：

<spi name="script">
    <default-provider>javascript</default-provider>
    <providers>
        <provider>javascript</provider>
        <provider>groovy</provider>
    </providers>
</spi>

• 重启Keycloak服务。
• 进入目标客户端的Mappers页面，点击Create，选择类型为Script Mapper。
• 在脚本内容中编写逻辑，提取LoA执行器的maxAge并添加到令牌：

// 获取当前认证会话
var authSession = authenticationSession;
// 获取LoA执行器的配置（执行器ID为"condition-level-of-authentication"）
var loaConfig = authSession.getAuthNote("condition-level-of-authentication");
if (loaConfig) {
    // 解析配置，提取maxAge（需根据你的实际配置格式调整）
    var configObj = JSON.parse(loaConfig);
    var maxAge = configObj.maxAge;
    // 将maxAge写入令牌自定义字段，比如"loa_max_age"
    token.setOtherClaims("loa_max_age", maxAge);
}

• 保存映射器，之后生成的access token就会包含loa_max_age字段。

2. 自定义Java SPI令牌映射器 #

如果脚本方式不符合需求，可以编写自定义SPI映射器：

• 创建Java类实现org.keycloak.protocol.oidc.mappers.OIDCAttributeMapper接口。
• 在transformAccessToken方法中，通过AuthenticationSessionModel获取LoA执行器的配置，提取maxAge并添加到令牌的claims中。
• 打包成JAR，放到Keycloak的providers目录，重启服务后在客户端Mappers中选择自定义映射器。

二、无需修改令牌的第二因素过期判断方案 #

如果不想修改令牌，可以通过以下方式判断：

1. 利用Keycloak Admin API查询会话信息 #

调用Admin API的用户会话接口GET /admin/realms/{realm}/users/{userId}/sessions，返回的会话数据中包含authenticationSessions，其中可以找到LoA认证的时间戳。计算当前时间与该时间戳的差值，判断是否超过maxAge。

注意：此方法需要服务端具备Admin API的访问权限，且需要匹配当前客户端的会话ID来定位对应的认证记录。

2. 存储LoA认证时间到用户会话属性 #

在阶梯式认证的Post Authentication Flow中添加一个Script Execution执行器，编写脚本将当前认证时间写入会话的自定义属性：

var authSession = authenticationSession;
// 记录当前LoA认证的时间戳（毫秒）
authSession.setAuthNote("last_loa_auth_time", new Date().getTime().toString());

之后在需要检查时，通过客户端的Token Introspection API（POST /realms/{realm}/protocol/openid-connect/token/introspect）获取会话的notes字段，提取last_loa_auth_time，计算与当前时间的差值是否超过maxAge。

3. 客户端本地存储（不推荐） #

在用户完成第二因素认证后，前端客户端存储当前时间戳，本地计算是否过期。但这种方式存在安全风险，客户端可以篡改存储的时间，仅适用于低安全要求的场景。

内容的提问来源于stack exchange，提问作者Lovis