> ## Documentation Index > Fetch the complete documentation index at: https://auth0.com/llms.txt > Use this file to discover all available pages before exploring further. # Ajouter la connexion à votre application React Router > Ce guide explique comment intégrer Auth0 à une application React Router (mode cadre d'applications, version 7 ou ultérieure) à l'aide de la trousse SDK Auth0 React Router. > [!WARNING] > > `@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](https://agentskills.io/home). > > **Installation :** > > ```bash theme={null} > npx skills add auth0/agent-skills --skill auth0 > ``` > > **Ensuite, demandez à votre assistant IA :** > > ```text theme={null} > 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 →](https://auth0.com/docs/fr-ca/quickstart/agent-skills.md) **Informations requises :** Avant de commencer, assurez-vous d’avoir installé les éléments suivants : * **[Node.js](https://nodejs.org/en/download)** 18 ou version ultérieure (20 LTS recommandée) * **[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)** 9+, **[yarn](https://classic.yarnpkg.com/lang/en/docs/install/)** 1.22+ ou **[pnpm](https://pnpm.io/installation)** 8+ * **[jq](https://jqlang.org/)** – 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. **1. Créer un nouveau projet React Router** Créez un nouveau projet React Router pour ce guide de démarrage rapide : ```shellscript theme={null} npx create-react-router@latest my-app ``` Ouvrez le projet : ```shellscript theme={null} cd my-app && npm install ``` > [!NOTE] > > Ignorez cette étape si vous ajoutez Auth0 à une application React Router existante. **2. Installez le SDK Auth0 React Router** ```shellscript theme={null} npm install @auth0/auth0-react-router ``` **3. Configurer Auth0** Créez une application Auth0 et définissez les URL de rappel et de déconnexion. **Configuration rapide** **CLI** 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` : ```shellscript Mac theme={null} # 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" ``` ```powershell Windows theme={null} # 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" ``` > [!NOTE] > > 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. **Dashboard** 1. Accédez à [Auth0 Dashboard](https://manage.auth0.com/) → **Applications > Applications** 2. Cliquez sur **Create Application**, saisissez un nom et sélectionnez **Regular Web Application** 3. Cliquez sur **Create** 4. Ouvrez l’onglet **Settings** (paramètres de l’application) 5. Remplissez les champs suivants : | Champ | Valeur | | - | - | | Allowed Callback URLs | `http://localhost:5173/auth/callback` | | Allowed Logout URLs | `http://localhost:5173` | 6. Cliquez sur **Save Changes** 7. Copiez les valeurs **Domain** et **Client ID** dans les paramètres de l’application — vous en aurez besoin à l’étape suivante **4. 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 | > [!WARNING] > > Ne validez jamais le fichier `.env` dans votre système de gestion de versions. Ajoutez-le à `.gitignore` avant votre première validation. **5. 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. ```ts app/auth0.server.ts theme={null} import { Auth0Server, registerAuth0Instance } from '@auth0/auth0-react-router/server'; export const auth0 = new Auth0Server(); registerAuth0Instance(auth0); ``` **6. 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. ```tsx app/routes/auth.$.tsx theme={null} 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 : ```ts app/routes.ts theme={null} import { type RouteConfig, route } from '@react-router/dev/routes'; export default [ route('auth/*', 'routes/auth.$.tsx'), // ... vos autres routes ] satisfies RouteConfig; ``` **7. 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. ```tsx app/root.tsx expandable theme={null} 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 ( ); } ``` > [!NOTE] > > `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()`. **8. 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. ```tsx app/routes/_index.tsx theme={null} import { AuthLoading, LoginButton, LogoutButton, SignedIn, SignedOut, } from '@auth0/auth0-react-router'; export default function Home() { return (

Welcome

Loading…

 Log in Log out
); } ``` **9. 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. ```tsx app/routes/profile.tsx theme={null} 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 (

Profile

{user && (
{user.name

{user.name}

{user.email}

)}
); } ``` **10. Exécutez votre application** ```shellscript theme={null} 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. > [!TIP] > > 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](https://manage.auth0.com/) → **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**. > **Erreur 404 sur /auth/login — route introuvable** > > **Cause :** La route générique `auth.$.tsx` est absente ou n’est pas enregistrée dans `routes.ts`. > > **Solution :** Assurez-vous que `app/routes/auth.$.tsx` existe et que `app/routes.ts` inclut `route('auth/*', 'routes/auth.$.tsx')`. Redémarrez le serveur de développement après avoir modifié `routes.ts`. > **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](https://manage.auth0.com/) → **Applications > APIs** → **API Settings → Identifier**). Utilisez ensuite `getAccessToken` dans un chargeur (loader) — le jeton n'est jamais transmis au navigateur : > > ```ts app/routes/data.tsx theme={null} > 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` : > > ```ts app/routes/admin.tsx theme={null} > 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. > > ```shellscript theme={null} > # Ajouts au fichier .env pour le mode SPA > VITE_AUTH0_DOMAIN={yourDomain} > VITE_AUTH0_CLIENT_ID={yourClientId} > ``` > > > [!WARNING] > > > > 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.