如何判断Keycloak用户是否已启用TOTP并将状态映射到令牌或userinfo端点

以下3种方案按实现优先级从高到低排序：

方案1：使用OIDC脚本映射器（最便捷） #

这是最适合普通场景的实现方式，无需额外开发插件，只需在Keycloak管理后台配置即可：

1. 开启Keycloak脚本功能（默认关闭）：启动Keycloak时追加启动参数 -Dkeycloak.profile.feature.scripts=enabled，重启服务生效
2. 进入对应Realm的客户端配置页，切换到「映射器（Mappers）」标签，点击「创建」
3. 映射器类型选择「脚本映射器（Script Mapper）」，填写基础配置：
   • 名称：自定义即可，例如totp_enabled_mapper
   • 声明名称：你希望在令牌/用户信息中返回的字段名，例如totp_enabled
   • 声明类型：选择Boolean
   • 勾选要注入的位置：ID令牌、访问令牌、UserInfo端点按需勾选
4. 在脚本输入框中填入以下代码：

user.isTotpEnabled()

5. 保存配置后重新登录用户，即可在对应位置拿到TOTP启用状态的布尔值。

方案2：自定义事件监听器同步用户属性（性能最优） #

如果不希望开启全局脚本功能，可通过插件实现状态预存，后续直接用内置映射器调用：

1. 开发Keycloak事件监听插件：实现EventListenerProvider接口，监听UPDATE_TOTP类型的用户事件，事件触发时调用user.isTotpEnabled()拿到当前状态，写入用户的自定义属性（例如字段名totp_status）
2. 将插件打包为jar包放入Keycloak的providers目录，重启服务后在Realm的事件设置中启用该监听器
3. 进入客户端映射器配置，新建「用户属性（User Attribute）」类型的映射器，选择上述自定义的totp_status属性，按需求配置注入到令牌或UserInfo端点即可。
   该方案无需每次生成令牌时执行脚本，性能开销更低，适合大流量生产环境。

方案3：后端代理Admin接口（无服务端修改权限时可用） #

如果你没有权限修改Keycloak服务端的配置或插件，可通过自有后端做一层权限代理：

1. 在Keycloak中新建一个服务账号，仅为其分配view-users的最小 Realm 管理权限
2. 你自己的后端新增一个接口，接收当前登录用户的UUID，用上述服务账号的凭据调用Keycloak Admin的/auth/admin/realms/{realm}/users/{uuid}接口，提取totp字段返回给前端
3. 前端登录后调用你自己的这个后端接口拿到TOTP状态即可。
   该方案无需修改Keycloak原有配置，但会额外增加一次接口请求开销。

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