Communitygithub.com

agents-inc/skills

Authentification gérée par Clerk – ClerkProvider, middleware, composants préconstruits, hooks, authentification côté serveur, organisations et webhooks.

Qu'est-ce que skills ?

Ce skill fournit un guide complet et impératif pour intégrer Clerk, une plateforme d'authentification managée, dans des applications Next.js. Il couvre l'ensemble du cycle de vie : configuration du `ClerkProvider` et du middleware (`clerkMiddleware`), utilisation des composants d'interface préconstruits (comme `<SignIn>`, `<SignUp>`, et le nouveau `<Show>` remplaçant les dépréciés `<SignedIn>/<SignedOut>`), ainsi que les hooks côté client (`useUser`, `useAuth`) pour un état réactif. Côté serveur, il détaille l'emploi d'`auth()` et `currentUser()` dans les Server Components, Route Handlers et Server Actions, en insistant sur la nécessité d'une vérification d'authentification à chaque couche (défense en profondeur). Enfin, il traite des fonctionnalités avancées : la gestion multi-tenant via les organisations, le contrôle d'accès basé sur les rôles et permissions, et la synchronisation des données utilisateur via des webhooks sécurisés par `verifyWebhook`. Le skill met en garde contre les erreurs critiques comme l'import de helpers serveur depuis le mauvais module, l'utilisation de composants obsolètes, ou le fait de passer l'objet `currentUser()` complet au client (qui contient `privateMetadata`).

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/api-auth-clerk

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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, et auth()/currentUser() pour l'authentification côté serveur. Clerk Core 3 (2026) remplace <SignedIn>/<SignedOut> par <Show>, renomme le fichier middleware en proxy.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() et createRouteMatcher()
  • 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 :

  1. 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).
  2. Authentification d'abord côté serveur – Utilisez auth() et currentUser() 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.
  3. 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.
  4. 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.
  5. 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 :

  • ClerkProvider se 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.ts sur Next.js 16+ ou middleware.ts sur 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_SECRET est la variable d'environnement pour la signature du webhook (pas CLERK_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'autorisation
  • useOrganization() – données de l'organisation active, adhésion, liste des membres paginée
  • useReverification() – 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/nextjs au 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 (fuit privateMetadata)
  • 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/types au lieu de @clerk/shared/types (Core 3)

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

Skills associés