javacustomizationkeycloak

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

I've seen those two post that give a solution to this question but they do not provide detailed enough informations about how to do it for non Java developer like me:

Keycloak add extra claims from database / external source

How to register a custom ProtocolMapper in Keycloak?

Here is a recap of their solutions that could help others if filled with more details.

Process expected from 1st link

  1. User logs in
  2. My custom protocol mapper gets called, where I overwrite the transformAccessToken method
  3. Here I log in the client where the protocol mapper is in into keycloak, as a service. Here don't forget to use another client ID instead the one you're building the protocol mapper for, you'll enter an endless recursion otherwise.
  4. I get the access token into the protocol mapper and I call the rest endpoint of my application to grab the extra claims, which is secured.
  5. Get the info returned by the endpoint and add it as extra claims

Steps to achieve it from 2nd link

Implement the ProtocolMapper interface and add the file "META-INF/services/org.keycloak.protocol.ProtocolMapper" containing the reference to the class.

At this point Keycloak recognizes the new implementation. And you should be able to configure it via the admin console.

To add some data to the token add the following interfaces

org.keycloak.protocol.oidc.mappers.OIDCAccessTokenMapper

and implement the methods according to the interface

Then add the file "META-INF/jboss-deployment-structure.xml" with the following 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 after doing all this the custom transformAccessToken() method is called on every request to URL http://:/auth/realms/testrealm/protocol/openid-connect/token

After reading this I have a few questions :

  1. How do you ”Implement the ProtocolMapper”
  2. Where do you add the files mentionned earlier ? ( can't see any META-INF/ directory in my Keycloak installation folder )
  3. How and where do you ”add the following interfaces”
  4. What does the custom transformAccessToken() looks like

Thank you all for your time. Let me know if I miss summarise their answers.

Edit :

I'm starting a bounty with the hope that someone will be able to give me detailled steps on how to add extra claims from database in Keycloak 3.4.3 ( Detailed enough for a non Java dev )

Edit 2 A method descibed here could do the trick but lack details. Keycloak create a custom identity provider mapper

Solution

  • 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