Integrations · OIDC

Keycloak Federation

Configure Keycloak to use Clavex as an upstream OpenID Connect Identity Provider (IdP broker). Users in a Keycloak realm can authenticate via Clavex, enabling eIDAS, SPID, CIE, BundID, and passkeys for Keycloak-managed applications.

Use case: Your existing applications are already integrated with Keycloak. Instead of migrating them to Clavex directly, you federate Keycloak with Clavex, gaining all EU eID methods with zero changes to your app configurations.

Prerequisites

Keycloak ≥ 20 (Quarkus distribution)
Keycloak realm admin access
Clavex at https://id.acme.eu, org slug acme

Step 1 — Register OIDC Client in Clavex

Keycloak acts as an OIDC Relying Party (client) towards Clavex. Register it:

Admin API (curl)

$ curl -X POST https://id.acme.eu/api/v1/organizations/acme/clients \ -H 'Authorization: Bearer $ADMIN_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "client_id": "keycloak-myrealm", "client_name": "Keycloak (myrealm)", "grant_types": ["authorization_code"], "redirect_uris": [ "https://keycloak.acme.eu/realms/myrealm/broker/clavex/endpoint" ], "scopes": ["openid", "profile", "email"], "token_endpoint_auth_method": "client_secret_basic" }'

Step 2 — Add Identity Provider in Keycloak

Log in to Keycloak Admin Console → select your realm (e.g. myrealm)
Go to Identity providers → Add provider → OpenID Connect v1.0

Fill in:

Field	Value
Alias	`clavex`
Display name	`Sign in with Clavex`
Discovery endpoint	`https://id.acme.eu/acme/.well-known/openid-configuration`
Client authentication	`Client secret sent as basic auth header`
Client ID	`keycloak-myrealm`
Client secret	`cs_xxxxxxxxxxxxxxxx`
Default scopes	`openid profile email`
Store tokens	enable if you need to call Clavex APIs on behalf of users
Trust email	enable if Clavex emails are already verified

Click Save

Step 3 — Configure Mappers

After saving, go to Mappers tab of the identity provider to map Clavex claims to Keycloak attributes:

Mapper type	Claim	User attribute
Username template importer	`preferred_username`	Keycloak username
Attribute importer	`given_name`	`firstName`
Attribute importer	`family_name`	`lastName`
Attribute importer	`email`	`email`

Step 4 — Test Federation

Go to your Keycloak realm's account console: https://keycloak.acme.eu/realms/myrealm/account
Click Sign in with Clavex — you are redirected to Clavex
After Clavex authentication, Keycloak creates a federated user and redirects to the account console

bash — test via Keycloak OIDC token endpoint

# After successful federation, the Keycloak realm issues its own tokens # containing Clavex user attributes. Test with a public client: $ curl "https://keycloak.acme.eu/realms/myrealm/protocol/openid-connect/token" \ -d "grant_type=authorization_code&code=AUTH_CODE&redirect_uri=...&client_id=test-client"

First Login Flow

Configure the First broker login authentication flow in Keycloak to handle account linking when a Clavex user signs in to Keycloak for the first time:

Keycloak Admin → Authentication → Flows → First broker login
Set Review profile (update profile on first login) to off to skip the profile review screen
Configure Handle Existing Account to automatically link by email if a local account exists

Troubleshooting

Symptom	Cause	Fix
Identity provider not shown on login page	IdP alias not in identity provider list	Check Keycloak → Identity providers — ensure `clavex` is listed and enabled
`invalid_client` from Clavex	Client ID or secret wrong	Re-check the identity provider settings in Keycloak; update client secret in Clavex if rotated
`You are already authenticated` loop	Keycloak re-uses an active session without going to Clavex	Set `prompt=login` or add `max_age=0` to force re-authentication
Username conflict on first login	Local Keycloak user with same username exists	Configure first login flow to link by email; or remove the local user first