如何配置自定义Keycloak令牌映射器支持向声明中写入多值属性

问题原因 #

OIDCAttributeMapperHelper.mapClaim传入列表仅第一个元素生效，是因为该方法默认以单值模式处理入参，未开启多值配置时会自动截断集合，仅取首个元素写入令牌声明。

解决方案 #

• 方案1：直接操作Token声明写入（最简便）
  跳过Helper类直接向令牌的自定义声明中写入完整列表，示例代码：

// 从映射配置中获取你预设的自定义声明名
String customClaimName = mappingModel.getConfig().get(OIDCAttributeMapperHelper.TOKEN_CLAIM_NAME);
// 直接写入完整列表
token.getOtherClaims().put(customClaimName, myList);

• 方案2：开启映射器多值配置后使用Helper
  在你的自定义映射器的配置定义环节，新增多值属性配置：

// 自定义映射器初始化配置时添加该项
Map<String, String> config = new HashMap<>();
config.put(OIDCAttributeMapperHelper.TOKEN_CLAIM_NAME, "你的自定义声明名");
// 开启多值支持
config.put(OIDCAttributeMapperHelper.MULTIVALUED, "true");
// 其余配置项省略...

配置完成后再调用原有方法即可写入完整列表：

List<MyObject> myList = ...
OIDCAttributeMapperHelper.mapClaim(token, mappingModel, myList);

注意事项 #

• 如果MyObject为自定义实体类，Keycloak会直接将其序列化为JSON结构存入声明，如有不需要序列化的字段请添加transient修饰，或提前转换为Map<String, Object>结构再写入。
• 写入列表后请验证JWT解析结果，确保列表结构符合下游业务的解析规则。

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