Keycloak Custom SPI Deployment with external Jar

I have a SPI implementation which is:

  • Custom SPI, directly implemented via SPI interface
  • has an external jar which does not exist in JBoss base
  1. EAR deployment: I tried EAR deployment and deploy my .ear to /standalone/deployments. This solves the external jar problem which is bundled within EAR’s lib folder. But now SPI is not initializing (which I saw when I debug) and also I get an exception when I trigger the SPI:
11:34:02,185 INFO  [] (Controller Boot Thread) WFLYSRV0025: Keycloak 9.0.2 (WildFly Core 10.0.3.Final) started in 12070ms - Started 732 of 1031 services (613 services are lazy, passive or on-demand)
    11:34:18,209 ERROR [] (default task-1) Uncaught server error: java.lang.NullPointerException
            at org.keycloak.keycloak-services@9.0.2//

Then I thought maybe keycloak is not able to import extended SPI via standalone/deployment deployment, which is also mentioned here if you develop custom SPI keycloak suggests (or requires?) module deployment.

  1. Then I tried module deployment; now I can see that my custom SPI is initializing, but now keycloak can not find my external JAR.
    13:17:05,682 FATAL [] (ServerService Thread Pool -- 65) java.lang.RuntimeException: org.jboss.modules.ModuleNotFoundException: com.orbitz.consul

As a solution, I found somewhere that I can put my dependent jar and all its dependent jar’s to ${KEYCLOAK_HOME}\modules\system\layers\keycloak but I don’t want to install my external JAR and its all dependencies manually to keycloak’s base (maybe automatically somehow?). Any solution?

Script to deploy as a module:

./jboss-cli.bat --command="module add --resources=target/registry-spi-1.0.1-SNAPSHOT.jar --dependencies=org.keycloak.keycloak-core,org.keycloak.keycloak-services,org.keycloak.keycloak-server-spi,org.keycloak.keycloak-server-spi-private,javax.api,,com.fasterxml.jackson.core.jackson-core,com.fasterxml.jackson.core.jackson-databind,com.fasterxml.jackson.core.jackson-annotations,org.jboss.logging,com.orbitz.consul"

And added it to standalone.xml as follows:



file name --> file content

org.keycloak.provider.Spi --> -->

my pom.xml





        <!-- this is not provided and I want to use as external jar -->

Keycloak automatically deploys jars (given they have valid META-INF) as the “correct type” of module:

  • for a user federation SPI , the META-INF/services must contain a file named
  • this file must contain a line with the fully qualified class name to the UserStorageProviderFactory implementation, e.g. com.mycompany.keycloak.custom.spi.MyCompanyUserStorageProviderFactory

If that is true (in that mentioned “external jar”), then you can deploy it by copying to to path-to-keycloak/standalone/deployments

Thank you for your reply, @bitrecycling

I am able to deploy my custom authenticator and it worked fine until I had to use a third party library which is not provided (e.g. keycloak-service)

How should the third party library be deployed?
How is the correct way to reference the library from my code/jar?

Hi @cmlonder,

as far as I see it, you have three possibilities:

  1. Install the external JAR as a module. Deploy your extension either as a module or as a JAR and let it reference that module as well as the Kecloak modules as described in
  2. Package your extension as an EAR or WAR. Add the consul-client dependency to the EAR/WAR and add add module dependencies to the other Keycloak modules (via jboss-deployment-structure.xml or manifest).
  3. Add the classes from the consul-client dependency to your JAR (e.g. using the maven-shade-plugin/). Use the same module reference as in 1, except for the consul-client.

Personally, I would go for the second, but all three should work.