Intégration Auth0 Fastify

Ajoutez l'authentification à vos applications web Fastify en utilisant @auth0/auth0-fastify.

Prérequis

Application Fastify (v5.x ou plus récent)
Node.js 20 LTS ou plus récent
Compte Auth0 et application configurés
Si vous n'avez pas encore configuré Auth0, utilisez d'abord la skill auth0-quickstart

Quand NE PAS l'utiliser

Applications monopage - Utilisez auth0-react, auth0-vue, ou auth0-angular pour l'auth côté client
Applications Next.js - Utilisez la skill auth0-nextjs qui gère le client et le serveur
Applications mobiles - Utilisez auth0-react-native pour React Native/Expo
APIs sans état - Utilisez @auth0/auth0-fastify-api à la place pour la validation JWT sans sessions
Microservices - Utilisez la validation JWT pour l'auth service-to-service

Workflow de démarrage rapide

1. Installer le SDK

npm install @auth0/auth0-fastify fastify @fastify/view ejs dotenv

2. Configurer l'environnement

Créez .env :

AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret
SESSION_SECRET=<openssl-rand-hex-64>
APP_BASE_URL=http://localhost:3000

Générer un secret : openssl rand -hex 64

3. Configurer le plugin Auth

Créez votre serveur Fastify (server.js) :

import 'dotenv/config';
import Fastify from 'fastify';
import fastifyAuth0 from '@auth0/auth0-fastify';
import fastifyView from '@fastify/view';
import ejs from 'ejs';

const fastify = Fastify({ logger: true });

// Register view engine
await fastify.register(fastifyView, {
  engine: { ejs },
  root: './views',
});

// Configure Auth0 plugin
await fastify.register(fastifyAuth0, {
  domain: process.env.AUTH0_DOMAIN,
  clientId: process.env.AUTH0_CLIENT_ID,
  clientSecret: process.env.AUTH0_CLIENT_SECRET,
  appBaseUrl: process.env.APP_BASE_URL,
  sessionSecret: process.env.SESSION_SECRET,
});

fastify.listen({ port: 3000 });

Cela crée automatiquement :

/auth/login - Endpoint de connexion
/auth/logout - Endpoint de déconnexion
/auth/callback - Callback OAuth

4. Ajouter des routes

// Route publique
fastify.get('/', async (request, reply) => {
  const session = await fastify.auth0Client.getSession({ request, reply });
  return reply.view('views/home.ejs', {
    isAuthenticated: !!session,
  });
});

// Route protégée
fastify.get('/profile', {
  preHandler: async (request, reply) => {
    const session = await fastify.auth0Client.getSession({ request, reply });
    if (!session) {
      return reply.redirect('/auth/login');
    }
  }
}, async (request, reply) => {
  const user = await fastify.auth0Client.getUser({ request, reply });
  return reply.view('views/profile.ejs', { user });
});

5. Tester l'authentification

Lancez votre serveur :

node server.js

Visitez http://localhost:3000 et testez le flux de connexion.

Erreurs courantes

Erreur	Solution
Oubli d'ajouter l'URL de callback dans le tableau de bord Auth0	Ajoutez le chemin `/auth/callback` à Allowed Callback URLs (ex. `http://localhost:3000/auth/callback`)
SESSION_SECRET manquant ou faible	Générez un secret sécurisé de 64 caractères avec `openssl rand -hex 64` et stockez-le dans .env
Application créée en tant que type SPA dans Auth0	Doit être du type Regular Web Application pour l'auth côté serveur
Secret de session exposé dans le code	Utilisez toujours des variables d'environnement, ne codez jamais les secrets en dur
appBaseUrl incorrect pour la production	Mettez à jour APP_BASE_URL pour correspondre à votre domaine de production
Oubli d'attendre fastify.register	Fastify v4+ nécessite d'attendre l'enregistrement du plugin

Skills connexes

auth0-quickstart - Configuration Auth0 de base
auth0-migration - Migration depuis un autre fournisseur d'auth
auth0-mfa - Ajouter l'authentification multi-facteurs

Référence rapide

Options du plugin :

domain - Domaine du tenant Auth0 (requis)
clientId - ID client Auth0 (requis)
clientSecret - Secret client Auth0 (requis)
appBaseUrl - URL de l'application (requis)
sessionSecret - Secret de chiffrement de session (requis, min 64 caractères)
audience - Audience API (optionnel, pour appeler des APIs)

Méthodes client :

fastify.auth0Client.getSession({ request, reply }) - Obtenir la session utilisateur
fastify.auth0Client.getUser({ request, reply }) - Obtenir le profil utilisateur
fastify.auth0Client.getAccessToken({ request, reply }) - Obtenir le token d'accès
fastify.auth0Client.logout(options, { request, reply }) - Déconnecter l'utilisateur

Cas d'usage courants :

Routes protégées → Utilisez preHandler pour vérifier la session (voir Étape 4)
Vérifier le statut d'auth → !!session
Obtenir les infos utilisateur → getUser({ request, reply })
Appeler des APIs → getAccessToken({ request, reply })

auth0-fastify