Skip to main content
Version 0.6Draft

Identity broker integrations

What is an identity broker integration?​

An identity broker integration is the pattern where your organisation already operates its own identity layer - typically Keycloak, FusionAuth, a commercial federation hub, or a self-hosted Matrix homeserver - and you want LuxID to be one of the upstream identity sources that your broker can authenticate against. Users who choose "Sign in with LuxID" inside your broker's login page are redirected to LuxID, authenticate there, and are redirected back. Your broker then re-issues its own session tokens or assertions to downstream applications.

The architecture follows a three-hop flow: the user's browser starts at your application, is sent to your broker's login page, and the broker in turn initiates an OIDC authorisation code flow with LuxID. From LuxID's perspective your broker is just another registered OIDC client application - it holds a Client ID and Client Secret issued by LuxID, and it must present a registered Redirect URI when it calls LuxID. From your application's perspective nothing has changed: it still talks only to your broker.

This path sits in the same section as the leaf SaaS configurations (WordPress, Odoo, etc.) because the broker's own configuration screen is where the work happens - no custom application code is required. However it is operationally quite different: a leaf SaaS tool is the end consumer of the LuxID token, whereas a broker is a re-issuer. The distinction matters for logout, consent, user provisioning, and token lifetime design.

When to use this path​

Use an identity broker integration when your organisation already runs an IdP and centralising on it is the right architectural decision. Specific situations where this pattern fits well:

  • You operate Keycloak, FusionAuth, or a similar broker and do not want to point every downstream application individually at LuxID - the broker absorbs that complexity.
  • Your broker needs to provision LuxID-authenticated users into its own user store just-in-time (JIT provisioning) on first login, so that downstream applications can look up local profile attributes, roles, or group memberships.
  • You are mixing multiple identity sources - for example, corporate Active Directory users alongside LuxID consumer accounts - and you want a single broker to present a unified login experience.
  • Your authorisation logic lives in the broker (group membership, role assignment, access policies) and you want to keep it there rather than replicating it per-application.

If none of these apply and you are simply connecting one off-the-shelf tool to LuxID, see the Tool-specific integrations guide instead.

Operational implications​

Placing a broker between LuxID and your applications introduces a second trust boundary. Before committing to this architecture, review the trade-offs:

FactorImplication
Trust boundaryYour broker trusts LuxID; your applications trust your broker. A misconfiguration at either hop can break the chain. Applications do not validate LuxID tokens directly - they only see broker-issued tokens.
Token translationThe broker re-issues its own tokens after receiving LuxID's ID token. Token format, claims, and lifetimes are determined by your broker configuration, not by LuxID. Ensure claim mapping is correct or downstream apps will receive incomplete profiles.
Logout propagationLogout requires two hops: clearing the application session, then clearing the broker session. LuxID does not expose an OIDC end_session_endpoint and revocation does not end the LuxID SSO session; clearing the LuxID session is user-driven via a redirect to https://login.luxid.lu/auth/logout?client_id=<id>. See the Logout propagation section below.
ConsentThe user consents once at LuxID (scope-level consent). Your broker may then pre-consent its downstream applications, meaning the user does not see a second consent screen for each app. This is typically the desired behaviour but should be a deliberate policy decision.
User provisioningOn first login, the broker creates a local user record from the LuxID claims (JIT provisioning). Ensure your broker's provisioning policy handles duplicate emails and account linking correctly - particularly if some users already exist with a local password.

Before you start​

The prerequisites are the same as the rest of this section. Confirm all of the following before opening your broker's configuration screen:

  • LuxID Partner registration: Your organisation is registered as a LuxID Partner. Contact LuxID if you are not sure.
  • Application registered with LuxID: You have a registered application with a Client ID and Client Secret. The registered Redirect URI must match the callback URL your broker will use after LuxID authentication.
  • Discovery URL: https://login.luxid.lu/.well-known/openid-configuration (production). For UAT, replace login.luxid.lu with login-uat.luxid.lu.
  • HTTPS on the callback URL: The broker's redirect URI must be HTTPS in production. LuxID enforces exact-match URI validation.
  • UAT credentials first: Register a separate application with LuxID for your UAT environment and test there before switching to production endpoints.

The LuxID OIDC endpoints for reference:

EndpointURL
Issuerhttps://login.luxid.lu
Authorisationhttps://login.luxid.lu/mga/sps/oauth/oauth20/authorize
Tokenhttps://login.luxid.lu/mga/sps/oauth/oauth20/token
UserInfohttps://login.luxid.lu/mga/sps/oauth/oauth20/userinfo
JWKShttps://login.luxid.lu/mga/sps/oauth/oauth20/jwks/OIDC-LUXID
Discoveryhttps://login.luxid.lu/.well-known/openid-configuration

For UAT, replace login.luxid.lu with login-uat.luxid.lu in all URLs above.

Pick your broker​

Logout propagation​

When a user signs out, you need to decide how far the sign-out propagates. With a broker in the chain there are three layers:

  1. The application session
  2. The broker session
  3. The LuxID session at login.luxid.lu
LuxID's position on global sign-out

LuxID does not expose an OIDC end_session_endpoint and does not implement RFC 7009 token revocation as a way for a Partner application to terminate the LuxID session. The reason is architectural: LuxID is an SSO authority used by many Partners simultaneously; it would be inappropriate for a single application to end the user's session at every other Partner they have an active subscription with. The application or broker is responsible for terminating its own session.

Where a user explicitly wants to end their LuxID session as well, the application or broker can redirect to https://login.luxid.lu/auth/logout?client_id=<your-client-id>. LuxID then renders a logout confirmation screen that displays the application name (derived from the client_id) and lets the user choose to end the LuxID session. The user decision is the trigger - not the application's.

There are two practical patterns:

Pattern A - clear application session only

The application destroys its local session cookie. The broker session and the LuxID session remain active. If the user navigates to another application in the same broker realm, they are still signed in there (and at LuxID). This is the cheapest option but leaves sessions alive that the user may expect to have ended.

Pattern B - clear application and broker session (recommended for most consumer use cases)

The application redirects the user to the broker's end-session endpoint. The broker clears its own session (and all associated application sessions in the same realm if it supports global logout). The LuxID session is not explicitly terminated; it will expire on its own. This is the right default for most consumer-facing deployments where the user is signing out of your service, not necessarily out of LuxID.

Optional final hop - user-driven LuxID sign-out

After clearing the broker session, the broker or application may redirect the user to https://login.luxid.lu/auth/logout?client_id=<your-client-id>. LuxID displays a logout confirmation tied to the requesting application. The user, not the application, then decides whether to also end the LuxID session. This is useful on shared devices but should not be the default for personal-device deployments.

For most deployments, Pattern B strikes the right balance between security and user experience. Discuss pattern selection with your security officer if you handle sensitive personal data or regulated information.

Cross-references​

Updated 2026-07-03
On this page