自定义OIDC身份提供商映射器部署求助：组角色映射至访问令牌

嘿，我看你在自定义Keycloak的OIDC令牌映射器时碰到了部署问题——把用户所属组的角色以组名-角色列表的格式塞进单个声明里这个需求挺实用的，咱们一步步来排查解决：

1. 先盯紧编译打包的基础环节 #

• 依赖匹配是关键：你继承了AbstractOIDCProtocolMapper并实现了OIDCAccessTokenMapper等接口，必须确保项目引入的Keycloak核心依赖（比如keycloak-core、keycloak-server-spi、keycloak-server-spi-private）版本和你部署的Keycloak完全一致，版本不匹配是部署失败的重灾区。
• 打包方式别踩坑：Keycloak扩展需要打成标准JAR包，用Maven的话，确保<packaging>jar</packaging>配置正确；如果你的映射器依赖了第三方库，用maven-shade-plugin打包时要排除Keycloak自带的核心类，避免类冲突。

2. 验证扩展识别配置文件 #

你提到在编译目录顶层加了文件，这里必须注意Keycloak的扩展识别规则：

• 一定要在META-INF/services目录下创建org.keycloak.protocol.ProtocolMapper文件，文件内容就是你的映射器类的全限定名（比如com.yourteam.HierarchicalAttributesMapper）。路径错了、类名写错了，Keycloak根本找不到你的扩展，自然部署失败。
• 如果在Keycloak控制台添加映射器时看不到你的自定义选项，90%是这个配置文件的问题。

3. 检查映射器类的核心实现细节 #

既然你是基于GroupMembershipMapper扩展，这些细节要注意：

• 必须重写init、transformAccessToken、transformIDToken、transformUserInfoToken这些核心方法，尤其是在令牌转换方法里，要正确遍历用户的组和对应角色，构建组名-角色列表的映射对象，再把它添加到令牌声明中。
• 别忘了在getDisplayCategory、getDisplayType、getHelpText这些方法里返回清晰的标识，这样在Keycloak控制台才能正确显示你的映射器选项，方便配置使用。

4. 扒Keycloak日志找具体错误 #

部署失败最直接的排查方式是看日志：

• 启动Keycloak时加上--log-level=DEBUG参数，或者去服务器日志目录（比如standalone/log/server.log）找详细错误信息，比如类找不到、依赖缺失、初始化时的空指针异常等，日志会精准告诉你哪里出问题。
• 如果是本地部署，把JAR放到standalone/deployments目录后，要是部署失败，会生成.failed后缀的文件，里面也有错误提示。

5. 确认部署路径的正确性 #

• 本地开发环境：把打包好的JAR放到Keycloak的standalone/deployments目录，Keycloak会自动热部署；
• 容器化部署：要确保JAR被正确挂载到容器内的/opt/keycloak/providers目录，然后重启容器生效。

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