Patrons Auth.js (NextAuth v5)

Guide rapide : Configurez Auth.js dans un fichier racine auth.ts en exportant { auth, handlers, signIn, signOut } depuis NextAuth(). Utilisez la fonction unifiée auth() partout (Server Components, Route Handlers, middleware). La stratégie de session par défaut est JWT (basée sur les cookies) ; ajoutez un adaptateur de base de données pour des sessions persistantes. Protégez les routes via le middleware ou des vérifications auth() par page.

<critical_requirements>

CRITIQUE : Avant d'utiliser ce Skill

Tout le code doit suivre les conventions du projet dans CLAUDE.md (kebab-case, exports nommés, ordre des importations, import type, constantes nommées)

(Vous DEVEZ configurer Auth.js dans un fichier racine auth.ts et exporter { auth, handlers, signIn, signOut } depuis NextAuth())

(Vous DEVEZ utiliser la fonction unifiée auth() pour l'accès côté serveur à la session - PAS les fonctions dépréciées getServerSession(), getSession() ou getToken())

(Vous DEVEZ utiliser la variable d'environnement AUTH_SECRET - NEXTAUTH_SECRET est dépréciée dans v5)

(Vous DEVEZ utiliser les variables d'environnement préfixées par AUTH_ pour les identifiants des fournisseurs (ex. AUTH_GITHUB_ID, AUTH_GITHUB_SECRET) - elles sont auto-détectées)

(Vous DEVEZ séparer la configuration d'authentification en auth.config.ts (compatible Edge) et auth.ts (avec adaptateur) lorsque vous utilisez des sessions en base de données avec le middleware)

(Vous DEVEZ vérifier la session à l'intérieur des Server Actions et des routes API - le middleware seul n'est PAS suffisant pour l'autorisation)

</critical_requirements>

Auto-détection : Auth.js, NextAuth, next-auth, authjs, auth.ts, auth.config.ts, NextAuth(), signIn, signOut, auth(), handlers, SessionProvider, useSession, AUTH_SECRET, fournisseur OAuth, fournisseur d'identifiants, adaptateur de base de données, @auth/prisma-adapter, @auth/drizzle-adapter, callback authorized, callback jwt, callback session, proxy auth, middleware auth

Quand l'utiliser :

Ajout de l'authentification aux applications Next.js, SvelteKit, Express ou Qwik
Implémentation de la connexion OAuth (GitHub, Google, Discord, etc.) avec plus de 80 fournisseurs intégrés
Construction de flux d'authentification par e-mail / lien magique
Besoin de gestion de session JWT ou basée sur une base de données
Projets nécessitant une authentification par middleware compatible Edge

Quand ne PAS l'utiliser :

Construction d'un système d'authentification personnalisé à partir de zéro (Auth.js est opinioné)
Besoin d'une gestion fine des organisations/équipes prête à l'emploi
Applications mobiles sans interface web
Besoin d'une authentification auto-hébergée avec une architecture de plugins

Patrons clés couverts :

Configuration d'authentification (auth.ts, auth.config.ts)
Fournisseurs OAuth (GitHub, Google, Identifiants, E-mail)
Stratégies de session (JWT vs base de données)
Accès à la session (Server Components, Route Handlers, Client Components)
Protection des routes via middleware/proxy
Adaptateurs de base de données (Prisma, Drizzle)
Callbacks (jwt, session, signIn, redirect)
Contrôle d'accès basé sur les rôles
Configuration fractionnée pour la compatibilité Edge

Ressources détaillées :

Pour les cadres de décision et les anti-patrons, voir reference.md

Patrons de base :

examples/core.md - Configuration d'authentification, fournisseurs, callbacks
examples/session.md - Stratégies de session, modèles d'accès à la session
examples/middleware.md - Protection des routes, middleware, compatibilité Edge
examples/database.md - Adaptateurs de base de données, Prisma, Drizzle
examples/patterns.md - Contrôle d'accès basé sur les rôles, liens magiques, liaison de comptes

Philosophie

Auth.js (v5) consolide l'authentification en une API unique et unifiée. La fonction auth() remplace getServerSession, getSession, withAuth et getToken de la v4 pour une utilisation côté serveur. useSession() reste l'API correcte côté client. La configuration se trouve dans un fichier racine, pas dans les routes API.

Principes de base :

Indépendant du framework - Fonctionne avec Next.js, SvelteKit, Express, Qwik
API unifiée - Une seule fonction auth() pour tous les contextes côté serveur
Écosystème de fournisseurs - Plus de 80 fournisseurs OAuth intégrés avec auto-détection des variables d'environnement AUTH_*
JWT par défaut - Sessions sans état dans des cookies cryptés, aucune base de données requise
Compatible Edge - Le middleware s'exécute sur le runtime Edge avec une configuration fractionnée (le proxy Next.js 16 s'exécute sur Node.js)
Complexité progressive - Commencez avec OAuth, ajoutez un adaptateur de base de données, puis personnalisez les callbacks

Patrons de base

Patron 1 : Configuration d'authentification

Le fichier de configuration central exporte tout ce dont vous avez besoin depuis NextAuth().

Configuration OAuth de base

// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import Google from "next-auth/providers/google";

export const { auth, handlers, signIn, signOut } = NextAuth({
  providers: [
    GitHub, // Détecte automatiquement AUTH_GITHUB_ID et AUTH_GITHUB_SECRET
    Google, // Détecte automatiquement AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET
  ],
});

// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";

export const { GET, POST } = handlers;

Pourquoi c'est bien : Un seul fichier de configuration exporte tous les utilitaires d'authentification, les fournisseurs détectent automatiquement les variables d'environnement AUTH_*, la route API est minimale

Variables d'environnement

# .env.local
AUTH_SECRET="generate-with-npx-auth-secret"  # Requis
AUTH_GITHUB_ID="your-github-client-id"       # Détecté automatiquement par le fournisseur GitHub
AUTH_GITHUB_SECRET="your-github-secret"      # Détecté automatiquement par le fournisseur GitHub
AUTH_GOOGLE_ID="your-google-id"       # Détecté automatiquement par le fournisseur Google
AUTH_GOOGLE_SECRET="your-google-secret"

Pourquoi c'est bien : Le préfixe AUTH_ est standardisé dans v5, AUTH_SECRET remplace NEXTAUTH_SECRET déprécié, les fournisseurs détectent automatiquement les identifiants

Patron 2 : Fournisseurs

Auth.js prend en charge l'authentification OAuth, par e-mail/lien magique et par identifiants. Plus de 80 fournisseurs OAuth intégrés détectent automatiquement les variables d'environnement AUTH_*.

// OAuth : personnaliser le mappage du profil
GitHub({
  profile(profile) {
    return {
      id: String(profile.id),
      name: profile.name ?? profile.login,
      role: "user",
    };
  },
});

// Identifiants : valider l'entrée, retourner null en cas d'échec
Credentials({
  async authorize(credentials) {
    const parsed = LoginSchema.safeParse(credentials);
    if (!parsed.success) return null;
    const user = await getUserByEmail(parsed.data.email);
    if (
      !user ||
      !(await verifyPassword(parsed.data.password, user.hashedPassword))
    )
      return null;
    return { id: user.id, name: user.name, email: user.email };
  },
});

Règles clés : Valider l'entrée avant la recherche en base de données, toujours hacher les mots de passe, retourner null en cas d'échec (ne jamais lever d'exception - cela fuit des informations). Voir examples/core.md pour les implémentations complètes.

Patron 3 : Callbacks

Quatre callbacks personnalisent le comportement de l'authentification. Le flux de données : callback jwt (enrichir le jeton) -> callback session (exposer au client).

callbacks: {
  jwt({ token, user }) {
    if (user) { token.id = user.id; token.role = user.role ?? "user"; }
    return token;
  },
  session({ session, token }) {
    session.user.id = token.id as string;
    session.user.role = token.role as string;
    return session;
  },
}

Règles clés : Le callback JWT s'exécute à CHAQUE appel à auth() (restez léger), le paramètre user n'est présent qu'à la connexion, n'exposez jamais les jetons OAuth au client. Voir examples/core.md pour les implémentations complètes des callbacks, y compris signIn et redirect.

Patron 4 : Accès à la session

La fonction unifiée auth() remplace getServerSession, getSession et getToken de la v4 pour une utilisation côté serveur. useSession() reste pour les Client Components.

Contexte	Comment accéder à la session
Server Component	`const session = await auth()`
Route Handler	`export const GET = auth(function GET(req) { req.auth })`
Server Action	`const session = await auth()`
Middleware/Proxy	`export { auth as middleware }` ou callback `authorized`
Client Component	`useSession()` (nécessite `SessionProvider` dans le layout)

Règles clés : Les importations côté serveur proviennent de @/auth, les importations côté client de next-auth/react. N'appelez jamais auth() dans les Client Components. Voir examples/session.md pour les implémentations complètes.

Patron 5 : Actions de connexion/déconnexion

Deux approches : Server Actions (recommandé, amélioration progressive) ou côté client.

// Côté serveur (recommandé) : importez depuis @/auth, utilisez les Server Actions dans les formulaires
import { signIn, signOut } from "@/auth";
// Dans une action de formulaire : await signIn("github", { redirectTo: "/dashboard" })
// Dans une action de formulaire : await signOut({ redirectTo: "/" })

// Côté client : importez depuis next-auth/react, utilisez les gestionnaires onClick
import { signIn, signOut } from "next-auth/react";
// onClick : signIn("github", { callbackUrl: "/dashboard" })

Règles clés : Côté serveur utilisez redirectTo, côté client utilisez callbackUrl. signIn() lève une exception NEXT_REDIRECT en interne - ne l'enveloppez pas dans un try/catch en attendant une valeur de retour. Voir examples/core.md pour les implémentations complètes.

Patron 6 : Extensions TypeScript

Étendez les types de session et JWT via la fusion de déclarations dans types/next-auth.d.ts. Déclarez les champs personnalisés (par exemple id, role) sur les interfaces Session, User et JWT en utilisant & DefaultSession["user"] pour préserver les valeurs par défaut. Voir examples/core.md pour l'exemple complet de déclaration de type.

<intégration>

Guide d'intégration

Auth.js est la couche d'authentification. Il gère la vérification d'identité, la gestion de session et la protection des routes. Il ne gère PAS la logique d'autorisation (vérifications de rôles, systèmes de permissions) - cela relève du code applicatif.

Support des frameworks : Auth.js fonctionne avec plusieurs frameworks web via des packages spécifiques (next-auth, @auth/sveltekit, @auth/express).

Adaptateurs de base de données : Pour les sessions en base de données, Auth.js fournit des packages d'adaptateurs (@auth/prisma-adapter, @auth/drizzle-adapter, etc.) qui s'intègrent avec votre ORM. Voir examples/database.md.

La stratégie de session dépend de vos besoins :

JWT (par défaut) - Aucune base de données nécessaire, fonctionne sur Edge, sans état
Base de données - Nécessite un adaptateur, stockage de session côté serveur, prend en charge la révocation immédiate

Auth.js ne gère PAS : l'autorisation fine/RBAC, la limitation de débit ou les requêtes de base de données au-delà de l'authentification - ce sont des préoccupations au niveau de l'application.

</intégration>

<drapeaux_rouges>

DRAPEAUX ROUGES

Utiliser getServerSession(authOptions) -- déprécié dans v5 ; utilisez auth() depuis votre auth.ts
Utiliser NEXTAUTH_SECRET ou NEXTAUTH_URL -- déprécié ; utilisez AUTH_SECRET (l'URL est automatiquement détectée)
Fournisseur d'identifiants sans limitation de débit -- vulnérable aux attaques par force brute
Exposer les jetons OAuth au client via le callback session -- gardez accessToken/refreshToken uniquement côté serveur
Middleware/proxy comme seule autorisation -- s'exécute avant le rendu mais ne remplace pas les vérifications par route dans les Server Actions/API routes
Adaptateur de base de données importé dans le middleware -- les ORM de base de données ne peuvent pas s'exécuter sur le runtime Edge (Next.js 14/15) ; séparez la configuration en auth.config.ts + auth.ts
Envelopper signIn() dans un try/catch -- il lève une exception NEXT_REDIRECT en interne (c'est intentionnel)
Le callback JWT interrogeant la base de données à chaque appel -- s'exécute à CHAQUE invocation de auth() ; restez léger

Voir reference.md pour la liste complète des anti-patrons, des pièges et le tableau de migration.

</drapeaux_rouges>

<rappels_critiques>

RAPPELS CRITIQUES

Tout le code doit suivre les conventions du projet dans CLAUDE.md