keycloak-rest-claim-mapper

A Keycloak 26.x custom OIDC and SAML Protocol Mapper that enriches federated users with attributes fetched from one or more external REST APIs at token issuance time.

Features

🔌 Works with any existing federation (LDAP, AD, or any User Storage SPI)
🔄 Persistent users (imported): attributes are cached in UserModel with a configurable TTL; re-fetched automatically when stale
⚡ Transient users (non-imported): attributes fetched live at every token issuance
🌐 Up to 3 configurable REST API endpoints executed in parallel (significantly faster than configuring multiple separate Keycloak mappers)
🔐 Supports API key, Basic Auth, and OAuth2 client credentials authentication
📜 GraalVM Polyglot JS for dynamic query string construction (query.script)
🗂️ JSONPath (Jayway) and plain field mapping to OIDC claims and SAML attributes
🧩 Structured JSON claims — map entire arrays of objects into a single claim with the json: prefix (ideal for GraphQL responses)
🧪 Test Query panel — live REST endpoint testing via Admin API without a real user login
📦 Deployed as a single fat JAR in /opt/keycloak/providers/

Quick Start

1. Build

mvn clean package

This produces target/keycloak-rest-claim-mapper-1.1.0.jar (a shaded fat JAR with all dependencies).

2. Deploy

cp target/keycloak-rest-claim-mapper-1.1.0.jar /opt/keycloak/providers/
/opt/keycloak/bin/kc.sh build
/opt/keycloak/bin/kc.sh start

3. Configure

In the Keycloak Admin Console:

OIDC Per client: Clients → <client> → Client Scopes → <client>-dedicated → Add Mapper → By Configuration → REST Attribute Enrichment
OIDC Shared: Client Scopes → Create scope → Mappers → Add Mapper → By Configuration → REST Attribute Enrichment
SAML Per client: Clients → <client> → Client Scopes → <client>-dedicated → Add Mapper → By Configuration → SAML REST Attribute Enrichment

See docs/ADMIN_GUIDE.md for the full configuration reference.

Documentation

Document	Description
ADMIN_GUIDE.md	Mapper configuration, Client Scope setup, Test Query panel
DEPLOYMENT.md	Build, deploy, and verify on Keycloak 26.x
CACHING.md	TTL caching strategy for persistent users
ERROR_HANDLING.md	Logging strategy and graceful degradation

Configuration Reference (Quick)

Key	Description
`endpoint.count`	Number of active endpoints (1–3)
`cache.ttl.seconds`	Cache TTL for persistent users (default: 300)
`endpoint.N.url`	REST API base URL
`endpoint.N.auth.type`	`apikey`, `basic`, or `oauth2`
`endpoint.N.auth.value`	API key, base64 encoded `username:password`, or `clientId:clientSecret:tokenUrl`
`endpoint.N.query.param.K`	User context field name (e.g. `username`, `email`, `sub`)
`endpoint.N.query.script`	JS expression building the query string
`endpoint.N.mapping`	`apiField→claimName` pairs (comma-separated, JSONPath supported)

Project Structure

src/main/java/com/github/jowe112/keycloak/
  mapper/
    RestClaimMapper.java          # Main OIDC mapper
    SamlRestClaimMapper.java      # Main SAML mapper
    RestMapperConfig.java         # Shared configuration setup
    ConfigParser.java             # Parses KC config map → List<EndpointConfig>
    EndpointConfig.java           # Per-endpoint config POJO
    MappingRule.java              # apiField→claimName mapping rule
    QueryScriptEvaluator.java     # GraalVM Polyglot JS evaluation
    RestApiClient.java            # Apache HttpClient 5 wrapper (apikey + oauth2)
    JsonPathMapper.java           # Jayway JSONPath + Jackson field mapping
    PersistentUserHandler.java    # TTL cache via UserModel attributes
    TransientUserHandler.java     # Live fetch, no persistence
  admin/
    TestQueryResourceProvider.java        # JAX-RS test-query resource
    TestQueryResourceProviderFactory.java # RealmResourceProviderFactory

src/main/resources/META-INF/services/
  org.keycloak.protocol.ProtocolMapper
  org.keycloak.services.resource.RealmResourceProviderFactory

Requirements

Keycloak 26.x (Quarkus distribution, GraalVM JDK)
Java 21
Maven 3.9+

REST Claim Mapper