Keycloak自定义事件监听器中keycloak-admin-client找不到问题求助

核心原因 #

Keycloak服务器默认不包含keycloak-admin-client类库，当你给依赖添加<scope>provided</scope>时，Maven不会将该依赖打包到扩展jar中，导致运行时无法找到对应类。

解决方案 #

1. 调整Maven依赖配置 #

移除keycloak-admin-client依赖的<scope>provided</scope>，确保依赖会被编译并纳入打包范围：

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-admin-client</artifactId>
    <version>与你的Keycloak服务器版本完全一致</version>
</dependency>

2. 使用Maven Shade插件构建包含依赖的Fat Jar #

添加maven-shade-plugin到pom.xml的build插件中，将keycloak-admin-client及其传递依赖打包到扩展jar里，同时重定位依赖包避免与Keycloak自带类冲突：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.3.0</version>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                    <configuration>
                        <relocations>
                            <relocation>
                                <pattern>org.keycloak.admin.client</pattern>
                                <shadedPattern>你的自定义扩展包名.shaded.keycloak.admin.client</shadedPattern>
                            </relocation>
                            <!-- 按需添加其他冲突依赖包的重定位，比如resteasy相关类 -->
                        </relocations>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

3. 重新打包并部署 #

运行以下命令构建包含依赖的jar：

mvn clean package

将生成的带-shaded后缀的jar文件（位于target目录下）复制到Keycloak对应目录：

• Quarkus版本Keycloak：${KEYCLOAK_HOME}/providers
• WildFly版本Keycloak：${KEYCLOAK_HOME}/standalone/lib/ext

最后重启Keycloak服务器。

额外注意事项 #

• 版本一致性：keycloak-admin-client的版本必须与Keycloak服务器版本完全匹配，否则会出现兼容性问题。
• 冲突排查：若打包后仍有类冲突，可通过Shade插件的relocation功能重定位更多冲突包路径。

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