Auth0 React SDK

When using enterprise connections (like Okta) that support id_token_session_expiry_supported: true, Auth0 includes a session_expiry claim in the ID token. This claim is a Unix timestamp (in seconds) representing a hard ceiling for the local session.

SDK Behavior

When the session_expiry timestamp is reached, the SDK updates its state on the next call to getAccessTokenSilently, getUser, or getIdTokenClaims. There is no background timer; the state only updates when these methods are invoked.

Upon reaching the ceiling:

• isAuthenticated becomes false.
• user becomes undefined.
• getAccessTokenSilently() returns undefined (without throwing an error).

Automatic Redirection

If your routes are wrapped with the withAuthenticationRequired Higher-Order Component (HOC), no manual code changes are needed. The next time a component calls getAccessTokenSilently or getUser, the SDK state updates, and the HOC will automatically redirect the user to the login page.

Note: A user sitting on a page that makes no calls to the SDK will remain in an 'authenticated' state in the React context until a call is made.

MFA support is available via the mfa property from the useAuth0() hook. All MFA operations require an mfa_token which is provided in the error payload when an authentication attempt triggers an mfa_required error.

There are two primary flows based on the mfa_requirements object in the error response:

1. Challenge Flow: The user has already enrolled authenticators. You must follow the List Authenticators → Challenge → Verify flow.
2. Enroll Flow: The user needs to set up MFA. You must follow the Enroll → Verify flow.

NOTE

Multi Factor Authentication support via SDKs is currently in Early Access. To request access to this feature, contact your Auth0 representative.

// Example Challenge Flow Response
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26.2*...",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "email" }
    ]
  }
}

// Example Enroll Flow Response
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26.2*...",
  "mfa_requirements": {
    "enroll": [
      { "type": "otp" },
      { "type": "phone" }
    ]
  }
}

Use loginWithCustomTokenExchange to exchange an external subject token for Auth0 tokens. This implements the RFC 8693 token exchange grant type.

Requirements:

• subject_token_type must be a namespaced URI under your organization's control.
• The external token must be validated in Auth0 Actions using strong cryptographic verification.
• This method triggers the GET_ACCESS_TOKEN_COMPLETE action internally, so isLoading and isAuthenticated states in the SDK will behave normally.

Note: The exchangeToken method is deprecated. Use loginWithCustomTokenExchange instead.

import React, { useState } from 'react';
import { useAuth0 } from '@auth0/auth0-react';

const TokenExchange = () => {
  const { loginWithCustomTokenExchange } = useAuth0();
  const [tokens, setTokens] = useState(null);
  const [error, setError] = useState(null);

  const handleExchange = async (externalToken) => {
    try {
      const tokenResponse = await loginWithCustomTokenExchange({
        subject_token: externalToken,
        subject_token_type: 'urn:your-company:legacy-system-token',
        audience: 'https://api.example.com/',
        scope: 'openid profile email',
      });

      setTokens(tokenResponse);
      setError(null);

      console.log('Access Token:', tokenResponse.access_token);
      console.log('ID Token:', tokenResponse.id_token);
    } catch (e) {
      console.error('Token exchange failed:', e);
      setError(e.message);
    }
  };

  return (
    <div>
      <button onClick={() => handleExchange('your-external-token')}>
        Exchange Token
      </button>
      {tokens && <div>Token exchange successful!</div>}
      {error && <div>Error: {error}</div>}
    </div>
  );
};

export default TokenExchange;

If you want to avoid building a custom MFA UI, you can use Step-Up Authentication. When a protected API requires MFA, the SDK can automatically open an Auth0 Universal Login popup. Once the user completes MFA in the popup, the SDK returns the access token transparently to your application.

Requirements:

• useRefreshTokens={true} must be set in Auth0Provider.
• interactiveErrorHandler must be set to "popup".

Warning: This only handles mfa_required errors. Other interactive errors are not intercepted.

Error Handling: If the popup is blocked or cancelled, the SDK throws PopupOpenError, PopupCancelledError, or PopupTimeoutError.

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

function App() {
  return (
    <Auth0Provider
      domain="YOUR_AUTH0_DOMAIN"
      clientId="YOUR_AUTH0_CLIENT_ID"
      authorizationParams={{
        redirect_uri: window.location.origin,
        audience: 'https://api.example.com/',
      }}
      useRefreshTokens={true}
      interactiveErrorHandler="popup"
    >
      <MyApp />
    </Auth0Provider>
  );
}