How verifyLogoutToken Validates Backchannel Logout Tokens in Auth0: Required Claims and Verification Steps

The verifyLogoutToken method validates backchannel logout tokens by verifying the JWT signature against Auth0's JWKS, enforcing required claims including iat and either sid or sub, prohibiting the nonce claim, and validating the structured events claim containing the backchannel-logout event identifier.

The verifyLogoutToken method in the auth0/auth0-auth-js repository implements the complete validation flow required by the OpenID Connect Back-Channel Logout specification. Located in packages/auth0-auth-js/src/auth-client.ts (lines 564–618), this method ensures that logout tokens received via back-channel communication are authentic, properly formatted, and contain the mandatory claims needed to identify and terminate user sessions securely.

JWT Signature and Standard Claims Verification

The validation begins by establishing trust through cryptographic verification. The method retrieves the JSON Web Key Set (JWKS) from serverMetadata.jwks_uri obtained via the discovery document and creates a remote JWK set using createRemoteJWKSet.

It then calls jwtVerify with strict parameters (lines 564–580):

• issuer: Must match serverMetadata.issuer
• audience: Must match the clientId
• algorithms: Restricted to ['RS256']
• requiredClaims: Must include ['iat'] (Issued-At timestamp)

This ensures the token was signed by Auth0, intended for your specific client, and includes a valid timestamp to prevent replay attacks.

Subject and Session Identifier Validation

After signature verification, the method enforces the presence of at least one identifying claim. According to the OpenID Connect Back-Channel Logout specification, the token must contain either a Session ID (sid) or a Subject ID (sub) to correlate the logout event to a specific user session.

The implementation checks (lines 82–84):

• If neither sid nor sub is present, it throws: "either 'sid' or 'sub' (or both) claims must be present"

If present, both claims undergo strict type validation (lines 86–92). Each must be a string; otherwise, a VerifyLogoutTokenError is raised. This prevents malformed tokens from causing runtime errors during session lookup.

Nonce Prohibition

The method explicitly forbids the nonce claim, which is reserved for front-channel authentication flows. If the payload contains a nonce claim, the method throws "'nonce' claim is prohibited" (lines 94–96).

This prohibition ensures that authentication tokens are not mistakenly processed as logout tokens, maintaining a clear security boundary between different OIDC flows.

Events Claim Structure Validation

The final validation step confirms the token represents a legitimate backchannel logout event through the events claim. The method enforces a nested structure (lines 98–114):

1. The events claim must exist
2. It must be an object (not a primitive or array)
3. It must contain the member http://schemas.openid.net/event/backchannel-logout
4. That member must also be an object

This structured claim signals the specific logout event type as mandated by the specification. Once all validations pass, the method returns an object containing { sid, sub } extracted from the payload (lines 118–121), allowing your application to locate and terminate the corresponding session.

Implementation Example

Use the AuthClient directly to verify logout tokens in your application:

import { AuthClient } from '@auth0/auth0-auth-js';

const authClient = new AuthClient({
  domain: 'YOUR_DOMAIN',
  clientId: 'YOUR_CLIENT_ID',
});

// Receive the logout token from Auth0 (e.g., via POST to your backchannel endpoint)
const logoutToken = request.body.logout_token;

try {
  const result = await authClient.verifyLogoutToken({ logoutToken });
  // result: { sid?: string; sub?: string }
  console.log('Valid logout token', result);
  // Use sid or sub to terminate the session
} catch (error) {
  console.error('Invalid logout token', error);
}

For server-side applications, use the Auth0ServerClient which wraps the same validation logic:

import { Auth0ServerClient } from '@auth0/auth0-server-js';

const serverClient = new Auth0ServerClient({
  domain: 'YOUR_DOMAIN',
  clientId: 'YOUR_CLIENT_ID',
});

const result = await serverClient.verifyLogoutToken({ logoutToken });

Summary

• Signature verification uses RS256 algorithm against Auth0's JWKS, validating issuer, audience, and iat claim
• Identifier requirement mandates at least one of sid (Session ID) or sub (Subject ID) as strings
• Security prohibitions explicitly reject tokens containing the nonce claim
• Event validation requires a structured events claim containing the URI http://schemas.openid.net/event/backchannel-logout
• Source locations: Core implementation in packages/auth0-auth-js/src/auth-client.ts, with server-side wrapper in packages/auth0-server-js/src/server-client.ts and comprehensive tests in packages/auth0-auth-js/src/auth-client.spec.ts

Frequently Asked Questions

What specific JWT algorithm does verifyLogoutToken require?

The method strictly requires RS256 (RSA Signature with SHA-256). When calling jwtVerify, it explicitly sets algorithms: ['RS256'] to ensure tokens are signed with Auth0's private RSA key and verifiable using their public JWKS.

Can a valid backchannel logout token contain both sid and sub claims?

Yes. While the specification requires at least one identifier, verifyLogoutToken accepts tokens containing both sid and sub claims simultaneously. The validation logic only throws if neither claim is present, or if either claim exists but is not a string type.

Why does verifyLogoutToken reject tokens containing a nonce claim?

The nonce claim is specific to front-channel authentication flows (like implicit or hybrid flows) to prevent token replay attacks during login. Backchannel logout tokens must never contain nonce because they serve a completely different purpose—securely notifying the RP of logout events via direct back-channel communication rather than through the browser.

What happens if the events claim is malformed or missing?

The method throws a VerifyLogoutTokenError if the events claim is absent, not an object, or missing the required member http://schemas.openid.net/event/backchannel-logout. This member must also be an object (even if empty), ensuring the token strictly conforms to the OIDC Back-Channel Logout specification's event signaling requirements.

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