Modèles d'authentification Clerk
Guide rapide : Clerk fournit une authentification managée avec des composants d'interface préconstruits, des helpers côté serveur et une multi-tenance basée sur les organisations. Utilisez
clerkMiddleware()pour la protection des routes,<Show>pour le rendu conditionnel, les hooks pour l'état côté client, etauth()/currentUser()pour l'authentification côté serveur. Clerk Core 3 (2026) remplace<SignedIn>/<SignedOut>par<Show>, renomme le fichier middleware enproxy.ts(Next.js 16+) et consolide les packages.
<critical_requirements>
CRITIQUE : Avant d'utiliser ce skill
Tout le code doit respecter les conventions du projet dans CLAUDE.md (kebab-case, exports nommés, ordre des imports,
import type, constantes nommées)
(Vous DEVEZ utiliser @clerk/nextjs/server pour TOUS les imports côté serveur – n'importer JAMAIS les helpers serveur depuis @clerk/nextjs)
(Vous DEVEZ vérifier les webhooks à l'aide du helper verifyWebhook de Clerk – ne faites JAMAIS confiance à des payloads de webhook non vérifiés)
(Vous DEVEZ utiliser le composant <Show> au lieu des composants dépréciés <SignedIn>/<SignedOut>/<Protect> – ils sont supprimés dans Core 3)
(Vous NE DEVEZ PAS passer l'objet currentUser() complet au client – il contient privateMetadata qui doit rester côté serveur)
(Vous DEVEZ protéger les routes à la fois dans le middleware ET dans la couche d'accès aux données – le middleware seul est insuffisant)
</critical_requirements>
Auto-détection : Clerk, ClerkProvider, clerkMiddleware, @clerk/nextjs, useUser, useAuth, useClerk, useSession, useOrganization, SignIn, SignUp, UserButton, UserProfile, OrganizationSwitcher, auth(), currentUser(), CLERK_SECRET_KEY, NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, Show when="signed-in"
Quand l'utiliser :
- Ajouter l'authentification et la gestion des utilisateurs à une application
- Construire des applications B2B multi-tenant avec un contrôle d'accès basé sur les organisations
- Utiliser des composants d'interface préconstruits pour la connexion/inscription avec un thème personnalisable
- Protéger les routes avec un middleware et des vérifications d'autorisation côté serveur
- Synchroniser les données utilisateur de Clerk dans votre base de données via des webhooks
Modèles clés couverts :
- Configuration de ClerkProvider, variables d'environnement, configuration du middleware
- Composants d'interface préconstruits (
<SignIn>,<SignUp>,<UserButton>,<Show>) - Hooks côté client (
useUser,useAuth,useSession,useOrganization) - Authentification côté serveur (
auth(),currentUser()) dans les Server Components, Route Handlers, Server Actions - Protection des routes avec
clerkMiddleware()etcreateRouteMatcher() - Multi-tenance basée sur les organisations avec rôles et permissions
- Gestion des webhooks avec vérification de signature Svix
Quand NE PAS l'utiliser :
- Besoin d'une authentification auto-hébergée (contrôle total sur le stockage des données d'authentification)
- Impossible d'utiliser un service d'authentification tiers (contraintes de conformité/réglementaires)
- Authentification simple par clé API (un middleware personnalisé suffit)
- Contraintes budgétaires empêchant l'utilisation d'un service managé
Ressources détaillées :
- reference.md – Cadres de décision, référence rapide des hooks, aide-mémoire pour la migration Core 3
- examples/core.md – ClerkProvider, variables d'environnement, configuration du middleware
- examples/components.md – Composants préconstruits, personnalisation, prop appearance
- examples/hooks.md – useUser, useAuth, useSession, états de chargement, rendu conditionnel
- examples/server.md – Server Components, routes API, Server Actions, gestion des webhooks
- examples/organizations.md – Gestion des organisations, rôles, permissions, RBAC
Philosophie
Clerk est une plateforme d'authentification managée qui gère l'ensemble du cycle de vie de l'authentification : inscription, connexion, gestion des sessions, profils utilisateur, organisations et MFA. Au lieu de construire l'authentification à partir de zéro, vous intégrez le SDK et les composants préconstruits de Clerk.
Principes fondamentaux :
- Défense en profondeur – Protégez les routes au niveau du middleware ET vérifiez l'authentification à chaque point d'accès aux données. Le middleware seul est insuffisant (CVE-2025-29927 a démontré des vulnérabilités de contournement du middleware).
- Authentification d'abord côté serveur – Utilisez
auth()etcurrentUser()dans les Server Components et Route Handlers. Utilisez les hooks côté client (useUser,useAuth) uniquement lorsque vous avez besoin d'un état réactif côté client. - Préconstruit plutôt que personnalisé – Utilisez les composants
<SignIn>,<SignUp>,<UserButton>de Clerk. Ne créez des flux personnalisés que lorsque les composants préconstruits ne peuvent vraiment pas répondre aux exigences. - Organisations pour la multi-tenance – Utilisez les organisations de Clerk avec rôles et permissions pour les applications B2B. Ne construisez pas de systèmes de locataires personnalisés sur le modèle utilisateur de Clerk.
- Synchronisation pilotée par webhooks – Synchronisez les données de Clerk dans votre base de données via des webhooks, pas par sondage. Vérifiez toujours les signatures des webhooks avec
verifyWebhook.
Quand utiliser Clerk :
- Vous avez besoin d'une authentification rapide avec un minimum de code personnalisé
- Vous voulez des composants d'interface préconstruits pour la connexion/inscription/gestion des utilisateurs
- Vous avez besoin d'une multi-tenance avec RBAC basée sur les organisations
- Vous voulez une MFA managée, SSO (SAML/OIDC) et une connexion sociale
Quand NE PAS utiliser Clerk :
- Vous avez besoin d'un contrôle total sur le stockage des données d'authentification (exigence auto-hébergée)
- Vous ne pouvez pas utiliser un service d'authentification tiers (conformité/réglementation)
- Votre application n'a besoin que d'une authentification simple par clé API
- Des contraintes budgétaires empêchent l'utilisation d'un service managé
Modèles Fondamentaux
Modèle 1 : Configuration de ClerkProvider et du Middleware
Chaque application Clerk a besoin d'un <ClerkProvider> enveloppant l'application et de clerkMiddleware() protégeant les routes. Voir examples/core.md pour des exemples de configuration complets.
Règles clés :
ClerkProviderse place à l'intérieur de<body>, pas autour de<html>– Core 3 l'exige- Utilisez la variable d'environnement
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, ne codez jamais les clés en dur - Le fichier middleware est
proxy.tssur Next.js 16+ oumiddleware.tssur Next.js <=15 - Le point de terminaison du webhook doit être dans la liste des routes publiques (vérifié séparément par
verifyWebhook) CLERK_WEBHOOK_SIGNING_SECRETest la variable d'environnement pour la signature du webhook (pasCLERK_WEBHOOK_SECRET)
// proxy.ts (Next.js 16+) ou middleware.ts (Next.js <=15)
const isPublicRoute = createRouteMatcher([
"/",
"/sign-in(.*)",
"/sign-up(.*)",
"/api/webhooks(.*)",
]);
export default clerkMiddleware(async (auth, req) => {
if (!isPublicRoute(req)) {
await auth.protect();
}
});
Pourquoi c'est bien : Les routes publiques sont explicitement autorisées, tout le reste nécessite une authentification, le point de terminaison du webhook est public (vérifié séparément)
// MAUVAIS : clerkMiddleware() sans callback
export default clerkMiddleware(); // Toutes les routes sont PUBLIQUES par défaut !
Pourquoi c'est mauvais : clerkMiddleware() sans callback attache les données d'authentification mais ne protège aucune route
Modèle 2 : Composants d'Interface Préconstruits et <Show>
Utilisez <Show> pour le rendu conditionnel (remplacement Core 3 de <SignedIn>/<SignedOut>/<Protect>). Voir examples/components.md pour des exemples complets.
<Show when="signed-out"><SignInButton /></Show>
<Show when="signed-in"><UserButton /></Show>
<Show when={{ role: "org:admin" }}><AdminPanel /></Show>
<Show when={(has) => has({ permission: "org:invoices:manage" })}><InvoiceManager /></Show>
Pourquoi c'est bien : <Show> est l'API Core 3, prend en charge des conditions de type chaîne/objet/callback, props fallback pour les non autorisés
// MAUVAIS : Déprécié – supprimé dans Core 3
<SignedIn>...</SignedIn>
<SignedOut>...</SignedOut>
<Protect role="admin">...</Protect>
Pourquoi c'est mauvais : <SignedIn>, <SignedOut>, <Protect> supprimés dans Core 3, utilisez <Show> avec la prop when
Les pages de connexion/inscription nécessitent des segments de route catch-all [[...sign-in]] pour les flux multi-étapes (MFA, callbacks OAuth).
Modèle 3 : Hooks Côté Client
Utilisez les hooks dans les Client Components pour un état d'authentification réactif. Vérifiez toujours isLoaded avant d'accéder aux données. Voir examples/hooks.md pour des exemples complets.
"use client";
const { isLoaded, isSignedIn, user } = useUser();
if (!isLoaded) return <div>Chargement...</div>;
if (!isSignedIn) return <div>Veuillez vous connecter</div>;
// Maintenant, il est sûr d'accéder à user.firstName, user.emailAddresses, etc.
Pourquoi c'est bien : Prévient les erreurs d'hydratation dues à l'accès à undefined pendant l'initialisation, prévient les TypeError liées à l'accès à null lorsqu'on est déconnecté
// MAUVAIS : Accès à user sans garde-fou
const { user } = useUser();
return <p>{user.firstName}</p>; // Erreur d'exécution quand isLoaded=false ou isSignedIn=false
Pourquoi c'est mauvais : user est undefined jusqu'au chargement et null lorsqu'on est déconnecté
Hooks clés :
useUser()– données du profil utilisateur (nom, email, avatar)useAuth()– jetons de session (getToken()),userId,orgId,has()pour l'autorisationuseOrganization()– données de l'organisation active, adhésion, liste des membres paginéeuseReverification()– ré-authentification avant des actions sensibles (Core 3)
Dans Core 3, getToken() lance ClerkOfflineError lorsqu'il est hors ligne au lieu de retourner null – enveloppez toujours dans un try/catch.
Modèle 4 : Authentification Côté Serveur
Utilisez auth() et currentUser() depuis @clerk/nextjs/server. Voir examples/server.md pour des exemples complets.
auth() – léger, pas d'appel API, lit les revendications de session :
import { auth } from "@clerk/nextjs/server";
const { userId, orgId, isAuthenticated, redirectToSignIn } = await auth();
if (!isAuthenticated) return redirectToSignIn();
currentUser() – objet utilisateur complet, effectue un appel API Backend :
import { currentUser } from "@clerk/nextjs/server";
const user = await currentUser();
// CRITIQUE : Sélectionnez les champs sécurisés avant de les passer aux composants client
const safeData = { firstName: user.firstName, imageUrl: user.imageUrl };
Pourquoi c'est critique : currentUser() retourne privateMetadata qui ne doit jamais atteindre le client. Sélectionnez explicitement les champs.
Défense en profondeur : L'authentification DOIT être vérifiée dans chaque Server Action et Route Handler, pas seulement dans le middleware :
"use server";
const { userId } = await auth();
if (!userId) throw new Error("Non autorisé");
// userId limite toutes les requêtes/mutations à l'utilisateur actuel
Modèle 5 : Autorisation avec Rôles et Permissions
Utilisez auth.protect() ou has() pour un contrôle d'accès granulaire. Voir examples/organizations.md pour les modèles RBAC.
// Middleware : protection de route basée sur le rôle
await auth.protect((has) => has({ role: "org:admin" }));
// Server Component : vérification de permission
const { has } = await auth();
if (!has({ permission: "org:invoices:delete" })) redirect("/dashboard");
// Client : rendu conditionnel par rôle
<Show when={{ role: "org:admin" }}><AdminPanel /></Show>
Format des permissions : org:<feature>:<action> (ex : org:invoices:create, org:reports:read)
Rôles par défaut : org:admin (toutes les permissions), org:member (lecture seule). Les rôles personnalisés sont configurés dans le tableau de bord Clerk.
Modèle 6 : Gestion des Webhooks
Utilisez les webhooks Clerk (via Svix) pour synchroniser les données utilisateur dans votre base de données. Voir examples/server.md pour un gestionnaire complet.
import { verifyWebhook } from "@clerk/nextjs/webhooks";
export async function POST(req: Request) {
const evt = await verifyWebhook(req); // lit la variable d'environnement CLERK_WEBHOOK_SIGNING_SECRET
// evt.type: "user.created" | "user.updated" | "user.deleted" | "organization.*" | ...
// evt.data: UserJSON | OrganizationJSON | etc.
}
Pourquoi c'est bien : verifyWebhook valide la signature Svix, retourne toujours 200 pour éviter les nouvelles tentatives, la route du webhook est publique dans le middleware (vérifiée par signature, pas par authentification)
// MAUVAIS : Pas de vérification de signature
const body = await req.json(); // N'importe qui peut POSTer de fausses données !
await db.insert(users).values(body.data); // Vulnérabilité de sécurité
Pourquoi c'est mauvais : L'absence de vérification de signature signifie que n'importe qui peut envoyer de faux événements webhook à votre point de terminaison
Importez les types depuis @clerk/shared/types (Core 3) : UserJSON, OrganizationJSON, OrganizationMembershipJSON
<decision_framework>
Cadre de Décision
Authentification Client vs Serveur
Où avez-vous besoin des données d'authentification ?
|-- Server Component, Route Handler, Server Action
| |-- Besoin uniquement de userId/sessionId ? --> auth()
| |-- Besoin de l'objet utilisateur complet ? --> currentUser()
| |-- Besoin de protéger la route ? --> auth.protect()
| +-- Besoin du contexte d'organisation ? --> auth() retourne orgId, orgRole
|
+-- Client Component (interface interactive)
|-- Besoin des données du profil utilisateur ? --> useUser()
|-- Besoin des données de session/jeton ? --> useAuth()
|-- Besoin des données d'organisation ? --> useOrganization()
+-- Besoin de l'API Clerk de bas niveau ? --> useClerk()
Stratégie de Protection des Routes
De quel type de route s'agit-il ?
|-- Publique (page d'accueil, connexion, inscription, webhooks)
| +-- Ajoutez au matcher isPublicRoute, sautez auth.protect()
|
|-- Authentifiée (tableau de bord, profil, paramètres)
| +-- auth.protect() dans le middleware + vérification auth() dans la couche de données
|
+-- Autorisée (admin, spécifique à une organisation, soumise à permission)
|-- Basée sur le rôle ? --> auth.protect({ role: "org:admin" })
+-- Basée sur la permission ? --> auth.protect((has) => has({ permission: "org:feature:action" }))
Choix du Composant
De quelle interface d'authentification avez-vous besoin ?
|-- Page de connexion complète --> <SignIn /> sur une route catch-all
|-- Page d'inscription complète --> <SignUp /> sur une route catch-all
|-- Bouton de connexion (modal) --> <SignInButton />
|-- Avatar + menu utilisateur --> <UserButton />
|-- Éditeur de profil complet --> <UserProfile />
|-- Sélecteur d'organisation --> <OrganizationSwitcher />
+-- Contenu conditionnel --> <Show when="signed-in"> ou <Show when={{ role: "..." }}>
</decision_framework>
<red_flags>
SIGNAUX D'ALARME
Problèmes de haute priorité :
- Importer des helpers serveur depuis
@clerk/nextjsau lieu de@clerk/nextjs/server(casse dans les Server Components) - Utiliser les composants dépréciés
<SignedIn>/<SignedOut>/<Protect>(supprimés dans Core 3) - Passer l'objet
currentUser()complet aux composants client (fuitprivateMetadata) - Faire confiance aux payloads de webhook sans vérification de signature
verifyWebhook - Se fier uniquement au middleware pour la protection des routes (le middleware peut être contourné)
- Importer les types depuis
@clerk/typesau lieu de@clerk/shared/types(Core 3)