Ajouter la connexion à votre application Next.js

Ce guide montre comment intégrer Auth0 à toute nouvelle application Next.js ou à une application existante à l’aide du SDK Auth0 Next.js v4.

Utilisez l’IA pour intégrer Auth0

Si vous utilisez un assistant IA de programmation comme Claude Code, Cursor ou GitHub Copilot, vous pouvez ajouter l’authentification Auth0 automatiquement en quelques minutes à l’aide d’Agent Skills.

Installation :

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

Ensuite, demandez à votre assistant IA :

Add Auth0 authentication to my Next.js app

Votre assistant IA créera automatiquement votre application Auth0, récupérera les identifiants, installera @auth0/nextjs-auth0, créera des routes d’API et configurera les variables d’environnement. Documentation complète sur Agent Skills →

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

• Node.js 20 LTS ou une version ultérieure
• npm 10+ ou yarn 1.22+ ou pnpm 8+

Vérifiez l’installation : node --version && npm --version

​

Pour commencer

Ce guide de démarrage rapide montre comment ajouter l’authentification Auth0 à une application Next.js 16. Vous créerez une application web full stack avec rendu côté serveur, une fonctionnalité de connexion sécurisée et des routes protégées à l’aide du SDK Auth0 Next.js.

1. Créer un nouveau projet

   Créez un nouveau projet Next.js pour ce Quickstart

   npx create-next-app@latest auth0-nextjs --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --yes
   

   Ouvrir le projet

   cd auth0-nextjs
   
2. Installer le SDK Auth0 Next.js

   shellscript npm install @auth0/nextjs-auth0

3. Créer les fichiers du projet

   Créez tous les répertoires et fichiers nécessaires à l’intégration d’Auth0 :

   Mac/Linux

   mkdir -p src/lib src/components && touch src/lib/auth0.ts src/proxy.ts src/components/LoginButton.tsx src/components/LogoutButton.tsx src/components/Profile.tsx
   
4. Configurez votre Auth0 App

   Ensuite, vous devez créer une nouvelle application sur votre tenant Auth0 et ajouter les variables d’environnement à votre projet.

   Vous avez trois options pour configurer votre application Auth0 : utiliser l’outil Quick Setup (recommandé), exécuter une commande CLI, ou configurer manuellement via le Dashboard :

   Configuration rapide (recommandée)

   Créez une Auth0 App et copiez le fichier .env prérempli avec les bonnes valeurs de configuration.

   CLI

   Exécutez la commande suivante dans le répertoire racine de votre projet pour créer une Auth0 App et générer un fichier .env :

   Mac

   # Installez Auth0 CLI (si ce n’est pas déjà fait)
   brew tap auth0/auth0-cli && brew install auth0
   
   # Configurez l’Auth0 App et générez le fichier .env
   auth0 qs setup --app --type regular --framework nextjs --name "My App" --port 3000
   

   Cette commande permet de :

   1. Vérifier si vous êtes authentifié(e) (et demander de vous connecter au besoin)
   2. Créer une Auth0 Regular Web Application configurée pour http://localhost:3000
   3. Générer un fichier .env contenant AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_SECRET et APP_BASE_URL

   Dashboard

   Créez un fichier .env.local dans le répertoire racine de votre projet :

   .env.local

   AUTH0_DOMAIN=YOUR_AUTH0_APP_DOMAIN
   AUTH0_CLIENT_ID=YOUR_AUTH0_APP_CLIENT_ID
   AUTH0_CLIENT_SECRET=YOUR_AUTH0_APP_CLIENT_SECRET
   AUTH0_SECRET=YOUR_LONG_RANDOM_SECRET_HERE
   APP_BASE_URL=http://localhost:3000
   

   Générez une valeur AUTH0_SECRET sécurisée :

   openssl rand -hex 32
   

   Copiez le résultat et remplacez YOUR_LONG_RANDOM_SECRET_HERE dans .env.local. Cette valeur doit contenir exactement 64 caractères hexadécimaux.

   Configurez ensuite votre application Auth0 :

   1. Accédez au Auth0 Dashboard
   2. Cliquez sur Applications > Applications > Create Application
   3. Dans la fenêtre contextuelle, entrez un nom pour votre application, sélectionnez Regular Web Application comme type d’application, puis cliquez sur Create
   4. Ouvrez l’onglet Settings sur la page Application Details
   5. Remplacez YOUR_AUTH0_APP_DOMAIN, YOUR_AUTH0_APP_CLIENT_ID et YOUR_AUTH0_APP_CLIENT_SECRET dans le fichier .env.local par les valeurs Domain, Client ID et Client Secret du Dashboard

   Critique : Si vous modifiez AUTH0_SECRET après le démarrage de l’application, vous devez supprimer les cookies de votre navigateur pour localhost. Les anciens session cookies chiffrés avec le secret précédent provoqueront une erreur JWEDecryptionFailed.

   Enfin, dans l’onglet Settings de la page Application Details, configurez les URL suivantes :

   Allowed Callback URLs:

   http://localhost:3000/auth/callback
   

   Allowed Logout URLs:

   http://localhost:3000
   

   Allowed Web Origins:

   http://localhost:3000
   

   Allowed Callback URLs constitue une mesure de sécurité essentielle pour s’assurer que les utilisateurs sont redirigés de façon sécuritaire vers votre application après l’authentication. Sans URL correspondante, le login process échouera et les utilisateurs verront une page d’erreur Auth0 au lieu d’accéder à votre application.

   Allowed Logout URLs est essentiel pour offrir une user experience fluide lors de la déconnexion. Sans URL correspondante, les utilisateurs ne seront pas redirigés vers votre application après le logout et resteront plutôt sur une page Auth0 générique.

   Allowed Web Origins est essentiel pour la silent authentication. Sans cela, les utilisateurs seront déconnectés lorsqu’ils actualiseront la page ou reviendront plus tard dans votre application.

5. Créer la configuration d’Auth0

   Ajoutez le code du client Auth0 dans src/lib/auth0.ts :

   src/lib/auth0.ts

   import { Auth0Client } from '@auth0/nextjs-auth0/server';
   
   export const auth0 = new Auth0Client();
   
6. Ajouter un proxy

   Ajoutez le code du proxy dans src/proxy.ts :

   src/proxy.ts

   import { auth0 } from "./lib/auth0";
   
   export async function proxy(request: Request) {
     return await auth0.middleware(request);
   }
   
   export const config = {
     matcher: [
       /*
        * Correspond à tous les chemins de requête sauf ceux commençant par :
        * - _next/static (fichiers statiques)
        * - _next/image (fichiers d'optimisation d'images)
        * - favicon.ico, sitemap.xml, robots.txt (fichiers de métadonnées)
        */
       "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
     ],
   };
   

   Comme nous utilisons un répertoire src/, le fichier proxy.ts est créé dans src/. Si vous n’utilisez pas de répertoire src/, créez-le plutôt à la racine du projet.

   Ce proxy configure automatiquement les routes d’authentification suivantes :

   • /auth/login - Route de connexion
   • /auth/logout - Route de déconnexion
   • /auth/callback - Route de rappel
   • /auth/profile - Route du profil utilisateur
   • /auth/access-token - Route du jeton d’accès
   • /auth/backchannel-logout - Route de déconnexion par canal arrière
7. Créer des composants de connexion, de déconnexion et de profil

   Ajoutez le code des composants aux fichiers créés à l’étape 3 :

8. Mettez à jour votre page d’accueil

   Remplacez src/app/page.tsx par :

   src/app/page.tsx

   import { auth0 } from "@/lib/auth0";
   import LoginButton from "@/components/LoginButton";
   import LogoutButton from "@/components/LogoutButton";
   import Profile from "@/components/Profile";
   
   export default async function Home() {
     const session = await auth0.getSession();
     const user = session?.user;
   
     return (
       <main className="min-h-screen bg-[#efefef] flex flex-col items-center justify-center gap-4 px-6 py-12">
         <div className="bg-white rounded-[28px] shadow-[0_4px_32px_rgba(0,0,0,0.08)] px-12 py-14 flex flex-col items-center gap-4 w-[360px]">
           <svg width="68" height="68" viewBox="0 0 68 68" fill="none" xmlns="http://www.w3.org/2000/svg" className="mb-1">
             <g filter="url(#filter0_di)">
               <rect x="2" y="2" width="64" height="64" rx="16" fill="url(#paint0_linear)"/>
               <rect x="2.5" y="2.5" width="63" height="63" rx="15.5" stroke="#252525"/>
               <path d="M34.0002 18C25.1572 18 18 25.1669 18 34C18 42.8432 25.1672 50 34.0002 50C42.8333 50 50 42.8331 50 34C50 25.1669 42.8433 18 34.0002 18ZM43.9172 43.8971C43.9172 43.9071 43.9069 43.9072 43.9069 43.9172C43.9069 43.9172 43.8969 43.9272 43.8868 43.9272C43.144 44.65 41.9796 44.7303 41.0662 44.2585L40.0228 43.7265C36.2487 41.7792 31.7619 41.7792 27.9777 43.7265L26.9338 44.2585C26.0103 44.7303 24.8459 44.65 24.1132 43.9272C24.1132 43.9272 24.1031 43.9172 24.0931 43.9172C24.0931 43.9172 24.0828 43.9071 24.0828 43.8971C23.3601 43.1543 23.2797 41.9899 23.7515 41.0765L24.2837 40.0326C26.231 36.2585 26.231 31.7717 24.2837 27.9975L23.7515 26.9536C23.2797 26.0302 23.3601 24.8657 24.0828 24.133C24.0828 24.1229 24.0931 24.123 24.0931 24.123C24.0931 24.123 24.1031 24.1129 24.1132 24.1129C24.856 23.3902 26.0204 23.3099 26.9338 23.7817L27.9777 24.3137C31.7518 26.261 36.2386 26.261 40.0228 24.3137L41.0662 23.7817C41.9897 23.3099 43.1541 23.3902 43.8868 24.1129C43.8868 24.1129 43.8969 24.123 43.9069 24.123L43.9172 24.133C44.6399 24.8758 44.7203 26.0402 44.2485 26.9536L43.7163 27.9975C41.769 31.7717 41.769 36.2585 43.7163 40.0326L44.2485 41.0765C44.7203 41.9899 44.6499 43.1543 43.9172 43.8971Z" fill="white"/>
             </g>
             <defs>
               <filter id="filter0_di" x="0" y="0" width="68" height="68" filterUnits="userSpaceOnUse" colorInterpolationFilters="sRGB">
                 <feFlood floodOpacity="0" result="BackgroundImageFix"/>
                 <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
                 <feMorphology radius="2" operator="dilate" in="SourceAlpha" result="effect1_dropShadow"/>
                 <feOffset/>
                 <feComposite in2="hardAlpha" operator="out"/>
                 <feColorMatrix type="matrix" values="0 0 0 0 0.117647 0 0 0 0 0.129412 0 0 0 0 0.164706 0 0 0 0.12 0"/>
                 <feBlend mode="normal" in2="BackgroundImageFix" result="effect1_dropShadow"/>
                 <feBlend mode="normal" in="SourceGraphic" in2="effect1_dropShadow" result="shape"/>
                 <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
                 <feOffset dy="-1"/>
                 <feGaussianBlur stdDeviation="0.5"/>
                 <feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1"/>
                 <feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.04 0"/>
                 <feBlend mode="normal" in2="shape" result="effect2_innerShadow"/>
               </filter>
               <linearGradient id="paint0_linear" x1="34" y1="2" x2="34" y2="66" gradientUnits="userSpaceOnUse">
                 <stop/>
                 <stop offset="1" stopColor="#677190"/>
               </linearGradient>
             </defs>
           </svg>
   
           {user ? (
             <>
               <h1 className="text-[17px] font-bold text-gray-900 tracking-tight">Your account</h1>
               <div className="w-full h-px bg-gray-100" />
               <Profile />
               <LogoutButton />
             </>
           ) : (
             <>
               <h1 className="text-[17px] font-bold text-gray-900 tracking-tight">Welcome to Sample0</h1>
               <p className="text-[13px] text-gray-400 text-center leading-relaxed -mt-2">
                 Get started by logging in to your account
               </p>
               <div className="h-3" />
               <LoginButton />
             </>
           )}
         </div>
   
         <div className="flex items-center gap-1.5 text-[11px] text-gray-400">
           <span>Powered by</span>
           <img
             src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-onlight.svg"
             alt="Auth0"
             className="h-3 opacity-40"
           />
         </div>
       </main>
     );
   }
   
9. Mettre à jour le layout avec Auth0Provider

   Mettez à jour src/app/layout.tsx pour charger la police Inter et entourer votre application de Auth0Provider :

   src/app/layout.tsx

   import { Inter } from "next/font/google";
   import type { Metadata } from "next";
   import { Auth0Provider } from "@auth0/nextjs-auth0/client";
   import "./globals.css";
   
   const inter = Inter({
     subsets: ["latin"],
     weight: ["300", "400", "500", "600", "700"],
   });
   
   export const metadata: Metadata = {
     title: "Auth0 Next.js App",
     description: "Next.js app with Auth0 authentication",
   };
   
   export default function RootLayout({
     children,
   }: {
     children: React.ReactNode;
   }) {
     return (
       <html lang="en">
         <body className={inter.className}>
           <Auth0Provider>{children}</Auth0Provider>
         </body>
       </html>
     );
   }
   

   Dans la version 4, le Auth0Provider est facultatif. Vous en avez besoin uniquement si vous voulez transmettre un utilisateur initial lors du rendu côté serveur afin qu’il soit accessible dans le hook useUser().

10. Configurer Tailwind CSS

    Remplacez le contenu de src/app/globals.css par :

    src/app/globals.css

    @import "tailwindcss";
    
11. Lancez votre application

    npm run dev
    

    Votre application sera accessible à l’adresse http://localhost:3000. L’Auth0 SDK v4 configure automatiquement les routes d’authentification sous /auth/* (et non /api/auth/* comme dans la v3).

    Si le port 3000 est déjà utilisé, exécutez : npm run dev -- --port 3001 et mettez à jour les URL de rappel de votre application Auth0 vers http://localhost:3001

Vérification

Vous devriez maintenant disposer d’une page de connexion Auth0 entièrement fonctionnelle sur votre localhost

---

​

Dépannage

JWEDecryptionFailed Error

Si vous voyez l’erreur JWEDecryptionFailed: decryption operation failed, c’est qu’il y a soit un AUTH0_SECRET invalide, soit un ancien cookie de session chiffré avec un secret différent.

Solution :

1. Générez un nouveau secret avec :

openssl rand -hex 32

2. Mettez à jour votre fichier .env.local :

AUTH0_SECRET=<your-new-64-character-hex-string>

3. Effacez les cookies de votre navigateur pour localhost:3000 :

   • Chrome/Edge : Appuyez sur F12 → onglet Application → Cookies → Supprimez tous les cookies pour localhost
   • Firefox : Appuyez sur F12 → onglet Storage → Cookies → Supprimez tous les cookies pour localhost
   • Safari : menu Develop → Show Web Inspector → onglet Storage → Cookies → Delete all

4. Redémarrez votre serveur de développement :

npm run dev

Le secret doit contenir exactement 32 octets (64 caractères hexadécimaux). L’erreur se produit lorsque l’application essaie de déchiffrer un cookie de session existant qui a été chiffré avec un secret différent.

Erreur 404 sur /auth/login

Si le fait de cliquer sur login vous mène à une page 404, vérifiez ces problèmes courants :

1. Emplacement du proxy : Assurez-vous que src/proxy.ts se trouve au bon endroit
2. Code du proxy : Vérifiez que le proxy correspond au code de l’étape 6
3. Redémarrer le serveur : Après avoir créé le fichier proxy, redémarrez le serveur de développement
4. Vérifier les importations : Assurez-vous que le chemin import { auth0 } from "./lib/auth0" est correct

Erreurs Module Not Found

Si vous voyez l’erreur “Cannot find module ’@/components/LoginButton’” ou une erreur semblable :

1. Vérifiez que les fichiers existent : Assurez-vous que tous les fichiers de l’étape 3 ont bien été créés
2. Vérifiez les chemins : Assurez-vous que les composants se trouvent dans le répertoire src/components/
3. Redémarrer TypeScript : Appuyez sur Cmd+Shift+P (Mac) ou Ctrl+Shift+P (Windows), puis exécutez “TypeScript: Restart TS Server”
4. Vérifier les importations : Assurez-vous d’utiliser @/components/* (et non ~/components/*)

---

​

Utilisation avancée

Changements importants de la v4

Ce guide de démarrage rapide utilise Auth0 Next.js SDK v4, qui apporte des changements importants par rapport à la v3 :

• Aucun handler de route dynamique n’est requis - Les routes d’authentification sont montées automatiquement par le proxy
• Configuration simplifiée du client - new Auth0Client() lit automatiquement les variables d’environnement
• Nouveaux chemins de routes - Les routes sont sous /auth/* plutôt que /api/auth/*
• Proxy requis - Toutes les fonctionnalités d’authentification passent par proxy.ts
• Utilisez des balises <a> - La navigation doit se faire avec <a href="/auth/login"> plutôt qu’avec des boutons utilisant onClick

​

Routes d’authentification

Le SDK monte automatiquement ces routes par l’intermédiaire du proxy :

Route	But
/auth/login	Lancer la connexion
/auth/logout	Déconnecter l’utilisateur
/auth/callback	Traiter le callback Auth0
/auth/profile	Obtenir le profil utilisateur
/auth/access-token	Obtenir le jeton d’accès
/auth/backchannel-logout	Gérer la déconnexion backchannel

Si vous obtenez des erreurs 404 sur ces routes, assurez-vous que :

1. Le fichier proxy.ts est au bon endroit (à la racine du projet, ou dans src/ si vous utilisez un répertoire src/)
2. Le proxy est correctement configuré avec le motif matcher indiqué à l’étape 6
3. Le serveur de développement a bien été redémarré après la création du fichier proxy

Authentification côté serveur

Auth0 Next.js SDK v4 prend en charge les modèles App Router et Pages Router. Voici quelques modèles courants côté serveur :

App Router - composant serveur

app/protected/page.tsx

import { auth0 } from "@/lib/auth0";
import { redirect } from "next/navigation";

export default async function ProtectedPage() {
  const session = await auth0.getSession();

  if (!session) {
    redirect('/auth/login');
  }

  return (
    <div>
      <h1>Protected Content</h1>
      <p>Welcome, {session.user.name}!</p>
    </div>
  );
}

App Router - route d’API

app/api/protected/route.ts

import { auth0 } from "@/lib/auth0";
import { NextResponse } from "next/server";

export async function GET() {
  const session = await auth0.getSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  return NextResponse.json({
    message: "This is a protected API route",
    user: session.user
  });
}

Pages Router - page

pages/protected.tsx

import { auth0 } from "@/lib/auth0";
import { GetServerSideProps } from "next";

export default function ProtectedPage({ user }: { user: any }) {
  return (
    <div>
      <h1>Protected Content</h1>
      <p>Welcome, {user.name}!</p>
    </div>
  );
}

export const getServerSideProps: GetServerSideProps = auth0.withPageAuthRequired();

Authentification côté client

Pour gérer l’état d’authentification côté client, utilisez le hook useUser :

components/UserProfile.tsx

"use client";

import { useUser } from "@auth0/nextjs-auth0/client";

export default function UserProfile() {
  const { user, error, isLoading } = useUser();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!user) return <div>Not logged in</div>;

  return (
    <div>
      <h2>{user.name}</h2>
      <p>{user.email}</p>
      <img src={user.picture} alt="Profile" referrerPolicy="no-referrer" />
    </div>
  );
}

Protection des routes d’API

Pour protéger une route d’API, utilisez la méthode withApiAuthRequired :

app/api/protected/route.ts

import { auth0 } from "@/lib/auth0";

export const GET = auth0.withApiAuthRequired(async function handler() {
  const session = await auth0.getSession();

  return Response.json({
    message: "This is a protected API route",
    user: session?.user
  });
});

Utiliser des jetons Auth0 avec des backends tiers

Si vous utilisez un service backend tiers (comme Convex, Supabase ou Firebase) qui exige des jetons d’authentification Auth0, vous devrez transmettre le jeton d’accès de votre application Next.js au client backend.

​

Obtenir le jeton d’accès

Côté serveur (App Router) :

app/api/token/route.ts

import { auth0 } from "@/lib/auth0";
import { NextResponse } from "next/server";

export async function GET() {
  const session = await auth0.getSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const accessToken = session.accessToken;
  return NextResponse.json({ accessToken });
}

Côté client :

lib/convex-client.ts

"use client";

import { ConvexProviderWithAuth0 } from "convex/react-auth0";
import { ConvexReactClient } from "convex/react";

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export function ConvexClientProvider({ children }: { children: React.ReactNode }) {
  return (
    <ConvexProviderWithAuth0
      client={convex}
      useAuth0={() => ({
        // Récupérez le jeton d’accès depuis votre route d’API Next.js
        getAccessToken: async () => {
          const response = await fetch("/api/token");
          const { accessToken } = await response.json();
          return accessToken;
        },
      })}
    >
      {children}
    </ConvexProviderWithAuth0>
  );
}

​

Configurer votre backend

La plupart des services tiers ont besoin de votre domaine Auth0 et de votre audience pour valider les jetons. Dans la configuration de votre backend :

convex/auth.config.ts

export default {
  providers: [
    {
      domain: process.env.AUTH0_DOMAIN,
      applicationID: process.env.AUTH0_CLIENT_ID,
    },
  ],
};

Assurez-vous que votre application Auth0 est configurée avec une audience d’API si votre backend l’exige. Vous pouvez la définir dans le Auth0 Dashboard sous Applications → APIs, ou ajouter AUTH0_AUDIENCE à votre .env.local et configurer le SDK en conséquence.

​

Résolution des problèmes liés aux jetons

Si ctx.auth.getUserIdentity() renvoie null dans votre backend :

1. Vérifiez que le jeton est bien transmis : consultez l’onglet Network des DevTools de votre navigateur pour confirmer que le jeton est inclus dans les requêtes
2. Vérifiez le format du jeton : assurez-vous de transmettre le accessToken, et non le idToken
3. Vérifiez la configuration du backend : confirmez que votre backend utilise le bon domaine Auth0 et le bon ID client
4. Vérifiez l’audience : si vous utilisez l’API Auth0, assurez-vous que AUTH0_AUDIENCE est défini et correspond à votre identifiant d’API
5. Inspectez les claims du jeton : décodez votre JWT sur jwt.io pour vérifier qu’il contient les claims attendus