Ajouter la connexion à votre application React Router

@auth0/auth0-react-router est actuellement en version bêta (1.0.0-beta.2). L’API pourrait changer d’ici la version stable 1.0.

Utiliser l’IA pour intégrer Auth0

Si vous utilisez un assistant de codage IA comme Claude Code, Cursor ou GitHub Copilot, vous pouvez ajouter automatiquement l’authentification Auth0 en quelques minutes grâce aux compétences d’agent.Installation :

npx skills add auth0/agent-skills --skill auth0

Ensuite, demandez à votre assistant IA :

Add Auth0 authentication to my React Router app

Votre assistant IA se chargera automatiquement de créer votre application Auth0, de récupérer les informations d’identification, d’installer @auth0/auth0-react-router, de configurer le fournisseur et de configurer vos routes. Documentation complète sur les compétences d’agent →

Informations requises : Avant de commencer, assurez-vous d’avoir installé les éléments suivants :

Node.js 18 ou version ultérieure (20 LTS recommandée)
npm 9+, yarn 1.22+ ou pnpm 8+
jq – requis pour la configuration avec l’interface de ligne de commande (CLI) d’Auth0
React Router en mode cadre d’applications, v7 ou version ultérieure (fichier react-router.config.ts présent)

Premiers pas

Ce guide de démarrage rapide vous montre comment ajouter l’authentification Auth0 à une application React Router. Vous allez créer une application sécurisée dotée de fonctionnalités de connexion, de déconnexion et de profil utilisateur à l’aide de la trousse SDK Auth0 React Router. La trousse SDK gère le flux OIDC côté serveur et stocke la session dans un témoin chiffré en JWE; les jetons ne se rendent donc jamais jusqu’au navigateur.

Créer un nouveau projet React Router

Créez un nouveau projet React Router pour ce guide de démarrage rapide :

npx create-react-router@latest my-app

Ouvrez le projet :

cd my-app && npm install

Ignorez cette étape si vous ajoutez Auth0 à une application React Router existante.

Installez le SDK Auth0 React Router

npm install @auth0/auth0-react-router

Configurer Auth0

Créez une application Auth0 et définissez les URL de rappel et de déconnexion.

Configuration rapide
CLI
Dashboard

Exécutez la commande suivante à partir du répertoire racine de votre projet pour créer une application Auth0 et générer un fichier .env :

# Installer Auth0 CLI (si ce n’est pas déjà fait)
brew tap auth0/auth0-cli && brew install auth0

# Configurer l’application Auth0 et générer le fichier .env
auth0 qs setup --app --type regular --framework react-router --port 5173 --name "My React Router App"

# Installer Auth0 CLI (si ce n’est pas déjà fait)
scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
scoop install auth0

# Configurer l’application Auth0 et générer le fichier .env
auth0 qs setup --app --type regular --framework react-router --port 5173 --name "My React Router App"

Cette commande crée une application Web standard Auth0 configurée pour http://localhost:5173 et génère un fichier .env contenant toutes les informations d’identification requises. Si vous choisissez cette option, passez l’étape 4.

Accédez à Auth0 Dashboard → Applications > Applications
Cliquez sur Create Application, saisissez un nom et sélectionnez Regular Web Application
Cliquez sur Create
Ouvrez l’onglet Settings (paramètres de l’application)
Remplissez les champs suivants :

Champ	Valeur
Allowed Callback URLs	`http://localhost:5173/auth/callback`
Allowed Logout URLs	`http://localhost:5173`

Cliquez sur Save Changes
Copiez les valeurs Domain et Client ID dans les paramètres de l’application — vous en aurez besoin à l’étape suivante

Configurer les variables d’environnement

Créez un fichier .env à la racine de votre projet :

Variable	Où la trouver
`AUTH0_DOMAIN`	Paramètres de l’application → Domaine
`AUTH0_CLIENT_ID`	Paramètres de l’application → ID client
`AUTH0_CLIENT_SECRET`	Paramètres de l’application → Secret client
`AUTH0_SESSION_SECRET`	Une chaîne aléatoire d’au moins 32 caractères — générée automatiquement dans l’extrait ci-dessus
`AUTH0_APP_BASE_URL`	L’URL de base de votre application — `http://localhost:5173` pour le développement local

Ne validez jamais le fichier .env dans votre système de gestion de versions. Ajoutez-le à .gitignore avant votre première validation.

Créer l’instance du serveur Auth0

Créez app/auth0.server.ts. Le suffixe .server.ts indique au bundler de React Router d’exclure ce fichier du paquet client, afin que vos secrets restent uniquement côté serveur.

app/auth0.server.ts

import { Auth0Server, registerAuth0Instance } from '@auth0/auth0-react-router/server';

export const auth0 = new Auth0Server();
registerAuth0Instance(auth0);

Ajouter les routes d’authentification

Créez une route générique (splat) qui prend en charge tous les chemins /auth/*. handleAuth achemine en interne les requêtes vers handleLogin, handleCallback, handleLogout et handleBackchannelLogout selon le chemin de l’URL et la méthode HTTP.

app/routes/auth.$.tsx

import { handleAuth } from '@auth0/auth0-react-router/server';
import { auth0 } from '../auth0.server';

export const loader = ({ request }: { request: Request }) =>
  handleAuth(auth0, request);

export const action = ({ request }: { request: Request }) =>
  handleAuth(auth0, request);

Enregistrez la route dans votre configuration de routes :

app/routes.ts

import { type RouteConfig, route } from '@react-router/dev/routes';

export default [
  route('auth/*', 'routes/auth.$.tsx'),
  // ... vos autres routes
] satisfies RouteConfig;

Configurer la mise en page racine

Ajoutez Auth0Provider et rootAuthLoader à app/root.tsx. rootAuthLoader déchiffre le témoin de session et transmet l’état d’authentification au fournisseur — aucun jeton n’est envoyé au navigateur.

app/root.tsx

import { Links, Meta, Outlet, Scripts, ScrollRestoration } from 'react-router';
import { Auth0Provider } from '@auth0/auth0-react-router';
import { rootAuthLoader } from '@auth0/auth0-react-router/server';
import type { Route } from './+types/root';

export const loader = ({ request }: Route.LoaderArgs) =>
  rootAuthLoader(request);

export default function Root() {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        <Auth0Provider>
          <Outlet />
        </Auth0Provider>
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

Auth0Provider lit les données de session à partir de useRouteLoaderData('root'); la route racine doit donc avoir l’identifiant root. Avec le routage basé sur les fichiers, React Router définit automatiquement cet identifiant à partir du nom du fichier. Avec une configuration de routes personnalisée, transmettez { id: 'root' } à l’appel layout().

Ajouter la connexion et la déconnexion

Utilisez les composants intégrés pour afficher les boutons de connexion et de déconnexion. LoginButton redirige vers /auth/login et LogoutButton redirige vers /auth/logout. Auth0 gère le flux OIDC, puis redirige l’utilisateur vers votre application une fois la connexion effectuée.

app/routes/_index.tsx

import {
  AuthLoading,
  LoginButton,
  LogoutButton,
  SignedIn,
  SignedOut,
} from '@auth0/auth0-react-router';

export default function Home() {
  return (
    <main>
      <h1>Welcome</h1>
      <AuthLoading>
        <p>Loading…</p>
      </AuthLoading>
      <SignedOut>
        <LoginButton>Log in</LoginButton>
      </SignedOut>
      <SignedIn>
        <LogoutButton>Log out</LogoutButton>
      </SignedIn>
    </main>
  );
}

Afficher le profil utilisateur

Utilisez le hook useUser pour accéder au profil de l’utilisateur authentifié dans n’importe quel composant client. Combinez-le avec requireSession dans le loader pour bloquer les requêtes non authentifiées directement sur le serveur, avant même le rendu de la page.

app/routes/profile.tsx

import { useUser } from '@auth0/auth0-react-router';
import { requireSession } from '@auth0/auth0-react-router/server';
import type { Route } from './+types/profile';

export const loader = async ({ request }: Route.LoaderArgs) => {
  await requireSession(request);
  return null;
};

export default function Profile() {
  const user = useUser();

  return (
    <main>
      <h1>Profile</h1>
      {user && (
        <div>
          <img src={user.picture} alt={user.name ?? ''} width={80} height={80} />
          <p><strong>{user.name}</strong></p>
          <p>{user.email}</p>
        </div>
      )}
    </main>
  );
}

Exécutez votre application

npm run dev

Ouvrez http://localhost:5173 dans votre navigateur et cliquez sur Log in. Vous serez redirigé vers la page de connexion universelle d’Auth0. Une fois connecté, vous serez redirigé vers votre application.

La connexion et la déconnexion fonctionnent maintenant dans votre application. La session est stockée dans un témoin chiffré en JWE — les jetons d’accès restent sur le serveur et ne sont jamais transmis au navigateur.

Dépannage

JWEDecryptionFailed — impossible de déchiffrer le témoin de session

Cause : AUTH0_SESSION_SECRET a été modifié après l’émission d’un témoin de session, ou la valeur compte moins de 32 caractères.Solution : Effacez les témoins de votre navigateur pour localhost, assurez-vous que AUTH0_SESSION_SECRET compte au moins 32 caractères, puis redémarrez le serveur de développement. Pour générer un nouveau secret : openssl rand -hex 32.

URL de rappel non concordante — Auth0 renvoie une erreur après la connexion

Cause : L’URL de redirection reçue par Auth0 ne correspond à aucune des valeurs définies dans les URL de rappel autorisées (Allowed Callback URLs).Solution : Dans Auth0 Dashboard → Applications > Applications → sélectionnez votre application → Application Settings, assurez-vous que Allowed Callback URLs est défini à http://localhost:5173/auth/callback. Supprimez toute barre oblique finale ou tout espace superflu, puis cliquez sur Save Changes.

useUser renvoie null après la connexion

Cause : rootAuthLoader n’est pas exporté depuis app/root.tsx, ou la route racine n’a pas l’identifiant root.Solution : Assurez-vous que app/root.tsx exporte export const loader = ({ request }) => rootAuthLoader(request). Si vous utilisez une configuration de routes personnalisée, enregistrez la mise en page racine comme suit : layout('root.tsx', { id: 'root' }, [...routes]).

TypeError sur context.get — le logiciel médiateur ne fonctionne pas

Cause : defineRouteAuth et auth0Middleware nécessitent React Router 7.9.0 ou une version ultérieure, puisque c’est cette version qui a introduit l’API de logiciel médiateur.Solution : Mettez à niveau react-router vers >=7.9.0, ou protégez plutôt chaque route individuellement à l’aide de requireSession / requireUser dans chaque chargeur.

Utilisation avancée

Appeler une API côté serveur avec un jeton d'accès

Ajoutez AUTH0_AUDIENCE au fichier .env avec l’identifiant de votre API (disponible dans Auth0 Dashboard → Applications > APIs → API Settings → Identifier). Utilisez ensuite getAccessToken dans un chargeur (loader) — le jeton n’est jamais transmis au navigateur :

app/routes/data.tsx

import { getAccessToken } from '@auth0/auth0-react-router/server';
import { TokenError } from '@auth0/auth0-react-router/errors';

export const loader = async ({ request }) => {
  let token: string;
  try {
    token = await getAccessToken(request);
  } catch (err) {
    if (err instanceof TokenError) {
      return new Response(null, { status: 302, headers: { Location: '/auth/login' } });
    }
    throw err;
  }
  const data = await fetch('https://api.example.com/items', {
    headers: { Authorization: `Bearer ${token}` },
  }).then(r => r.json());
  return { data };
};

Protection des routes en fonction des rôles

Utilisez le logiciel médiateur defineRouteAuth (React Router ≥ 7.9.0) pour imposer des rôles au niveau des routes. Par défaut, les rôles sont lus à partir de la demande personnalisée https://auth0.com/claims/roles :

app/routes/admin.tsx

import { defineRouteHandle } from '@auth0/auth0-react-router';
import { defineRouteAuth, auth0UserContext } from '@auth0/auth0-react-router/server';

export const handle = defineRouteHandle({ role: 'admin' });

export const middleware = defineRouteAuth({ role: 'admin' }).middleware;

export const loader = ({ context }) => {
  const user = context.get(auth0UserContext);
  return { user };
};

Les requêtes qui n’ont pas le rôle requis reçoivent une réponse 403.

Mode SPA (PKCE côté client)

La trousse SDK peut fonctionner entièrement côté client grâce à @auth0/auth0-spa-js. Ajoutez VITE_AUTH0_DOMAIN et VITE_AUTH0_CLIENT_ID à votre fichier .env — Auth0Provider détecte automatiquement ces variables et bascule vers le flux PKCE. Aucune autre modification du code n’est requise.

# Ajouts au fichier .env pour le mode SPA
VITE_AUTH0_DOMAIN={yourDomain}
VITE_AUTH0_CLIENT_ID={yourClientId}

Ne définissez pas les variables AUTH0_* et VITE_AUTH0_* simultanément. Le mode hybride n’est pas pris en charge — si les deux sont présentes, la déconnexion en mode SPA n’effacera pas le témoin de session côté serveur.

Guides de démarrage rapide

Présentation d’Auth0

Configurer Auth0

Applications

Ajouter la connexion à votre application React Router

Premiers pas

Dépannage

Utilisation avancée

​Premiers pas

​Dépannage

​Utilisation avancée

Premiers pas

Dépannage

Utilisation avancée