https://github.com/zloom/keycloak-external-claim-mapper
Keycloak extension for fetching remote data to jwt
https://github.com/zloom/keycloak-external-claim-mapper
jwt jwt-token keycloak user-data user-profile user-roles
Last synced: 3 months ago
JSON representation
Keycloak extension for fetching remote data to jwt
- Host: GitHub
- URL: https://github.com/zloom/keycloak-external-claim-mapper
- Owner: zloom
- License: apache-2.0
- Created: 2024-09-30T16:26:50.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-30T10:35:01.000Z (over 1 year ago)
- Last Synced: 2024-11-24T19:08:42.444Z (over 1 year ago)
- Topics: jwt, jwt-token, keycloak, user-data, user-profile, user-roles
- Language: Java
- Homepage:
- Size: 82 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/zloom/keycloak-external-claim-mapper/releases)
[](https://github.com/zloom/keycloak-external-claim-mapper/blob/main/LICENSE)
# Keycloak External Claim Mapper
Implementation of the keycloak internal SPI protocol-mapper, that allows to fetch remote http json data and include it into user JWT.
## Limitations
Built and tested with Keycloak 25.0.0, maven 3.6.3, openjdk21, you can build and test with other versions if required.
## Installation
To build Keycloak 25.0.0 image with extension from 0.0.2 release create dockerfile with following content:
```
FROM alpine:3.20 as build
ARG VERSION=0.0.2
RUN \
wget https://github.com/zloom/keycloak-external-claim-mapper/releases/download/${VERSION}/external.claim.mapper-${VERSION}.tar.gz;\
mkdir -p /providers;\
tar -C /providers -zxvf external.claim.mapper-${VERSION}.tar.gz;
FROM quay.io/keycloak/keycloak:25.0.0 as keycloak
COPY --from=build /providers /opt/keycloak/providers
ENV KEYCLOAK_ADMIN="admin"
ENV KEYCLOAK_ADMIN_PASSWORD="admin"
```
Build and run it with following command:
```
docker build -t keycloak . && docker run -p 8080:8080 keycloak start-dev
```
Login and password are `admin`. Check `http://localhost:8080/admin/master/console/#/master/providers` and find `external-claim-mapper` if extension is picked up by Keycloak, it should be there. Check detailed development setup guide [here](https://zloom.org/blogs/debugging-keycloak-extension?utm_source=keycloak-external-claim-mapper).
## Configuration
There are 5 fields to configure, except standard protocol mapper provider configuration.
### Remote url
This is remote url to fetch json from, you can optionally use a placeholders to insert keycloak user id, user name and email.
- Placeholders will work as following: assume your remote urls is `http://localhost/user` so that `http://localhost/user/**uid**/**uname**/**email**` will be transformed to `http://localhost/user/063943d2-d7ed-4bca-812b-506518c38228/test/test%40example.com` given that `063943d2-d7ed-4bca-812b-506518c38228` is keycloak user id, `test` is user name and `test@example.com` is the email.
### Json path
Optional json path expression to transform your remote endpoint response data.
Given that **Token Claim Name** is configured as `user_roles` and remote endpoint response is:
```
{
"roles": {
"values": [
"role1",
"role2",
"role3"
]
}
}
```
In final jwt it will look as following:
```
...
"user_roles": {
"roles": {
"values": [
"role1",
"role2",
"role3"
]
}
}
...
```
You can set **Json path** to `$.roles.values` it will result to:
```
...
"user_roles": [
"role1",
"role2",
"role3"
]
...
```
It is convenient when you don't have control over remote endpoint response shape, you can test json path expressions with https://jsonpath.com
### Error propagation
A switch to propagate errors that may occurs during data fetch and transformation. Mapper will fail for result code not from 2XX or 3XX codes. This flag also will propagate error on jsonpath transformation. Error will be propagated to keycloak token endpoint that will cause 500 error on auth. Exact error should be visible in keycloak logs.
### User authentication
When this options is enabled, extension will add user session JWT token, of course this token will not contain remote claims yet. Token will be added with following header `"Authorization" : "Bearer eyJ..."`
### Request headers
Set of key value pairs which you can use to configure custom request headers, when multiple values provided with same key header value will be joined with comma as following `"X-key": "value1, value2"`. You can use `**uid**` and `**uname**` placeholders same like in remote url.
## Development
Use **Docker Compose** to build and run changes in a local test environment:
```bash
docker compose up
```
This launches:
- A Keycloak server with the module installed
- A PostgreSQL database for Keycloak
- A MockServer that serves user roles
**Login to Keycloak:**
- Username: `admin`
- Password: `admin`
- Select the `dev` realm
A test user is preconfigured:
- Username: `test`
- Password: `test`
The custom mapper is loaded into the `account` client.
To change its settings, go to:
**Client Scopes → `account-dedicated` → `external_claims`.**
**Generate a token:**
```bash
./scripts/get_token.sh
```
This script generates a JWT token with mocked claims.
You can inspect the resulting `access_token` at [jwt.io](https://jwt.io/).
Local setup includes the MockServer dashboard at:
[http://localhost:8081/mockserver/dashboard](http://localhost:8081/mockserver/dashboard)
You can check received requests there.
## Contributors
- [Anton Zalialdinov](https://zloom.org)
- [Brendan Arnold](http://brendan.sdf-eu.org)
## License
This project is licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)