How Auth0 Auth JS Builds Logout URLs for Tenants Without end_session_endpoint

When an Auth0 tenant lacks an end_session_endpoint, the Auth0 Auth JS SDK automatically falls back to the legacy /v2/logout endpoint, constructing a URL with client_id and returnTo parameters to ensure users can always be logged out regardless of tenant configuration.

The auth0/auth0-auth-js library provides universal logout functionality that gracefully handles tenants missing RP-Initiated Logout support. When building logout URLs for tenants without end_session_endpoint, the SDK implements intelligent fallback logic that maintains backward compatibility with Auth0's v2 logout API. This ensures applications can reliably terminate user sessions even when modern OIDC features are not enabled.

How the SDK Detects the End-Session Endpoint

The logout process begins when the application invokes AuthClient.buildLogoutUrl. Internally, the method first discovers the tenant's OpenID configuration by calling the private #discover() method.

const { configuration, serverMetadata } = await this.#discover();

if (!serverMetadata.end_session_endpoint) {
  // fallback logic …
}

This discovery fetches the tenant's metadata and checks for the presence of end_session_endpoint, which represents the RP-Initiated Logout URL defined by the OIDC specification. If this property is missing from the server metadata, the SDK immediately triggers its legacy fallback mechanism.

Fallback to the Auth0 v2 Logout Endpoint

When serverMetadata.end_session_endpoint is undefined, the SDK constructs a logout URL using the tenant's domain and the static path /v2/logout. This legacy endpoint accepts specific query parameters to complete the logout flow.

The implementation in src/auth-client.ts performs the following operations:

1. Instantiates a new URL object pointing to https://<tenant-domain>/v2/logout
2. Appends the returnTo parameter from the options object
3. Appends the client_id from the SDK configuration
4. Returns the constructed URL object

const url = new URL(`https://${this.#options.domain}/v2/logout`);
url.searchParams.set('returnTo', options.returnTo);
url.searchParams.set('client_id', this.#options.clientId);
return url;

This approach guarantees that applications receive a functional logout URL even when the tenant does not support the modern OIDC RP-Initiated Logout protocol.

Modern OIDC Logout Path

If the tenant does have an end_session_endpoint configured, the SDK delegates URL construction to the OIDC client utility. Instead of manually building the URL, it calls client.buildEndSessionUrl, which constructs a standards-compliant logout URL using post_logout_redirect_uri rather than the legacy returnTo parameter.

This dual-path architecture ensures the SDK supports both legacy Auth0 configurations and modern OIDC-compliant tenants without requiring application-level changes.

Source Code Reference

The fallback logic is implemented in src/auth-client.ts at lines 438-449, where the buildLogoutUrl method handles the conditional branching between OIDC and legacy endpoints. The test suite in src/auth-client.spec.ts (lines 85-130) validates both code paths, ensuring consistent behavior across tenant configurations.

According to the auth0/auth0-auth-js source code, this implementation allows the SDK to guarantee logout functionality across the entire Auth0 platform, regardless of whether specific tenants have enabled RP-Initiated Logout features.

Practical Examples

Legacy logout for tenants without RP-Initiated Logout:

import { AuthClient } from '@auth0/auth0-react';

const auth0 = new AuthClient({
  domain: 'legacy-tenant.auth0.com',
  clientId: 'YOUR_CLIENT_ID',
});

const logoutUrl = await auth0.buildLogoutUrl({
  returnTo: 'https://myapp.com/goodbye',
});

// Results in: https://legacy-tenant.auth0.com/v2/logout?returnTo=https%3A%2F%2Fmyapp.com%2Fgoodbye&client_id=YOUR_CLIENT_ID
window.location.href = logoutUrl.toString();

Modern OIDC logout (when end_session_endpoint is available):

const auth0 = new AuthClient({
  domain: 'modern-tenant.auth0.com',
  clientId: 'YOUR_CLIENT_ID',
});

const logoutUrl = await auth0.buildLogoutUrl({
  returnTo: 'https://myapp.com/post-logout',
});
// URL constructed via OIDC client using post_logout_redirect_uri
window.location.href = logoutUrl.toString();

Summary

• The SDK checks for end_session_endpoint in the tenant's OIDC metadata before building logout URLs
• When the endpoint is missing, it automatically falls back to https://<domain>/v2/logout with client_id and returnTo parameters
• The fallback logic resides in src/auth-client.ts and ensures backward compatibility with all Auth0 tenants
• Modern tenants with RP-Initiated Logout enabled use the standards-compliant client.buildEndSessionUrl method instead
• Applications using auth0/auth0-auth-js receive functional logout URLs regardless of tenant configuration

Frequently Asked Questions

What is the end_session_endpoint in Auth0?

The end_session_endpoint is a URL defined in the OpenID Connect (OIDC) discovery metadata that enables RP-Initiated Logout. When present, it allows the SDK to redirect users to a standardized logout endpoint that accepts post_logout_redirect_uri parameters. Auth0 tenants must explicitly enable RP-Initiated Logout in their settings to expose this endpoint.

How does the SDK handle tenants that don't support RP-Initiated Logout?

The SDK detects the missing endpoint during the discovery phase and automatically constructs a legacy logout URL using the /v2/logout path. This URL includes the client_id and returnTo query parameters required by Auth0's legacy logout API, ensuring the logout process completes successfully even on older tenant configurations.

What parameters does the legacy v2/logout endpoint require?

The legacy endpoint requires two specific query parameters: client_id (identifying the application) and returnTo (specifying where to redirect the user after logout). The SDK extracts these values from the SDK configuration and the options passed to buildLogoutUrl, then appends them to the URL before returning it to the caller.

Where can I find the implementation of this fallback logic?

The conditional logic that checks for end_session_endpoint and constructs the fallback URL is located in src/auth-client.ts between lines 438-449. The corresponding test coverage demonstrating both the OIDC and fallback paths exists in src/auth-client.spec.ts at lines 85-130.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}