Supabase Auth en pratique : vérification e-mail, OAuth et gestion de session

J’ai ouvert le Supabase Dashboard, cliqué sur Authentication, et j’ai été dépassé. Vérification e-mail, Magic Link, OAuth, config SSR… trop d’options. Laquelle choisir ? Comment configurer ?

Si vous êtes dans le même cas, pas de panique. En ajoutant la connexion à un petit projet, j’ai perdu une demi-journée avant de comprendre que chaque mode a son usage. Cet article enchaîne les trois piliers de Supabase Auth : vérification e-mail, intégration OAuth, et la gestion de session qui embrouille souvent. À la fin, vous devriez pouvoir mettre en place une authentification complète en une trentaine de minutes.

Vérification e-mail — le mode le plus basique

Franchement, la vérification e-mail est la partie la plus simple de Supabase Auth, et aussi celle qu’on néglige le plus.

Dans le Dashboard, Authentication → Providers → Email, vous verrez l’interrupteur « Confirm Email ». Il détermine si l’utilisateur doit valider son e-mail après inscription pour se connecter. Sur un projet hébergé, c’est activé par défaut : un e-mail de confirmation arrive, le lien active le compte.

La première fois, je l’avais désactivé par erreur. Résultat : n’importe quelle adresse suffisait, et les comptes spam ont afflué. En production, cet interrupteur doit rester activé.

Le code est simple :

// Inscription avec déclenchement de la vérification e-mail
const { data, error } = await supabase.auth.signUp({
  email: '[email protected]',
  password: 'secure-password',
  options: {
    emailRedirectTo: 'https://yourapp.com/auth/callback'
  }
})

Un détail important : le paramètre emailRedirectTo. Après le clic sur le lien de l’e-mail, l’utilisateur est redirigé vers cette URL — page d’accueil ou page de bienvenue dédiée.

Côté modèles, Supabase fournit confirmation d’e-mail, réinitialisation de mot de passe et Magic Link. Vous les éditez dans Email Templates du Dashboard. Pour un SMTP perso (Resend, SendGrid), configurez Auth Hooks — c’est du niveau avancé ; les modèles par défaut suffisent au départ.

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

Piège que j’ai connu : en local, la vérification peut sembler bloquée, car l’instance locale n’envoie pas de vrais e-mails. Utilisez Mailcatcher pour les tests, ou désactivez Confirm Email en dev et réactivez-le avant la mise en production.

Intégration OAuth — connexion en un clic

OAuth améliore nettement l’expérience : pas de mot de passe à retenir, un clic GitHub ou Google, et la conversion dépasse souvent l’inscription par e-mail.

Supabase couvre de nombreux providers : GitHub, Google, Facebook, Apple, Azure, Twitter, Discord… plus de 15 au total. J’utilise surtout GitHub et Google, les flux les plus clairs.

Pour GitHub OAuth, créez d’abord une OAuth App (Settings → Developer settings → OAuth Apps → New OAuth App). La Callback URL doit être exacte :

https://<votre-ref-projet>.supabase.co/auth/v1/callback

En local :

http://localhost:54321/auth/v1/callback

Copiez Client ID et Client Secret dans le Dashboard (Authentication → Providers → GitHub). Côté client :

// Connexion GitHub OAuth
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'github',
  options: {
    redirectTo: 'https://yourapp.com/auth/callback'
  }
})

Google suit le même schéma, avec une nuance : des Client ID distincts pour Web, iOS et Android. Multi-plateforme implique plusieurs configs.

Après OAuth, Supabase fournit un provider token utilisable pour les API tierces — lister les dépôts GitHub, accéder à Google Drive, etc. Très pratique quand l’app s’appuie sur des services externes.

Piège fréquent en local : mauvaise callback URL. J’avais mis le port 3000 (frontend) ; l’erreur venait de là. La callback doit viser le port Supabase, pas celui du frontend.

Gestion de session — JWT et flux PKCE

C’est souvent la section la plus confuse. Au début, je ne voyais pas clairement comment JWT, refresh token et PKCE s’enchaînent.

Une session Supabase combine un access token (JWT court) et un refresh token (longue durée). L’access token expire par défaut après 1 heure ; la doc recommande de ne pas descendre sous 5 minutes (décalage d’horloge). Le refresh token est à usage unique et sert à obtenir un nouvel access token.

Point important : fenêtre de réutilisation de 10 secondes sur le refresh token. En SSR, si plusieurs requêtes rafraîchissent en parallèle, Supabase accepte les rafraîchissements répétés dans cette fenêtre sans couper la session — utile quand front et back manipulent la session en même temps.

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

PKCE : avec Next.js ou tout framework SSR, c’est indispensable. Le flux implicite expose le token dans l’URL, ce qui est risqué en SSR. PKCE protège l’échange via un code verifier.

À l’initialisation client, deux paramètres :

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
  auth: {
    detectSessionInUrl: true,
    flowType: 'pkce'
  }
})

Puis une route callback pour l’échange du code :

// Next.js App Router - app/auth/callback/route.ts
import { NextResponse } from 'next/server'
import { createClient } from '@/utils/supabase/server'

export async function GET(request: Request) {
  const { searchParams, origin } = new URL(request.url)
  const code = searchParams.get('code')

  if (code) {
    const supabase = await createClient()
    const { error } = await supabase.auth.exchangeCodeForSession(code)
    if (!error) {
      return NextResponse.redirect(`${origin}/dashboard`)
    }
  }
  return NextResponse.redirect(`${origin}/auth/error`)
}

L’auth code dure 5 minutes et ne s’échange qu’une fois. Échec au debug : souvent timeout ou réutilisation.

Supabase propose aussi trois modes de limitation : Time-boxed (expiration fixe), Inactivity timeout (inactivité prolongée), Single session per user (une session active par compte). Utile pour la conformité SOC 2 ou HIPAA.

Conseils pratiques et questions fréquentes

Quel mode choisir ?

En bref : e-mail pour une inscription avec profil complet ; OAuth pour une connexion rapide (outils dev, B2B) ; Magic Link pour le sans mot de passe (accès temporaire, mobile-first).

Comparaison :

Avec Next.js ou autre SSR, checklist :

1. detectSessionInUrl: true — Supabase extrait la session depuis l’URL
2. flowType: 'pkce' — force le flux PKCE
3. redirectTo correct — la route callback gère l’auth code
4. Variables d’environnement — NEXT_PUBLIC_SUPABASE_URL et NEXT_PUBLIC_SUPABASE_ANON_KEY renseignées

Questions courantes :

Q : Pourquoi OAuth échoue en local ?

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

Souvent une mauvaise callback URL. Vérifiez le Provider dans le Dashboard : localhost, pas le domaine de production.

Q : Déconnexion forcée à l’expiration du JWT ?

Assurez un rafraîchissement automatique. onAuthStateChange gère le refresh sans logique manuelle.

Q : La session disparaît soudainement ?

Fréquent en SSR. Vérifiez l’initialisation du client serveur et navigateur, surtout la transmission des cookies.

Conclusion

Les trois modes Supabase Auth ont chacun leur place. E-mail pour l’inscription formelle ; OAuth pour l’expérience rapide ; la gestion de session (JWT, PKCE) pour que tout tienne en SSR.

Mes erreurs étaient simples : mauvaise callback URL, Confirm Email oublié, PKCE absent. Une fois ces détails réglés, l’authentification tourne de façon stable.

Étape suivante : après Auth, protégez les données avec Row Level Security (RLS). RLS et Auth sont liés — chaque utilisateur n’accède qu’à ses données ; c’est la boucle complète de l’authentification.