Skip to content

Waldur Keycloak mapper

Custom Keycloak OIDC protocol mappers that integrate with Waldur so OIDC tokens reflect Waldur permissions, offering access, and per-offering identities. The build produces a single shaded JAR that operators drop into Keycloak's providers directory; Keycloak picks it up via SPI on next start.

What's in the box

Display name in Keycloak Purpose
Waldur preferred username mapper Adds the per-offering preferred username from Waldur as a custom claim.
Waldur offering access mapper Checks per-user offering access in Waldur and mutates Keycloak group/role membership accordingly.
Waldur MinIO mapper Adds a comma-separated list of customer or project UUIDs as a claim, intended for MinIO policy mapping.

All three mappers register under the standard Token mapper category in the Keycloak admin UI (Clients → your client → Client scopes → Mappers).

Mappers

Waldur preferred username mapper

Resolves a user's preferred username for a specific Waldur offering and emits it as an OIDC claim on the ID token, access token, and userinfo response.

Configuration

Parameter Description
Waldur API URL Base URL with trailing slash, e.g. https://waldur.example.com/api/.
Offering UUID UUID of the Waldur offering to look up the username in.
API Token Waldur API token (sent as Authorization: Token <token>).
TLS Validation When off, disables both hostname and certificate-chain verification.
Claim Name OIDC claim name to write the username into.

Waldur offering access mapper

On every token issuance, asks Waldur whether the user has access to the configured offering and reconciles Keycloak state to match: joins/leaves a configured group and grants/revokes a configured role.

Heads up — side effects. This mapper mutates Keycloak user-group and user-role state during token issuance. That's unusual for an OIDC mapper. Be deliberate about which clients trigger it and how often tokens are minted.

Configuration

Parameter Description
Waldur API URL Base URL with trailing slash.
Offering UUID UUID of the offering to check access against.
API Token Waldur API token.
Username Source id (Keycloak user ID) or username.
Group name Group to add/remove the user from. The mapper resolves it as /<name>; nested groups are not supported.
Add to group If off, group membership is not touched.
Role name Realm role to grant/revoke.
Assign role If off, role assignment is not touched.
Claim Name OIDC claim name to write group info into (optional).

TLS validation is always strict for this mapper — there is no toggle.

Waldur MinIO mapper

Aggregates the user's Waldur permissions at customer or project scope and emits the matching scope UUIDs as a comma-separated string under a single claim. MinIO can then map that claim to its policy engine.

Configuration

Parameter Description
Waldur API URL Base URL with trailing slash.
API Token Waldur API token.
Permission Scope customer or project.
TLS Validation When off, disables both hostname and certificate-chain verification.
Username Source id (Keycloak user ID) or username.
Claim Name OIDC claim name to write the UUID list into (e.g. policy).

Example claim payload. For a user who is owner in customers C1, C2 (with Permission Scope = customer and Claim Name = policy):

1
2
3
{
  "policy": "c1-uuid-here,c2-uuid-here"
}

Building from source

Prerequisites

  • JDK 17 (the project compiles to --release 17).
  • Maven 3.6+.
  • Docker — only needed for integration tests (mvn verify).

Build

1
2
3
mvn clean install            # compile, run unit tests, build shaded JAR (skips ITs)
mvn -B verify                # also runs the Testcontainers-based integration test
mvn clean install -DskipTests   # skip all tests

The shaded JAR lands at target/waldur-keycloak-mapper-<version>.jar. Locally, <version> falls back to the <revision> property in pom.xml (currently 1.4.0); CI overrides it via -Drevision=<tag>.

Tests

  • Unit tests under src/test/java/... — verify URL construction and special-character encoding.
  • Integration test (KeycloakProviderIT) — boots a Keycloak container with the freshly-built JAR mounted as a provider and asserts that all three mappers register. Auto-skips when Docker isn't available. The image registry can be overridden with -Ddocker.registry.prefix= (default mirrors via registry.hpc.ut.ee/mirror/).

Installation in Keycloak

  1. Grab the JAR from the GitHub releases page (or build it yourself).

  2. Drop it into Keycloak's providers directory. For a Docker-based deployment:

1
2
3
4
5
6
7
8
services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.0
    command: start-dev
    ports:
      - "8080:8080"
    volumes:
      - ./waldur-keycloak-mapper-1.4.0.jar:/opt/keycloak/providers/waldur-keycloak-mapper-1.4.0.jar

The leading ./ matters — without it Docker Compose treats the entry as a named volume rather than a bind mount.

  1. Restart Keycloak so the SPI loader picks up the new provider.

  2. In the admin console, configure the mappers under Clients → your client → Client scopes → scope → Mappers → Add mapper → By configuration. Pick one of the three display names listed at the top of this README.

Compatibility

Mapper version Keycloak Java
1.4.x 26.x 17

Older mapper versions targeted earlier Keycloak releases; check CHANGELOG.md and the release notes if you need to pin to an older line.

Releasing

Releases are developer-driven, not CI-automated:

1
2
./scripts/release.sh 1.4.0       # bumps <revision>, generates a CHANGELOG entry, commits, tags
git push origin master --tags    # CI picks up the tag and publishes the GitHub release

See CLAUDE.md for the full release-flow notes.

License

MIT — Copyright (c) 2025-2026 OpenNode OÜ.