{"id":21601253,"url":"https://github.com/zloom/keycloak-external-claim-mapper","last_synced_at":"2026-03-02T02:33:53.494Z","repository":{"id":258186416,"uuid":"865501785","full_name":"zloom/keycloak-external-claim-mapper","owner":"zloom","description":"Keycloak extension for fetching remote data to jwt","archived":false,"fork":false,"pushed_at":"2024-10-30T10:35:01.000Z","size":84,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-24T19:08:42.444Z","etag":null,"topics":["jwt","jwt-token","keycloak","user-data","user-profile","user-roles"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zloom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-30T16:26:50.000Z","updated_at":"2024-11-17T20:24:23.000Z","dependencies_parsed_at":"2024-10-17T23:56:32.190Z","dependency_job_id":null,"html_url":"https://github.com/zloom/keycloak-external-claim-mapper","commit_stats":null,"previous_names":["zloom/keycloak-external-claim-mapper"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zloom%2Fkeycloak-external-claim-mapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zloom%2Fkeycloak-external-claim-mapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zloom%2Fkeycloak-external-claim-mapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zloom%2Fkeycloak-external-claim-mapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zloom","download_url":"https://codeload.github.com/zloom/keycloak-external-claim-mapper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235483249,"owners_count":18997400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jwt","jwt-token","keycloak","user-data","user-profile","user-roles"],"created_at":"2024-11-24T19:08:45.237Z","updated_at":"2026-03-02T02:33:53.487Z","avatar_url":"https://github.com/zloom.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![GitHub Release](https://img.shields.io/github/v/release/zloom/keycloak-external-claim-mapper?color=blue)](https://github.com/zloom/keycloak-external-claim-mapper/releases)\n[![GitHub license](https://img.shields.io/badge/License-Apache-blue.svg)](https://github.com/zloom/keycloak-external-claim-mapper/blob/main/LICENSE)\n# Keycloak External Claim Mapper\nImplementation of the keycloak internal SPI protocol-mapper, that allows to fetch remote http json data and include it into user JWT.\n## Limitations\nBuilt and tested with Keycloak 25.0.0, maven 3.6.3, openjdk21, you can build and test with other versions if required.\n## Installation\nTo build Keycloak 25.0.0 image with extension from 0.0.2 release create dockerfile with following content:\n```\nFROM alpine:3.20 as build\n\nARG VERSION=0.0.2\n\nRUN \\\n  wget https://github.com/zloom/keycloak-external-claim-mapper/releases/download/${VERSION}/external.claim.mapper-${VERSION}.tar.gz;\\\n  mkdir -p /providers;\\\n  tar -C /providers -zxvf external.claim.mapper-${VERSION}.tar.gz;\n\nFROM quay.io/keycloak/keycloak:25.0.0 as keycloak\n\nCOPY --from=build /providers /opt/keycloak/providers\n\nENV KEYCLOAK_ADMIN=\"admin\"\nENV KEYCLOAK_ADMIN_PASSWORD=\"admin\"\n```\nBuild and run it with following command:\n```\ndocker build -t keycloak . \u0026\u0026 docker run -p 8080:8080 keycloak start-dev\n```\nLogin 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).\n## Configuration\nThere are 5 fields to configure, except standard protocol mapper provider configuration.\n### Remote url\nThis is remote url to fetch json from, you can optionally use a placeholders to insert keycloak user id, user name and email. \n- 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.\n### Json path\nOptional json path expression to transform your remote endpoint response data.\nGiven that **Token Claim Name** is configured as `user_roles` and remote endpoint response is:\n```\n{\n  \"roles\": {\n    \"values\": [\n      \"role1\",\n      \"role2\",\n      \"role3\"\n    ]\n  }\n}\n```\nIn final jwt it will look as following:\n```\n...\n\"user_roles\": {\n  \"roles\": {\n    \"values\": [\n      \"role1\",\n      \"role2\",\n      \"role3\"\n    ]\n  }\n}\n...\n```\nYou can set **Json path** to `$.roles.values` it will result to:\n```\n...\n\"user_roles\": [\n  \"role1\",\n  \"role2\",\n  \"role3\"\n]\n...\n```\nIt is convenient when you don't have control over remote endpoint response shape, you can test json path expressions with https://jsonpath.com\n### Error propagation\nA 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.\n### User authentication\nWhen 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...\"`\n### Request headers\nSet 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.\n\n## Development\n\nUse **Docker Compose** to build and run changes in a local test environment:\n\n```bash\ndocker compose up\n```\n\nThis launches:\n- A Keycloak server with the module installed\n- A PostgreSQL database for Keycloak\n- A MockServer that serves user roles\n\n**Login to Keycloak:**\n- Username: `admin`\n- Password: `admin`\n- Select the `dev` realm\n\nA test user is preconfigured:\n- Username: `test`\n- Password: `test`\n\nThe custom mapper is loaded into the `account` client.  \nTo change its settings, go to:  \n**Client Scopes → `account-dedicated` → `external_claims`.**\n\n**Generate a token:**\n\n```bash\n./scripts/get_token.sh\n```\n\nThis script generates a JWT token with mocked claims.\nYou can inspect the resulting `access_token` at [jwt.io](https://jwt.io/).\nLocal setup includes the MockServer dashboard at:  \n[http://localhost:8081/mockserver/dashboard](http://localhost:8081/mockserver/dashboard)\n\nYou can check received requests there.\n\n![Dashboard](./images/2025-06-14_13-51.png)\n\n## Contributors\n\n- [Anton Zalialdinov](https://zloom.org)\n- [Brendan Arnold](http://brendan.sdf-eu.org)\n\n## License\nThis project is licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzloom%2Fkeycloak-external-claim-mapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzloom%2Fkeycloak-external-claim-mapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzloom%2Fkeycloak-external-claim-mapper/lists"}