Auth0 Authentication Provider for react-admin

Common errors

• Error: Invalid state

  cause Using `ra-auth-auth0` versions prior to 2.0.1 in React's Strict Mode.
  fix Upgrade `ra-auth-auth0` to version 2.0.1 or newer.

• TypeError: Cannot read properties of undefined (reading 'push')

  cause The `Auth0AuthProvider` relies on react-router's navigation context, which is missing if `BrowserRouter` is not wrapping the application.
  fix Wrap your `Admin` component, or your entire application, with `<BrowserRouter>` from `react-router-dom`.

• Infinite redirect loop on failures

  cause Misconfiguration of redirect URIs or `checkAuth` logic, potentially related to `redirectOnCheckAuth` setting.
  fix Verify `loginRedirectUri` and `logoutRedirectUri` are correctly set. Ensure `redirectOnCheckAuth` is configured appropriately for your login flow; setting it to `false` requires a custom login page.

• checkAuth should reject when redirectOnCheckAuth is set to false

  cause Older versions of the provider might not correctly reject `checkAuth` when `redirectOnCheckAuth` is explicitly `false`, leading to unexpected behavior with custom login pages.
  fix Upgrade `ra-auth-auth0` to version 1.1.0 or newer to ensure correct `checkAuth` rejection behavior with `redirectOnCheckAuth: false`.

Warnings

• breaking Version 2.0.0 introduced breaking changes by upgrading peer dependencies to `react-admin` v5. Applications using older `react-admin` versions should stick to `ra-auth-auth0` v1.x.
  Fix: Upgrade your `react-admin` package to v5.x or higher, and ensure `@auth0/auth0-spa-js` is at `^2.0.0`.
• breaking In version 2.0.0, internal `react-admin` imports changed from `ra-core` to `react-admin`. If you previously had custom code relying on internal imports, adjust them accordingly.
  Fix: Review any custom implementations that might have used internal `ra-core` imports and update them to use `react-admin` where applicable, or refactor to use public APIs.
• gotcha The `Auth0AuthProvider` requires the application to be wrapped within a `BrowserRouter` component from `react-router-dom` to handle redirects and routing correctly. Missing this will lead to authentication failures.
  Fix: Ensure your root application component, or at least the `Admin` component, is a child of `<BrowserRouter>`.
• gotcha If using React's Strict Mode (e.g., in development), versions prior to 2.0.1 could encounter an 'Invalid state' error during the authentication flow.
  Fix: Upgrade to `ra-auth-auth0` version 2.0.1 or newer to resolve the `React.StrictMode` compatibility issue.
• gotcha To retrieve user roles or custom permissions from Auth0, you must configure Auth0 Actions to include these claims in the authentication token. By default, `ra-auth-auth0` looks for a claim with 'role' in its name, which might not match your Auth0 setup.
  Fix: Configure an Auth0 Action to add roles/permissions to the ID token. If the claim name doesn't match 'role', override the `getPermissions` method in the authProvider configuration to correctly parse your token claims.

Install

• npm install ra-auth-auth0 npm
• yarn add ra-auth-auth0 yarn
• pnpm add ra-auth-auth0 pnpm

Imports

• Auth0AuthProvider
  wrong:

  const Auth0AuthProvider = require('ra-auth-auth0').Auth0AuthProvider;

  correct:

  import { Auth0AuthProvider } from 'ra-auth-auth0';

  This package is primarily consumed as an ESM module. CommonJS require syntax is discouraged and may lead to issues.
• httpClient
  wrong:

  import httpClient from 'ra-auth-auth0/httpClient';

  correct:

  import { httpClient } from 'ra-auth-auth0';

  httpClient is a named export for integrating Auth0 tokens with data providers, not a default export or submodule.
• Auth0Client
  wrong:

  import { Auth0Client } from 'ra-auth-auth0';

  correct:

  import { Auth0Client } from '@auth0/auth0-spa-js';

  Auth0Client is provided by the peer dependency @auth0/auth0-spa-js, not by ra-auth-auth0 itself. It must be imported separately.

Quickstart

This quickstart demonstrates how to set up `ra-auth-auth0` with a basic `react-admin` application, initializing Auth0Client, configuring the authProvider, and integrating the httpClient with a data provider to forward authentication tokens.

import React, { useEffect, useRef, useState } from 'react';
import { Admin, Resource } from 'react-admin';
import { BrowserRouter } from 'react-router-dom';
import { Auth0AuthProvider, httpClient } from 'ra-auth-auth0';
import { Auth0Client } from '@auth0/auth0-spa-js';
import jsonServerProvider from 'ra-data-json-server';

// Environment variables for Auth0 configuration (replace with your actual values or .env)
const VITE_AUTH0_DOMAIN = process.env.VITE_AUTH0_DOMAIN ?? 'your-auth0-domain.auth0.com';
const VITE_AUTH0_CLIENT_ID = process.env.VITE_AUTH0_CLIENT_ID ?? 'your-client-id';
const VITE_AUTH0_AUDIENCE = process.env.VITE_AUTH0_AUDIENCE ?? 'your-api-audience';
const VITE_LOGIN_REDIRECT_URL = process.env.VITE_LOGIN_REDIRECT_URL ?? `${window.location.origin}/auth-callback`;
const VITE_LOGOUT_REDIRECT_URL = process.env.VITE_LOGOUT_REDIRECT_URL ?? window.location.origin;

const auth0Client = new Auth0Client({
    domain: VITE_AUTH0_DOMAIN,
    clientId: VITE_AUTH0_CLIENT_ID,
    cacheLocation: 'localstorage',
    authorizationParams: {
        audience: VITE_AUTH0_AUDIENCE,
        redirect_uri: VITE_LOGIN_REDIRECT_URL,
    },
});

const authProvider = Auth0AuthProvider(auth0Client, {
    loginRedirectUri: VITE_LOGIN_REDIRECT_URL,
    logoutRedirectUri: VITE_LOGOUT_REDIRECT_URL,
});

// Example dataProvider using httpClient to pass Auth0 token
const dataProvider = jsonServerProvider(
    'http://localhost:3000',
    httpClient(auth0Client)
);

const App = () => {
    return (
        <BrowserRouter>
            <Admin authProvider={authProvider} dataProvider={dataProvider}>
                <Resource name="posts" />
            </Admin>
        </BrowserRouter>
    );
};
export default App;