Redirect URIs and domains

Planned - future LuxID Console

Self-service redirect URI management is on the LuxID roadmap. Today, redirect URI changes are performed by LuxID when you submit a request to LuxID with the list of URIs to add or remove. The rules and field formats below describe what to include in that request.

What redirect URIs are and why they matter

A redirect URI (also called callback URL or reply URL) is the exact URL LuxID returns the user's browser to after authentication, carrying the authorisation code (OIDC) or SAML response.

When LuxID redirects the user's browser back to your application after authentication, it appends an authorisation code (OIDC) or a SAML response to a URL you specify. That URL is the redirect URI (also called callback URL or reply URL).

If LuxID accepted any URL a client requested, an attacker could intercept authorisation codes by substituting their own URL. The redirect URI allowlist is the primary safeguard against this attack. LuxID enforces an exact-match policy: the URI the application sends in the authorisation request must match - character for character - one of the URIs registered in the Console.

Redirect URI rules for OIDC

Exact match only

LuxID performs a byte-exact comparison between the redirect_uri in the authorisation request and each URI in the allowlist.

There are no wildcards, no prefix matches, and no pattern matching. The following pair would fail even though they look similar:

• Registered: https://app.example.lu/callback
• Requested: https://app.example.lu/callback/

The trailing slash makes them different strings.

HTTPS required for production

All redirect URIs for Applications registered in the Production environment must use https://. HTTP URIs are rejected.

Exceptions:

• http://localhost and http://127.0.0.1 are allowed in UAT only, for local development.
• http://[::1] (IPv6 loopback) is accepted in UAT on the same basis.

Mobile app deep-link schemes

Native mobile applications use custom URI schemes or Universal Links / App Links for their callback:

• Custom scheme (acceptable): com.example.myapp://callback - register the exact scheme and path.
• Universal Links / App Links (preferred for security): https://app.example.lu/callback - this is a standard HTTPS URI and follows the same rules as web URIs.

Custom schemes are accepted but carry a risk: any app on the device can claim to handle the scheme. Where possible, use Universal Links (iOS) or App Links (Android) instead.

Port numbers

The port is part of the URI and must match exactly:

• Registered: https://app.example.lu:8443/callback
• Requested: https://app.example.lu/callback - fails (default port 443 is not the same as an explicit 8443)

For local development in UAT, common development server ports (http://localhost:3000/callback, http://localhost:8080/callback) must each be registered individually if your team uses multiple ports.

Path and query string

The registered URI must include the exact path your application sends. Query parameters are not permitted in the registered URI - LuxID appends code and state to the URI after authentication, so query parameters in the base URI are not supported and will cause a mismatch.

Registering redirect URIs

Redirect URIs are configured per Application registration. Because UAT and Production are completely independent environments, each environment's Application registration maintains its own separate allowlist.

To add or change redirect URIs:

1. Log in to the Console at https://console.luxid.lu (opens in a new tab).
2. Navigate to Applications and select your Application.
3. Under Redirect URIs, select Add URI.
4. Enter the URI and select Save.

Changes to redirect URIs take effect immediately. There is no propagation delay.

You can register multiple redirect URIs per Application. This is useful when:

• Your application runs on multiple domains (for example, https://app.example.lu/callback and https://app.example.com/callback).
• You need to support both a primary domain and a maintenance domain.
• Your application uses different paths for different login entry points.

Remove URIs that are no longer in use. Stale URIs expand the attack surface unnecessarily.

Domain ownership verification

LuxID requires Partners to demonstrate control of the domains used in redirect URIs before those URIs can be used in Production. This prevents a Partner from accidentally (or maliciously) registering a redirect URI on a domain they do not own.

Domain verification is performed during the Partner onboarding process. If you add a new domain to your redirect URI allowlist after onboarding, you will need to complete a verification step for that domain. Contact LuxID or refer to Service provider onboarding for the current verification process.

Domain verification is not required in UAT. Localhost URIs in UAT are exempt from domain verification.

SAML: assertion consumer service URLs

For Applications using SAML 2.0, the equivalent of a redirect URI is the Assertion Consumer Service (ACS) URL. LuxID posts the SAML response to the ACS URL after the user authenticates.

The same rules apply:

• Exact-match only.
• HTTPS required in Production.
• One or more ACS URLs can be registered per Application.
• The ACS URL sent in the AuthnRequest must match a registered value, or the request is rejected.

SAML additionally uses an Entity ID (the Service Provider's unique identifier). Confirm the correct Entity ID with your SAML SP library before registering it in the Console.

Common pitfalls

The most frequent causes of redirect_uri_mismatch errors, in order of occurrence:

Trailing slash mismatch

The most common single cause of redirect URI errors. Your application sends https://app.example.lu/callback/ but you registered https://app.example.lu/callback (or vice versa).

Fix: check the exact URI your library constructs. Many OAuth libraries append a trailing slash automatically. Register the URI exactly as the library sends it.

HTTP vs HTTPS

Your application sends http://app.example.lu/callback but you registered https://app.example.lu/callback.

This often happens when:

• A load balancer or reverse proxy terminates TLS and forwards HTTP internally.
• The application determines its own base URL from a request header that reflects the internal scheme, not the public scheme.

Fix: ensure your application constructs redirect URIs using the public-facing scheme (https://). Configure X-Forwarded-Proto handling if you are behind a reverse proxy.

Port mismatch

Your application sends https://app.example.lu:443/callback with an explicit port, but you registered https://app.example.lu/callback without a port (default HTTPS port is implicit).

Fix: register both forms if your application behaves inconsistently, then normalise the application to omit the default port.

Case sensitivity

URI schemes and hostnames are case-insensitive by specification, but LuxID's matcher treats the full URI as case-sensitive for simplicity and auditability.

Fix: use lowercase throughout. Registered: https://app.example.lu/callback. Requested: https://app.example.lu/callback. Match.

Stale registration after a domain change

You moved your application to a new domain but forgot to update the Console. LuxID still holds the old domain as the only registered URI.

Fix: add the new URI before the migration, then remove the old one after confirming the new domain is working.

Diagnosing redirect URI errors

When a redirect_uri_mismatch error occurs, LuxID logs the event in the authentication log with the exact URI that was received. Use the Console logs to compare what LuxID received against what you intended to register.

See Logs and audit trails for how to filter logs by Application and error type.

For further guidance, see Redirect and domain issues.

Security recommendations

• Register the minimum set of redirect URIs needed. Remove URIs that are no longer in use.
• Prefer HTTPS over custom URI schemes for mobile app callbacks.
• In UAT, restrict localhost URIs to specific ports your team actually uses. Do not register open-ended localhost entries.
• Review your redirect URI list as part of each deployment review, alongside your Dependency and secrets audit.
• Never register a URI on a domain you do not control, even temporarily. Verify domain ownership before adding new domains.