How to register a custom ProtocolMapper in Keycloak?

Question

I'm struggling with registering a custom ProtocolMapper in Keycloak. I would like to add some data from my database on token request. So i followed the idea given in Keycloak add extra claims from database / external source.

I implemented the ProtocolMapper interface and added the file

META-INF/services/org.keycloak.protocol.ProtocolMapper

containing the reference to my class. So far so good and Keycloak recognizes the new implementation. I'm also able to configure it via the admin console.

To add some data to the token I think I must also add one/some of the interfaces

org.keycloak.protocol.oidc.mappers.UserInfoTokenMapper org.keycloak.protocol.oidc.mappers.OIDCIDTokenMapper org.keycloak.protocol.oidc.mappers.OIDCAccessTokenMapper

and implement the methods according to the interface(s).

The problem now is that as soon as I add the interface I get the following log message:

08:55:07,292 ERROR [org.jboss.msc.service.fail] (MSC service thread 1-6) MSC000001: Failed to start service jboss.deployment.unit."keycloak-spi.jar".POST_MODULE: org.jboss.msc.service.StartException in service jboss.deployment.unit."keycloak-spi.jar".POST_MODULE
: WFLYSRV0153: Failed to process phase POST_MODULE of deployment "keycloak-spi.jar"
        at org.jboss.as.server.deployment.DeploymentUnitPhaseService.start(DeploymentUnitPhaseService.java:172)
        at org.jboss.msc.service.ServiceControllerImpl$StartTask.startService(ServiceControllerImpl.java:2032)
        at org.jboss.msc.service.ServiceControllerImpl$StartTask.run(ServiceControllerImpl.java:1955)
        at java.util.concurrent.ThreadPoolExecutor.runWorker(Unknown Source)
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source)
        at java.lang.Thread.run(Unknown Source)
Caused by: java.lang.NoClassDefFoundError: Failed to link at/lotterien/jam/keycloak/spi/JamAuthorizationInfoProtocolMapper (Module "deployment.keycloak-spi.jar" from Service Module Loader): org/keycloak/protocol/oidc/mappers/UserInfoTokenMapper
        at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
        at sun.reflect.NativeConstructorAccessorImpl.newInstance(Unknown Source)
        at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(Unknown Source)
        at java.lang.reflect.Constructor.newInstance(Unknown Source)
        at org.jboss.modules.ModuleClassLoader.defineClass(ModuleClassLoader.java:446)
        at org.jboss.modules.ModuleClassLoader.loadClassLocal(ModuleClassLoader.java:274)
        at org.jboss.modules.ModuleClassLoader$1.loadClassLocal(ModuleClassLoader.java:77)
        at org.jboss.modules.Module.loadModuleClass(Module.java:713)
        at org.jboss.modules.ModuleClassLoader.findClass(ModuleClassLoader.java:190)
        at org.jboss.modules.ConcurrentClassLoader.performLoadClassUnchecked(ConcurrentClassLoader.java:412)
        at org.jboss.modules.ConcurrentClassLoader.performLoadClass(ConcurrentClassLoader.java:400)
        at org.jboss.modules.ConcurrentClassLoader.loadClass(ConcurrentClassLoader.java:116)
        at java.lang.Class.forName0(Native Method)
        at java.lang.Class.forName(Unknown Source)
        at java.util.ServiceLoader$LazyIterator.nextService(Unknown Source)
        at java.util.ServiceLoader$LazyIterator.next(Unknown Source)
        at java.util.ServiceLoader$1.next(Unknown Source)
        at org.keycloak.provider.DefaultProviderLoader.load(DefaultProviderLoader.java:60)
        at org.keycloak.provider.ProviderManager.load(ProviderManager.java:92)
        at org.keycloak.services.DefaultKeycloakSessionFactory.loadFactories(DefaultKeycloakSessionFactory.java:214)
        at org.keycloak.services.DefaultKeycloakSessionFactory.deploy(DefaultKeycloakSessionFactory.java:115)
        at org.keycloak.provider.ProviderManagerRegistry.deploy(ProviderManagerRegistry.java:42)
        at org.keycloak.subsystem.server.extension.KeycloakProviderDeploymentProcessor.deploy(KeycloakProviderDeploymentProcessor.java:55)
        at org.jboss.as.server.deployment.DeploymentUnitPhaseService.start(DeploymentUnitPhaseService.java:165)
        ... 5 more

Why does Keycloak not find its own interface? Shouldn't it be provided out of the box?

What do I miss to make it work?

---

Edit 1

I got a little bit further. I added a file

META-INF/jboss-deployment-structure.xml

with content

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
    <deployment>
        <dependencies>
            <module name="org.keycloak.keycloak-services"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

and now the exception is gone.

Unfortunately the method transformUserInfoToken() in my class is still not called on token request.

Can anyone put me in the right direction please?

Answer 1

It finally works. Even there are still open questions I could implement the needed functionality.

I had to implement the Interface

org.keycloak.protocol.oidc.mappers.OIDCAccessTokenMapper

(instead of org.keycloak.protocol.oidc.mappers.UserInfoTokenMapper)

Now my transformAccessToken() method is called on every request to URL http://<host>:<port>/auth/realms/testrealm/protocol/openid-connect/token

I think the problem came from my misunderstanding of the terms AccessToken, UserInfo and IDToken. I thought all three are part of the token generated. But it seems the OIDCAccessTokenMapper is the only way to get additional information into the access token.

The remaining open question for me is where the UserInfo and the IDToken would appear. Maybe somebody can give an answer for that.