Keycloak

Keycloak calls this feature "Identity Brokering". You add LuxID as an external OpenID Connect v1.0 Identity Provider inside a Keycloak realm, and Keycloak users can then select "Sign in with LuxID" at the Keycloak login page.

Red Hat build of Keycloak / Red Hat SSO

Same product. The "Red Hat build of Keycloak" (rebranded from "Red Hat Single Sign-On" / RH-SSO around 2022) is Red Hat's enterprise-supported distribution of upstream Keycloak. The admin console, realm model, and Identity Brokering configuration screens are identical to community Keycloak. Every step below applies; the only practical difference is the support contract and the version cadence (Red Hat ships LTS versions on a slower schedule than upstream).

Prerequisites

• Keycloak 21 or later, or Red Hat build of Keycloak 22+ (earlier versions support the same flow but menu paths differ slightly).
• Realm administrator access.
• Your LuxID Client ID, Client Secret, and the registered Redirect URI for this Keycloak realm's broker callback. The callback URL will be in the form https://<keycloak-host>/realms/<realm>/broker/luxid/endpoint.

Add the identity provider

1. Sign in to the Keycloak admin console.
2. Select the correct realm from the top-left dropdown.
3. Navigate to Identity Providers in the left-hand menu.
4. Click Add provider and select OpenID Connect v1.0.

Field mapping

Fill in the provider configuration using the values below. Fields not listed here can be left at their defaults.

Keycloak field	Value
Alias	luxid
Display Name	Sign in with LuxID
Discovery URL (Use discovery endpoint)	https://login.luxid.lu/.well-known/openid-configuration
Authorization URL	https://login.luxid.lu/mga/sps/oauth/oauth20/authorize
Token URL	https://login.luxid.lu/mga/sps/oauth/oauth20/token
User Info URL	https://login.luxid.lu/mga/sps/oauth/oauth20/userinfo
JWKS URL	https://login.luxid.lu/mga/sps/oauth/oauth20/jwks/OIDC-LUXID
Issuer	https://login.luxid.lu
Client Authentication	Client secret sent as basic auth
Client ID	(your Client ID from your LuxID registration)
Client Secret	(your Client Secret from your LuxID registration)
Default Scopes	openid profile email
PKCE	Enabled, method S256
Validate Signatures	ON
Use JWKS URL	ON

If you enable "Use discovery endpoint" in Keycloak, most endpoint fields are filled automatically from the LuxID discovery document. Verify the populated values match the table above before saving.

After entering the Client ID and Client Secret, copy the Redirect URI that Keycloak displays (something like https://<keycloak-host>/realms/<realm>/broker/luxid/endpoint). This URI must be registered as an allowed Redirect URI for your application with LuxID. If it is not registered, the authorisation request will be rejected.

Claim mapping (mappers)

Once the provider is saved, open the Mappers tab for the LuxID identity provider and create the following mappers:

Claim (from LuxID)	Mapper type	Keycloak attribute
email	Attribute Importer	email
given_name	Attribute Importer	firstName
family_name	Attribute Importer	lastName
sub	Attribute Importer	(used as external ID automatically)

Keycloak automatically links the sub claim to the broker's external user ID. The email, firstName, and lastName mappers populate the Keycloak user profile on JIT provisioning.

Test login

1. Open the Keycloak account console or any application in the realm that uses Keycloak login.
2. The "Sign in with LuxID" button should appear below the username/password form.
3. Click it. You will be redirected to login.luxid.lu.
4. Complete LuxID authentication (username, password, 2FA if configured).
5. You are redirected back to Keycloak, which provisions a local account and establishes a session.
6. Inspect the new user record in Keycloak admin -> Users to confirm email, firstName, and lastName are populated.

Production checklist

Before switching from UAT to production:

• Update the Discovery URL (and all individual endpoints if you entered them manually) from login-uat.luxid.lu to login.luxid.lu.
• Register the production Keycloak redirect URI with LuxID production application record.
• Rotate the Client Secret - do not reuse the UAT secret in production.
• Confirm Validate Signatures is ON and Use JWKS URL is ON.
• Decide on the account linking strategy in the Keycloak identity provider settings: "First login flow" controls what happens when a user with an existing Keycloak account authenticates via LuxID for the first time. Review the options and select one deliberately.
• Run a full end-to-end login test in production before announcing the feature.

Common errors

Error	Likely cause	Fix
invalid_redirect_uri from LuxID	Keycloak's callback URL is not registered with LuxID	Add the exact Keycloak redirect URI to the registered Redirect URIs with LuxID
invalid_client from LuxID	Wrong Client ID or Secret, or using UAT credentials against production	Double-check credentials; confirm which environment the Keycloak discovery URL points to
Keycloak shows "Identity provider returned an error"	LuxID returned an error code; check the error and error_description parameters in the redirect URL	Enable Keycloak debug logging; inspect the URL parameters in the browser's developer tools
User lands back at Keycloak with no account created	Mapper misconfiguration; email may be missing	Verify the Attribute Importer mappers exist and the claim names match LuxID's claim names exactly
Signature validation fails	JWKS URL misconfigured or Keycloak cached a stale key	Confirm JWKS URL is https://login.luxid.lu/mga/sps/oauth/oauth20/jwks/OIDC-LUXID; clear Keycloak's key cache