Authentification Clerk

Clerk est la plateforme d’authentification et de gestion des utilisateurs qui gère toutes les opérations d’identité dans CodeCourier. De l’inscription à la gestion des sessions en passant par le nettoyage de compte piloté par webhook, Clerk fournit une solution d’authentification complète qui s’intègre parfaitement au frontend Next.js et au backend Convex. Cette page explique comment CodeCourier utilise Clerk, les instructions de configuration et les options de personnalisation.

Ce que fournit Clerk

Clerk est une plateforme d’authentification axée sur les développeurs qui offre :

• Plusieurs méthodes de connexion -- E-mail et mot de passe, fournisseurs OAuth (Google, GitHub et autres), liens magiques, et plus encore.
• Composants d’interface préconstruits -- Formulaires de connexion et d’inscription prêts à l’emploi qui gèrent l’intégralité du flux d’authentification.
• Émission de JWT -- Des JWT signés qui s’intègrent aux services backend comme Convex pour la vérification d’identité côté serveur.
• Gestion des utilisateurs -- Profils utilisateur, métadonnées et paramètres de compte via un tableau de bord hébergé.
• Événements webhook -- Notifications pour les événements du cycle de vie utilisateur tels que la création et la suppression de compte.
• Gestion des sessions -- Rafraîchissement automatique des sessions, prise en charge multi-appareils et gestion sécurisée des cookies.

Comment CodeCourier utilise Clerk

Flux d’authentification

CodeCourier utilise le SDK @clerk/nextjs (version 6+) pour intégrer Clerk au routeur d’application Next.js. L’intégration inclut :

• Pages de connexion et d’inscription -- Situées sur /sign-in et /sign-up, elles utilisent les composants préconstruits de Clerk stylisés pour correspondre au système de design de CodeCourier.
• Protection des routes -- Le proxy Next.js (proxy.ts) intercepte les requêtes et redirige les utilisateurs non authentifiés vers la page de connexion pour les routes protégées.
• Intégration Convex -- Le composant ConvexProviderWithClerk enveloppe l’application et transmet automatiquement les tokens de session Clerk au client Convex pour l’authentification côté serveur.

Synchronisation des enregistrements utilisateur

Lorsqu’un utilisateur se connecte pour la première fois, CodeCourier crée un enregistrement correspondant dans la table Convex users. Cet enregistrement stocke :

• clerkId -- L’identifiant utilisateur Clerk, utilisé pour les recherches via l’index by_clerk_id.
• email -- L’adresse e-mail principale de l’utilisateur.
• name -- Le nom d’affichage de l’utilisateur (facultatif).
• imageUrl -- L’URL de l’avatar de l’utilisateur depuis son profil Clerk ou son fournisseur OAuth.
• role -- Un rôle facultatif au niveau de l’application (à ne pas confondre avec les rôles d’adhésion au projet).

Gestion des sessions

Clerk gère automatiquement le cycle de vie des sessions. Les sessions sont maintenues via des cookies HTTP-only sécurisés avec rafraîchissement automatique. Le SDK @clerk/nextjs fournit un middleware (implémenté sous forme de proxy.ts dans Next.js 16) qui valide la session à chaque requête et rend l’identité de l’utilisateur disponible pour les composants serveur et les routes API.

Suppression de compte

Lorsqu’un utilisateur supprime son compte Clerk, le point de terminaison /clerk/webhook reçoit un événement user.deleted. Cela déclenche le nettoyage des données de l’utilisateur dans Convex. Le webhook utilise la vérification de signature Svix pour la sécurité (voir la page Webhooks pour les détails de vérification).

Installation et configuration

Variables d’environnement

Trois variables d’environnement sont requises pour l’intégration Clerk :

• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY -- La clé publique de votre tableau de bord Clerk. Utilisée par le SDK frontend pour les opérations côté client.
• CLERK_SECRET_KEY -- La clé secrète de votre tableau de bord Clerk. Utilisée par le SDK côté serveur pour la validation des sessions et les appels API.
• CLERK_WEBHOOK_SECRET -- Le secret de signature Svix pour la vérification des webhooks. Obtenu depuis la section webhooks de votre tableau de bord Clerk.

Configuration du tableau de bord Clerk

1. Créez une application Clerk sur clerk.com.
2. Configurez les méthodes de connexion que vous souhaitez prendre en charge (e-mail/mot de passe, OAuth Google, OAuth GitHub, etc.).
3. Copiez la clé publique et la clé secrète dans vos variables d’environnement.
4. Configurez un point de terminaison webhook pointant vers l’URL de déploiement de votre Convex suivie de /clerk/webhook.
5. Abonnez-vous à l’événement user.deleted (et à tout autre événement que vous souhaitez gérer).
6. Copiez le secret de signature du webhook dans votre variable d’environnement CLERK_WEBHOOK_SECRET.

Gestion des utilisateurs

Profils utilisateur

Les informations de profil utilisateur sont gérées principalement via Clerk. La page de profil utilisateur hébergée par Clerk permet aux utilisateurs de :

• Mettre à jour leur nom d’affichage et leur avatar
• Modifier leur adresse e-mail
• Gérer les comptes OAuth connectés
• Mettre à jour leur mot de passe
• Activer ou désactiver l’authentification à deux facteurs

CodeCourier lit les informations de profil depuis Clerk via le JWT de session et les affiche dans l’en-tête du tableau de bord, le composant d’avatar utilisateur et les listes de membres de projet.

Préférences utilisateur

Les préférences spécifiques à l’application (comme le dernier projet actif) sont stockées dans la table Convex userSettings, séparément du profil Clerk. Cette séparation permet à Clerk de rester focalisé sur l’identité tandis que Convex gère l’état de l’application.

OAuth et authentification sociale

Clerk prend en charge de nombreux fournisseurs OAuth d’emblée. Pour ajouter une option de connexion sociale :

1. Accédez à User & Authentication > Social Connections dans le tableau de bord Clerk.
2. Activez le fournisseur souhaité (Google, GitHub, etc.).
3. Configurez les identifiants de l’application OAuth (client ID et secret) pour les déploiements en production.

Aucune modification de code n’est nécessaire dans CodeCourier -- les composants de connexion Clerk affichent automatiquement des boutons pour tous les fournisseurs activés.

Personnalisation

Intégration du thème

CodeCourier personnalise les composants de connexion et d’inscription Clerk à l’aide du paquet @clerk/themes. La configuration de l’apparence est définie dans lib/clerk-appearance.ts et garantit que les composants Clerk correspondent au système de design de CodeCourier, y compris la prise en charge du mode sombre et une typographie cohérente.

Auth Guard

Le composant AuthGuard assure la protection des routes côté client. Il vérifie l’état de la session Clerk et redirige les utilisateurs non authentifiés vers la page de connexion. Cela fonctionne de pair avec le proxy côté serveur pour une défense en profondeur.

RGPD et confidentialité des données

CodeCourier implémente un système de gestion du consentement aux côtés de l’authentification Clerk. Les tables consents et consentHistory suivent le consentement de l’utilisateur pour le traitement des données essentielles, d’analyse, marketing et fonctionnelles. Les utilisateurs peuvent soumettre des demandes de données (export, suppression, restriction, opposition, rectification) via le système dataRequests.

Lorsqu’un utilisateur demande la suppression de son compte via CodeCourier, le système traite la demande en interne et peut déclencher la suppression du compte Clerk si nécessaire. Inversement, si un utilisateur supprime directement son compte Clerk, le webhook garantit que CodeCourier est notifié et peut procéder au nettoyage en conséquence.