Deep Linking with Enterprise Connections (SAML / OIDC)

Part of the Deep Linking series. This page covers the Auth0 self-service enterprise connections (SAML and OIDC). If you have not read the main deep-linking overview yet, start there first — it explains what deep linking is, how it works at a high level, and where each authentication method stands.

What Are Enterprise Connections?

Since mid-2025 we onboard customers using Auth0's self-service SAML and OIDC connections. Each customer configures their own identity provider, and Auth0 brokers the authentication on their behalf. From the user's perspective, the experience is the same as any other SSO login — they land on their institution's login page and return to Statista after authenticating.

For background on how these connections work and why we chose this approach, see SAML Auth0 Self-Service Overview.

How Deep Linking Works Here

Enterprise connections go through Auth0 using standard OIDC, which gives us a natural mechanism for carrying the destination URL: the state parameter.

When remix-sso initiates an OIDC authorization request, it can embed the target URL (or a reference to it) in the state parameter. Auth0 carries state through the entire flow — including the SAML round-trip with the customer's IdP — and echoes it back unchanged in the callback. The callback then reads state, extracts the target, and redirects the user there.

In our implementation, the target URL is stored in the __sso_redirect cookie before the authorization request is initiated. This keeps the approach consistent with the OpenAthens Keystone path: the cookie is the single source of truth for the destination, regardless of which authentication method was used.

The Full Flow

sequenceDiagram
    actor User
    participant App as Statista<br/>(remix-sso)
    participant Cookie as Cookie Store<br/>(__sso_redirect)
    participant Auth0 as Auth0
    participant IdP as Customer IdP<br/>(SAML or OIDC)
    participant Callback as remix-sso<br/>/sso/callback
    participant Target as Target Resource Page

    User->>App: Clicks deep link (e.g. intranet, LMS, email)
    App->>Cookie: Set __sso_redirect = target path (httpOnly, sameSite:lax)
    App->>Auth0: 302 → /authorize?connection=customer-saml&state=…
    Auth0->>IdP: SAML AuthnRequest (or OIDC redirect)
    IdP-->>User: Login prompt
    User->>IdP: Credentials
    IdP-->>Auth0: Assertion / token
    Auth0->>Auth0: Run post-login Actions
    Auth0->>Callback: 302 → /sso/callback?code=…
    Callback->>Auth0: Token exchange (code → tokens)
    Callback->>Callback: Validate tokens, establish session
    Callback->>Cookie: Read __sso_redirect cookie
    Callback->>User: 302 → target resource path ✓
    User->>Target: Lands on the specific page

How to Initiate a Deep Link

An enterprise connection deep link is initiated by landing the user on our application with a target query parameter, typically via a URL the customer embeds in their intranet, LMS, or email system.

The entry point in remix-sso reads the target parameter, validates it, stores it in __sso_redirect, and then initiates the Auth0 authorization flow with the appropriate connection. The rest of the flow is identical to any other enterprise SSO login.

If the customer's link does not include a target parameter, the user is redirected to the homepage after authentication — the default behaviour.

Connection-Specific Notes

SAML Connections

When the customer's identity provider is configured as a SAML connection in Auth0, Auth0 handles the SAML round-trip internally. From remix-sso's perspective, Auth0 is the only OIDC layer it talks to — the SAML details are transparent. This means the deep-link mechanism (cookie + OIDC callback) is exactly the same regardless of whether the underlying connection is SAML or OIDC.

One thing to be aware of: Auth0's SAML connections must have a federated_id claim configured in order for our session to correctly identify the user. See ADR-004: Require federated_id Claim for the rationale.

OIDC Connections

When the customer's identity provider is itself an OIDC provider, Auth0 federates the OIDC flow. The deep-link cookie mechanism is unchanged. The state parameter that Auth0 uses internally for its own round-trip is separate from our __sso_redirect cookie — they do not interfere.

From a deep-linking perspective, OIDC connections are mechanically identical to SAML connections. Auth0 brokers the OIDC round-trip with the customer's IdP transparently; remix-sso sees only the standard OIDC callback and reads __sso_redirect the same way regardless of what connection type Auth0 used upstream. There is no separate deep-linking implementation needed for OIDC-backed enterprise connections.

If, in the future, there is a need to expose lower-level OIDC mechanics to customers — such as state encoding for flows they initiate themselves, PKCE, or third-party-initiated login — that would be the point to promote this into a dedicated page. For now, the cookie-based approach covers all cases.

Common Pitfalls

The target parameter in the initiating link is absent. Enterprise connection deep links depend on the customer constructing the link with a target parameter. If the customer's intranet or LMS does not include it, users will always land on the homepage. This is a configuration concern on the customer side, not a code issue.

The target URL is not validated. Always validate the target parameter against a domain allowlist before storing it. An unvalidated redirect destination is an open redirect vulnerability.

The cookie is lost during the round-trip. If the OIDC callback runs on a different subdomain than the page that set the cookie, the cookie will not be sent. Ensure the cookie is scoped to the correct parent domain.