Skip to main content
Version 0.2Draft

Learn the basics

This page is a quick orientation glossary, sized for someone getting started. The full, authoritative entity model (User, Organisation, Partner, Application, Sphere, Subscription, Group, Claim Template, Consent, Federation) lives in Concepts and Fundamentals - Roles in the Ecosystem. Where this page and that one differ in depth, the Concepts section is canonical.

Core identity concepts​

Authentication vs authorisation​

Authentication answers "who is this user?" LuxID authenticates the user against the credentials they have set on their account - their email, plus either a password they have defined (optionally combined with a second factor: OTP, TOTP, or LuxTrust) or a passkey (passwordless) - and issues a signed ID token asserting the authenticated session. This is distinct from identity verification (proving the user's real-world identity attributes), which LuxID handles separately through LuxID Verified using qualified services such as LuxTrust or the EUDI Wallet.

Authorisation answers "what is this user allowed to do?" Most business-logic authorisation stays in your application. LuxID provides two opt-in capabilities at the identity layer:

  • Consent management - the user authorises which Claims your Application receives via the LuxID consent screen. Only Claims you pre-declared at Application registration are requestable - LuxID acts as a privacy guardrail (see Privacy and consent).
  • Access Rules - server-side conditions LuxID evaluates at sign-in time. They come in three sub-types: Auth requirements (minimum auth_level), Guard rule (evaluated before the consent screen), and User rule (evaluated after). Each rule is built from base conditions combined with anyOf / allOf, can reference Group memberships, and can carry a custom error message.

Groups are a Partner-managed attribute (e.g. admin, editor, vip). Memberships surface as a token claim and can be referenced inside Access Rules.

At runtime your application receives: who the user is, what auth_level they reached, what they consented to share, which Groups they belong to, and confirmation that the Access Rules passed. Your application decides everything beyond that.

For the deep model and the operational detail, see Roles in the ecosystem and the Register an Application page.

Federation​

Federation means one identity system trusts assertions from another. When a user signs in to your application via LuxID:

  1. Your application redirects to LuxID (the Identity Provider, IdP).
  2. The user authenticates directly with LuxID.
  3. LuxID issues a signed token to your application (the Relying Party, RP).
  4. Your application trusts that token because it can verify the signature against LuxID's published keys.

Neither the user's password nor raw credentials ever reach your application. This is the core security benefit of federation.

Sessions vs tokens​

ConceptWhat it isLifetime
LuxID sessionThe authenticated session on https://login.luxid.lu (opens in a new tab) - allows SSO across PartnersManaged by LuxID, independent of your app
ID tokenA signed JWT asserting the user's identity; for your app's consumption only - do not pass to APIs~1 hour
Access tokenA bearer credential presented to resource servers (APIs) to prove authorisationShort-lived
Refresh tokenUsed to obtain new access tokens without re-authenticating the userLong-lived

Tokens are not sessions. Your application manages its own application session (cookie, server-side store) independently of LuxID's tokens. When an access token expires, you use the refresh token to get a new one silently. When the refresh token expires, the user must re-authenticate.

For full token and claims documentation see Tokens and claims.

The LuxID domain model​

LuxID organises access around six entities. Understanding these before you register your application will save time.

Organisation​

The top-level legal entity - the company or public body signing the LuxID Agreement. Example: RTL Group S.A., Cactus S.A., CFL (Chemins de Fer Luxembourgeois).

Partner​

The unit of API access. A Partner holds a Client ID and Client Secret. One Organisation may have multiple Partners - typically one per subsidiary, business unit, or dedicated development team within the same Organisation. Each Partner has its own registered Applications, Claim Templates, and Groups.

Application​

A concrete software product - a website, a mobile app, a kiosk, a backend service. An Application belongs to exactly one Partner. It has registered redirect URIs and a declared set of claims. Claims and user consent are scoped to the Application: a user who accepted claims for one Application must accept again for a sibling Application under the same Partner. See Privacy and consent for the consent lifecycle. The same Application name may appear in both UAT and Production, but each environment holds a completely independent registration with its own Client ID, Client Secret, redirect URIs, and lifecycle.

Sphere​

The pseudonymisation domain. A Sphere is not nested under an Organisation or a Partner: it is a peer-level entity that Partners (and the Organisations behind them) are associated with via a many-to-many relationship. The only entity strictly bound to a Sphere is the Application: every Application belongs to exactly one Sphere.

LuxID assigns each user a sub (subject identifier) that is Sphere-scoped:

  • Applications in the same Sphere see the same sub for a given user. Sharing a Sphere can be intentional within a Partner, across multiple Partners under the same Organisation, or even across Partners belonging to different Organisations - the last case requires explicit LuxID approval and is used when two distinct companies want a consistent user identifier (for example, a joint product). Sphere membership is managed by LuxID, not by Partners.
  • Applications in different Spheres see different sub values for the same user. This prevents cross-context tracking.

Sphere selection is an architectural decision you make at design time, and changing it later means the existing sub values become invalid. See Plan and design for the decision matrix.

Subscription​

A Subscription represents a specific user's connection to a specific Application. LuxID creates a Subscription at the moment the user explicitly consents to share their data with the Application on the LuxID consent screen - not at the first redirect to LuxID. If the user cancels at the consent screen, no Subscription is created. Revoking the last Subscription within a Sphere and re-subscribing generates a new sub for that user in that Sphere - treat sub as stable only as long as the Subscription exists. This is privacy by design: a user who revoked consent and later returns to the same Application (even via a different or changed email) should not be re-identifiable by the application. The new sub makes them effectively a new user from the Application's perspective.

A Subscription can be terminated in two ways:

  • By the user, from account.luxid.lu (opens in a new tab) under Account / Applications - the standard self-service consent-revocation path.
  • By the Partner, via the Partner API - typically when the user has cancelled the Partner's end-service (closed their MyPost account, terminated their RTL Play subscription, ...) and the Partner wants LuxID's state to mirror that.

In both cases, the next time the user signs in to that Application via LuxID, the consent screen is shown again - the user must explicitly re-consent for a new Subscription to be created.

Subscriptions are also LuxID's billing unit: the number of active Subscriptions per Application is what LuxID counts when computing per-Partner usage.

Claim Template​

A declared attribute that your application requests from LuxID. Before going to production, you declare which claims you need (e.g. given_name, email, birthdate). LuxID presents the user with a consent screen listing the user-facing claims. You may only receive claims you have declared.

Each Claim Template has two orthogonal properties:

Type - either USER or TECHNICAL:

  • USER claims carry user-facing personal information (name, email, phone, birthdate, ...) and are listed on the consent screen for explicit user approval.
  • TECHNICAL claims carry technical or business information defined by the Partner (correlation IDs, internal flags, contract identifiers, migration shims). Technical claims are not shown on the consent screen and must not contain personal information. Their values are set by the Partner via the Partner API, not derived from the user's LuxID profile. Technical claims are normally part of the Partner application's own business logic - LuxID recommends managing this mapping on the Partner side. The LuxID-hosted capability exists as a fallback for applications that cannot store and resolve the mapping themselves.

Necessity - either essential or voluntary:

  • Essential claims must be released for the Application's service to function. If the user declines an essential claim on the consent screen, they cannot complete sign-in and cannot use the service.
  • Voluntary claims enhance the experience but are not required. The user may decide not to disclose them and still sign in; the Application receives the rest.

The essential/voluntary distinction follows the OIDC claims parameter convention (see OIDC Core 1.0 §5.5 (opens in a new tab)). Mark a claim essential only when your service truly cannot operate without it; over-declaring essentials degrades the consent rate.

The three supported standards​

LuxID supports three identity federation standards. Choose based on your stack and use case.

OpenID Connect (OIDC)​

OIDC (OpenID Connect Core 1.0 (opens in a new tab)) is a thin identity layer on top of OAuth 2.0. It is the recommended standard for new integrations. OIDC gives you:

  • A signed ID token (JWT) asserting who the user is
  • An access token for calling UserInfo or your own APIs
  • A refresh token (with offline_access scope) for silent token renewal

Use OIDC when you are building a web application, a mobile app, or a server-side application and want a modern, library-supported integration.

LuxID supports the Authorization Code flow with PKCE (RFC 7636 (opens in a new tab)) as the recommended flow for all client types. Confidential clients (server-side apps with a securely stored secret) may use Authorization Code without PKCE, but PKCE is preferred even then.

OAuth 2.0​

OAuth 2.0 (opens in a new tab) is the underlying authorisation framework. Use it directly (without the OIDC identity layer) only if your application needs access tokens for resource access but does not need to assert user identity. In practice, most Partner integrations use OIDC, which subsumes OAuth 2.0.

SAML 2.0​

SAML 2.0 (opens in a new tab) (Security Assertion Markup Language) is an XML-based federation standard widely supported by enterprise SaaS platforms (Microsoft 365, Salesforce, ServiceNow, Atlassian, Moodle). Use SAML when:

  • Your application has a built-in SAML SP connector
  • You are integrating a SaaS platform that does not support OIDC
  • Your organisation's IT policy mandates SAML

SAML uses browser-based redirects with signed XML assertions rather than tokens. It is more complex to implement from scratch but trivial to configure in SaaS connectors. See SAML 2.0 for the integration guide and Quick Integrations for connector-based setup.

Choosing a standard​

CriterionOIDCSAML
New custom applicationPreferredPossible
SaaS platform with built-in connectorPossibleOften simpler
Mobile / native appPreferredNot recommended
API access (access tokens)Yes (OAuth 2.0 layer)No
Library ecosystemRich (most languages)Available
Assertion formatJSON (JWT)XML

When in doubt, use OIDC. It has better library support, simpler debugging (JWTs are readable), and is the direction the industry is moving.

Authentication levels​

LuxID's native authentication-strength scale is auth_level, a numeric value assigned automatically based on which authentication methods the user completed. Partners declare a minimum required level; LuxID enforces step-up authentication if the user's current session does not meet it.

auth_levelTypical methodExample use case
2Password onlyAnonymous browsing, low-risk personalisation
3 or 4Password + OTP (SMS/voice) or TOTPConsumer e-commerce, account management
8PasskeyPhishing-resistant passwordless sign-in
9LuxTrust (hardware-backed qualified credential)Financial services, identity-verified actions

LuxID's strength tiers structurally mirror the eIDAS Low / Substantial / High rationale, but LuxID is not a notified eID scheme and does not issue formal eIDAS LoA assertions. eIDAS LoA values appear in LuxID payloads only when relayed from a qualified upstream source - LuxTrust identity verification, a federated corporate IdP, or (in future) the EUDIW. For the full model, the acr claim format, and the acr_values request mechanism, see Authentication levels.

MFA methods​

LuxID supports four categories of second factor:

MethodTagDescription
One-Time Code via SMS or voice callotpA random code delivered out-of-band. SMS by default; voice call as fallback
Authenticator app (TOTP)totpA time-based code derived from a shared secret using apps such as Aegis, FreeOTP, or Microsoft Authenticator (RFC 6238 (opens in a new tab))
PasskeyspasskeysFIDO2 / WebAuthn device-bound credentials (W3C WebAuthn Level 2 (opens in a new tab))
LuxTrustluxtrustQualified authentication using the LuxTrust mobile app or smartcard

otp and totp are distinct. otp is a random server-generated code sent to the user's phone. totp is a code the user's authenticator app derives locally from a pre-shared secret. Do not conflate them.

Next steps​

Updated 2026-07-03
On this page