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

I am using a Custom Protocol Mapper¹ to send an authenticated² GraphQL query³ to an external system and put the JSON response data into the user's access token (JWT). It currently runs with Keycloak 10.

==> You can find the full code in this repository.

(1) Custom Protocol Mapper

As others have noted, your project needs at least 3 files.

1. A Java class that implements AbstractOIDCProtocolMapper & its method setClaim (among others).
2. A jboss-deployment-structure.xml file that contains the dependencies for deployment.
3. An org.keycloak.protocol.ProtocolMapper file that contains the full name of the custom protocol mapper.

Here is the folder structure:

$ tree src/ -A
src/
└── main
    ├── java
    │   └── com
    │       └── thohol
    │           └── keycloak
    │               └── JsonGraphQlRemoteClaim.java
    └── resources
        └── META-INF
            ├── jboss-deployment-structure.xml
            └── services
                └── org.keycloak.protocol.ProtocolMapper

(2) Authenticated Remote Requests

If the remote endpoint requires authentication, we can obtain an Access Token from Keycloak. The complete flow would look as follows (especially steps 3-6):

1. A user sends an authentication request (i.e., "logs in") to Keycloak. The request is made against a specific Keycloak client, e.g., login-client.
2. Because the login-client is configured to use the Custom Protocol Mapper, its code gets executed while the user's authentication request is being processed.
3. The Custom Protocol Mapper sends a second authentication request to Keycloak. The request is made against a second Keycloak client (e.g., remote-claims-client) using client_credentials (Client ID + Secret).
4. The Custom Protocol Mapper receives an access token for client remote-claims-client.
5. The Custom Protocol Mapper sends a request to the remote endpoint. An Authorization: Bearer <access token> header is added to the request headers.
6. The remote endpoint receives the request and validates the JWT token. In many cases, access should be restricted further. For example, to only allow tokens minted ("written") for the corresponding remote-claims-client.
7. The remote endpoint returns the custom remote claims data.
8. The Custom Protocol Mapper receives the custom remote claims data and puts it into the user's access token.
9. Keycloak returns an access token with custom claims to the user.

Steps 3/4 can be implemented as a simple HTTP POST request in Java (error handling omitted!):

// Call remote service
HttpClient httpClient = HttpClient.newHttpClient();
URIBuilder uriBuilder = new URIBuilder(keycloakAuthUrl);
URI uri = uriBuilder.build();

HttpRequest.Builder builder = HttpRequest.newBuilder().uri(uri);
String queryBody = "grant_type=client_credentials&client_id=remote-claims-client&client_secret=dfebc62a-e8d7-4ab3-9196-258ddb5684ab";
builder.POST(HttpRequest.BodyPublishers.ofString(queryBody));

// Build headers
builder.header(HttpHeaders.CONTENT_TYPE , MediaType.APPLICATION_FORM_URLENCODED);

// Call
HttpResponse<String> response = httpClient.send(builder.build(), HttpResponse.BodyHandlers.ofString());

// Process Response
JsonNode json = return new ObjectMapper().readTree(response.body());
String accessToken = json.findValue("access_token").asText();

(3) Using GraphQL Queries for external requests

A GraphQL query is essentially an HTTP POST request, with a body like

{
    "query": "query HeroName($episode: Episode) {
        hero(episode: $episode) {
            name
        }
    }",
    "variables": {
        "episode" : "JEDI"
    }
}

This can be sent from Java like (error handling omitted!):

HttpClient httpClient = HttpClient.newHttpClient();
URIBuilder uriBuilder = new URIBuilder(remoteUrl);
URI uri = uriBuilder.build();

HttpRequest.Builder builder = HttpRequest.newBuilder().uri(uri);
String queryBody = "{
    \"query\": \"query HeroName($episode: Episode) {
        hero(episode: $episode) {
            name
        }
    }\",
    \"variables\": {
        \"episode\" : \"JEDI\"
    }
}";
builder.POST(HttpRequest.BodyPublishers.ofString(queryBody));

// Build headers
builder.header(HttpHeaders.CONTENT_TYPE , MediaType.APPLICATION_JSON);
builder.header(HttpHeaders.AUTHORIZATION, "Bearer " + accessToken);

// Call
HttpResponse<String> response = httpClient.send(builder.build(), HttpResponse.BodyHandlers.ofString());

// Process Response and add to token
JsonNode json = return new ObjectMapper().readTree(response.body());
clientSessionCtx.setAttribute("custom_claims", json);

Disclaimer

I am the owner/author of the linked repository. However, I did not start from scratch but used multiple other repositories as basis/inspiration. See the repo's README.