Keycloak add extra claims from database / external source with custom protocol mapper

I hope this step by step guide helps you

I'm using Keycloak 4.5.0 - because I have this newer version installed - but I should not make a big difference. And I implemented a OIDCProtocolMapper in the example.

Just to summarize it - for the quick overview for others - each step is described more detailed later

1. You implement a CustomProtocolMapper class based on AbstractOIDCProtocolMapper

2. META-INF/services File with the name org.keycloak.protocol.ProtocolMapper must be available and contains the name of your mapper

3. jboss-deployment-structure.xml need to be available to use keycloak built in classes

4. Jar File is deployed in /opt/jboss/keycloak/standalone/deployments/

Okay now more details :-)

Create your custom Mapper

I uploaded you my maven pom.xml (pom) - just import it into your IDE and all the dependencies should be loaded automatically. The dependencies are just provided and will be later used from keycloak directly at runtime

Relevant is the keycloak.version property - all keycloak dependencies are currently loaded in version 4.5.0.Final

Now i created a custom Protocol Mapper Class called CustomOIDCProtocolMapper. Find "full" code here

It should extend AbstractOIDCProtocolMapper and need to implement all abstract methods. Maybe you want to have a SAML Protocol Mapper then it's another base class (AbstractSAMLProtocolMapper)

one relevant method is transformAccessToken - here I set a additional Claim to the AccessToken. You need your logic here but yeah - depends on your database, etc. ;-)

Services File

The services File is important for keycloak to find your custom-Implementation

Place a file with the fileName org.keycloak.protocol.ProtocolMapper inside \src\main\resources\META-INF\services\

Inside this file you write to Name of your custom Provider - so keycloak knows that this class is available as Protocol Mapper
In my example the file content is just one line

com.stackoverflow.keycloak.custom.CustomOIDCProtocolMapper

Deployment Structure XML

In your custom mapper you use files from keycloak. In order to use them we need to inform jboss about this dependency. Therefore create a file jboss-deployment-structure.xml inside \src\main\resources\META-INF\ Content:

<jboss-deployment-structure>
    <deployment>
        <dependencies>
            <module name="org.keycloak.keycloak-services" />
        </dependencies>
    </deployment>
</jboss-deployment-structure>

Build and deploy your Extension

Build a jar File of your Extension (mvn clean package) - and place the jar in /opt/jboss/keycloak/standalone/deployments/ and restart keycloak

In the logfile you should see when it's deployed and (hopefully no) error messages

Now you can use your mapper - In my example I can create a Mapper in keycloak admin ui and select Stackoverflow Custom Protocol Mapper from dropdown

Just as info - this is not fully official supported by keycloak - so interfaces could possible change in later versions

I hope it's understandable and you will be able to succesfully implement your own mapper

EDIT: Exported eclipse file structure zip