Intégration Auth0 Fastify API

Protégez les endpoints de votre API Fastify avec la validation de token JWT en utilisant @auth0/auth0-fastify-api.

Prérequis

• Application API Fastify (v5.x ou plus récent)
• Node.js 20 LTS ou plus récent
• Auth0 API configurée (pas Application - doit être une ressource API)
• Si vous n'avez pas encore configuré Auth0, utilisez d'abord la skill auth0-quickstart

Quand NE PAS utiliser

• Applications web server-rendered - Utilisez @auth0/auth0-fastify pour l'authentification par session
• Single Page Applications - Utilisez auth0-react, auth0-vue, ou auth0-angular pour l'authentification côté client
• Applications Next.js - Utilisez la skill auth0-nextjs
• Applications mobiles - Utilisez auth0-react-native pour React Native/Expo

Workflow Démarrage Rapide

1. Installer le SDK

npm install @auth0/auth0-fastify-api fastify dotenv

2. Créer une API Auth0

Vous avez besoin d'une API (pas Application) dans Auth0 :

# Utiliser Auth0 CLI
auth0 apis create \
  --name "My Fastify API" \
  --identifier https://my-api.example.com

Ou créez manuellement dans Auth0 Dashboard → Applications → APIs

3. Configurer l'environnement

Créez .env :

AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_AUDIENCE=https://my-api.example.com

4. Configurer le plugin Auth

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

import 'dotenv/config';
import Fastify from 'fastify';
import fastifyAuth0Api from '@auth0/auth0-fastify-api';

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

// Enregistrer le plugin Auth0 API
await fastify.register(fastifyAuth0Api, {
  domain: process.env.AUTH0_DOMAIN,
  audience: process.env.AUTH0_AUDIENCE,
});

fastify.listen({ port: 3001 });

5. Protéger les routes

// Route publique - pas d'authentification
fastify.get('/api/public', async (request, reply) => {
  return {
    message: 'Hello from a public endpoint!',
    timestamp: new Date().toISOString(),
  };
});

// Route protégée - nécessite un JWT valide
fastify.get('/api/private', {
  preHandler: fastify.requireAuth()
}, async (request, reply) => {
  return {
    message: 'Hello from a protected endpoint!',
    user: request.user.sub,
    timestamp: new Date().toISOString(),
  };
});

// Route protégée avec infos utilisateur
fastify.get('/api/profile', {
  preHandler: fastify.requireAuth()
}, async (request, reply) => {
  return {
    profile: request.user,  // JWT claims
  };
});

6. Tester l'API

Tester l'endpoint public :

curl http://localhost:3001/api/public

Tester l'endpoint protégé (nécessite un token d'accès) :

curl http://localhost:3001/api/private \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Erreurs courantes

Skills associées

• auth0-quickstart - Configuration Auth0 basique
• auth0-fastify - Pour les applications web Fastify server-rendered avec sessions
• auth0-mfa - Ajouter l'authentification multifacteur

Référence rapide

Options du plugin :

• domain - Domaine du tenant Auth0 (requis)
• audience - Identifiant de l'API depuis les paramètres Auth0 API (requis)

Propriétés de requête :

• request.user - Objet JWT claims décodé
• request.user.sub - ID utilisateur (subject)

Middleware :

• fastify.requireAuth() - Protéger une route avec la validation JWT
• fastify.requireAuth({ scopes: 'read:data' }) - Exiger un scope spécifique
• fastify.requireAuth({ scopes: ['read:data', 'write:data'] }) - Exiger des scopes spécifiques

Cas d'usage courants :

• Protéger les routes → Utiliser preHandler: fastify.requireAuth() (voir Étape 5)
• Obtenir l'ID utilisateur → request.user.sub
• Claims personnalisés → Accéder via request.user['namespace/claim']

Références

• Documentation Auth0 Fastify API
• Dépôt GitHub du SDK
• Guide des Access Tokens