Intégration Auth0 avec Next.js

Ajoutez l'authentification à vos applications Next.js en utilisant @auth0/nextjs-auth0. Prend en charge à la fois App Router et Pages Router.

Prérequis

• Application Next.js 13+ (App Router ou Pages Router)
• Compte Auth0 et application configurée
• Si vous n'avez pas encore configuré Auth0, utilisez d'abord la skill auth0-quickstart

Quand NE PAS l'utiliser

• Applications React côté client uniquement - Utilisez auth0-react pour les SPAs Vite/CRA
• Applications mobiles React Native - Utilisez auth0-react-native pour iOS/Android
• Frameworks non-Next.js - Utilisez les SDKs spécifiques au framework (Express, Vue, Angular, etc.)
• APIs sans état uniquement - Utilisez la validation JWT middleware si vous n'avez pas besoin de gestion de session

Workflow de démarrage rapide

1. Installer le SDK

npm install @auth0/nextjs-auth0

2. Configurer l'environnement

Pour une configuration automatisée avec Auth0 CLI, consultez le Setup Guide pour les scripts complets.

Pour une configuration manuelle :

Créez .env.local :

AUTH0_SECRET=<generate-a-32-character-secret>
APP_BASE_URL=http://localhost:3000
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret

Générer le secret : openssl rand -hex 32

Important : Ajoutez .env.local à .gitignore

3. Créer le client Auth0 et le middleware

Détecter la structure du projet d'abord : Vérifiez si le projet utilise un répertoire src/ (c'est-à-dire si src/app/ ou src/pages/ existe). Ceci détermine où placer les fichiers :

• Avec src/ : src/lib/auth0.ts, src/middleware.ts (ou src/proxy.ts pour Next.js 16)
• Sans src/ : lib/auth0.ts, middleware.ts (ou proxy.ts pour Next.js 16)

Créez lib/auth0.ts (ou src/lib/auth0.ts si vous utilisez la convention src/) :

import { Auth0Client } from '@auth0/nextjs-auth0/server';

export const auth0 = new Auth0Client({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
  secret: process.env.AUTH0_SECRET!,
  appBaseUrl: process.env.APP_BASE_URL!,
});

Configuration du middleware (Next.js 15 vs 16) :

Next.js 15 - Créez middleware.ts (à la racine du projet, ou src/middleware.ts si vous utilisez src/) :

import { NextRequest } from 'next/server';
import { auth0 } from '@/lib/auth0';

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

Next.js 16 - Vous avez deux options :

Option 1 : Utilisez middleware.ts (identique à Next.js 15, mêmes règles de placement src/) :

import { NextRequest } from 'next/server';
import { auth0 } from '@/lib/auth0';

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

Option 2 : Utilisez proxy.ts (à la racine du projet, ou src/proxy.ts si vous utilisez src/) :

import { NextRequest } from 'next/server';
import { auth0 } from '@/lib/auth0';

export async function proxy(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

Ceci crée automatiquement les endpoints :

• /auth/login - Connexion
• /auth/logout - Déconnexion
• /auth/callback - Callback OAuth
• /auth/profile - Profil utilisateur

4. Ajouter le contexte utilisateur (Optionnel)

Remarque : En v4, l'encapsulation avec <Auth0Provider> est optionnelle. Nécessaire uniquement si vous voulez passer un utilisateur initial lors du rendu côté serveur à useUser().

App Router - Encapsulez optionnellement l'app dans app/layout.tsx :

import { Auth0Provider } from '@auth0/nextjs-auth0/client';
import { auth0 } from '@/lib/auth0';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const session = await auth0.getSession();

  return (
    <html>
      <body>
        <Auth0Provider user={session?.user}>{children}</Auth0Provider>
      </body>
    </html>
  );
}

Pages Router - Encapsulez optionnellement l'app dans pages/_app.tsx :

import { Auth0Provider } from '@auth0/nextjs-auth0/client';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <Auth0Provider user={pageProps.user}>
      <Component {...pageProps} />
    </Auth0Provider>
  );
}

5. Ajouter l'interface d'authentification

Composant client (fonctionne dans les deux routers) :

'use client'; // Nécessaire uniquement pour App Router

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

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

  if (isLoading) return <div>Chargement...</div>;

  if (user) {
    return (
      <div>
        <img src={user.picture} alt={user.name} />
        <h2>Bienvenue, {user.name}!</h2>
        <a href="/auth/logout">Déconnexion</a>
      </div>
    );
  }

  return <a href="/auth/login">Connexion</a>;
}

6. Tester l'authentification

Démarrez votre serveur de développement :

npm run dev

Visitez http://localhost:3000 et testez le flux de connexion.

Documentation détaillée

• Setup Guide - Scripts de configuration automatisée, configuration de l'environnement, utilisation d'Auth0 CLI
• Integration Guide - Authentification côté serveur, routes protégées, routes API, middleware
• API Reference - API SDK complète, hooks, helpers, gestion de session

Erreurs courantes

Skills connexes

• auth0-quickstart - Configuration basique Auth0
• auth0-migration - Migrer depuis un autre fournisseur d'auth
• auth0-mfa - Ajouter l'authentification multifacteur

Référence rapide

Configuration V4 :

• Détecter la convention src/ : vérifier si src/app/ ou src/pages/ existe — placer tous les fichiers dans src/ si c'est le cas
• Créer lib/auth0.ts (ou src/lib/auth0.ts) avec une instance Auth0Client
• Créer la configuration du middleware (obligatoire) :
  • Next.js 15 : middleware.ts (ou src/middleware.ts) avec la fonction middleware()
  • Next.js 16 : middleware.ts avec la fonction middleware() OU proxy.ts avec la fonction proxy() (mêmes règles src/)
• Optionnel : Encapsulez avec <Auth0Provider> pour l'utilisateur SSR

Hooks côté client :

• useUser() - Obtenir l'utilisateur dans les composants clients
• user - Objet du profil utilisateur
• isLoading - État de chargement

Méthodes côté serveur :

• auth0.getSession() - Obtenir la session dans les Server Components/routes API/middleware
• auth0.getAccessToken() - Obtenir le token d'accès pour appeler les APIs

Cas d'usage courants :

• Liens connexion/déconnexion → Utilisez les chemins /auth/login et /auth/logout (voir Étape 5)
• Pages protégées (App Router) → Integration Guide
• Pages protégées (Pages Router) → Integration Guide
• Routes API avec auth → Integration Guide
• Protection middleware → Integration Guide

Références

• Documentation Auth0 Next.js SDK
• Quickstart Auth0 Next.js
• SDK GitHub Repository