Protégez votre API Fastify

Utilisez l’IA pour intégrer Auth0

Si vous utilisez un assistant de codage IA comme Claude Code, Cursor ou GitHub Copilot, vous pouvez ajouter automatiquement l’authentification API avec Auth0 en quelques minutes à l’aide d’Agent Skills.Installer :

npx skills add auth0/agent-skills --skill auth0

Demandez ensuite à votre assistant IA :

Add Auth0 JWT authentication to my Fastify API

Votre assistant IA créera automatiquement votre API Auth0, récupérera les informations d’identification, installera @auth0/auth0-fastify-api, configurera le plugin et protégera vos points de terminaison d’API à l’aide de la validation des JWT. Documentation complète sur Agent Skills →

Prérequis : Avant de commencer, assurez-vous d’avoir installé ce qui suit :

Node.js 20 LTS ou une version plus récente
npm 10+ ou yarn 1.22+ ou pnpm 8+

Vérifiez l’installation : node --version && npm --versionCompatibilité avec les versions de Fastify : Ce guide de démarrage rapide fonctionne avec Fastify 5.x et les versions ultérieures.

Pour commencer

Ce guide de démarrage rapide montre comment protéger des points de terminaison d’API Fastify à l’aide de jetons d’accès JWT. Vous créerez une API sécurisée qui valide les jetons d’accès Auth0 et donne accès à des ressources protégées.

Créer un nouveau projet

Créez un nouveau répertoire pour votre API Fastify et initialisez un projet Node.js.

mkdir auth0-fastify-api && cd auth0-fastify-api

Initialiser le projet

npm init -y

Créez l’arborescence du projet

touch server.js .env

Installez le SDK d’API Auth0 pour Fastify

Installez les dépendances nécessaires

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

Mettez à jour votre package.json pour y ajouter des scripts de démarrage :

package.json

{
  "name": "auth0-fastify-api",
  "version": "1.0.0",
  "type": "module",
  "main": "server.js",
  "scripts": {
    "start": "node server.js",
    "dev": "node --watch server.js"
  },
  "dependencies": {
    "@auth0/auth0-fastify-api": "^1.2.0",
    "dotenv": "^16.3.1",
    "fastify": "^5.0.0"
  }
}

Configurez votre API Auth0

Ensuite, vous devez créer une nouvelle API dans votre tenant Auth0 et ajouter les variables d’environnement à votre projet.Vous avez deux options pour configurer votre API Auth0 : utiliser une commande CLI ou la configurer manuellement dans le Dashboard :

CLI
Dashboard

Exécutez la commande suivante à la racine de votre projet pour créer une API Auth0 :

# Installer Auth0 CLI (si ce n’est pas déjà fait)
brew tap auth0/auth0-cli && brew install auth0

# Créer une API Auth0
auth0 apis create \
  --name "My Fastify API" \
  --identifier https://my-fastify-api.example.com

# Installer Auth0 CLI (si ce n’est pas déjà fait)
scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
scoop install auth0

# Créer une API Auth0
auth0 apis create `
  --name "My Fastify API" `
  --identifier https://my-fastify-api.example.com

Une fois l’API créée, copiez les valeurs Identifier et Domain, puis créez votre fichier .env :

.env

AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
AUTH0_AUDIENCE=YOUR_API_IDENTIFIER

Cette commande effectue les actions suivantes :

Vérifie si vous êtes authentifié(e) (et vous invite à vous connecter au besoin)
Crée une API Auth0 avec l’identifiant indiqué
Affiche les détails de l’API, y compris le domaine et l’identifiant

Accédez au Auth0 Dashboard
Allez à Applications → APIs → Create API
Entrez un nom pour votre API (p. ex., “My Fastify API”)
Définissez l’Identifier (p. ex., https://my-fastify-api.example.com)
- Il s’agit de l’audience de votre API et elle doit respecter un format d’URL valide
- Il n’est pas nécessaire que ce soit une vraie URL — c’est simplement un identifiant
Laissez Signing Algorithm à RS256
Cliquez sur Create
Copiez la valeur Identifier dans l’onglet Settings

Créez votre fichier .env avec les valeurs suivantes :

.env

AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
AUTH0_AUDIENCE=YOUR_API_IDENTIFIER

Remplacez YOUR_AUTH0_DOMAIN par le domaine de votre tenant Auth0 (p. ex., dev-abc123.us.auth0.com) et YOUR_API_IDENTIFIER par l’identifiant de votre API dans le dashboard (p. ex., https://my-fastify-api.example.com).

Vérifiez que votre fichier .env existe : cat .env (Mac/Linux) ou type .env (Windows)

Configurer le plugin de l’API Auth0

Créez votre serveur Fastify et enregistrez le plugin de l’Auth0 API :

server.js

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

const fastify = Fastify({ logger: true });
const port = process.env.PORT || 3001;

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

// Démarrer le serveur
fastify.listen({ port }, (err) => {
  if (err) {
    fastify.log.error(err);
    process.exit(1);
  }
  fastify.log.info(`API server running at http://localhost:${port}`);
});

Ce que cela fait :

Enregistre le plugin Auth0 API avec votre domaine Auth0 et l’audience de l’API
Configure la validation des JWT pour les requêtes entrantes
Met le preHandler requireAuth() à disposition pour protéger les routes

Créer des routes d’API

Ajoutez des routes publiques et protégées à votre server.js :

server.js

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

const fastify = Fastify({ logger: true });
const port = process.env.PORT || 3001;

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

// Route publique - aucune authentification requise
fastify.get('/api/public', async (request, reply) => {
  return {
    message: 'Hello from a public endpoint! You don\'t need to be authenticated to see this.',
    timestamp: new Date().toISOString(),
  };
});

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

// Route protégée - retourne les informations de l'utilisateur à partir du jeton
fastify.get('/api/profile', {
  preHandler: fastify.requireAuth()
}, async (request, reply) => {
  return {
    message: 'Your user profile from the access token',
    profile: request.user,
  };
});

// Démarrer le serveur
fastify.listen({ port }, (err) => {
  if (err) {
    fastify.log.error(err);
    process.exit(1);
  }
  fastify.log.info(`API server running at http://localhost:${port}`);
});

Points clés :

Les routes publiques ne nécessitent pas d’authentification
Les routes protégées utilisent preHandler: fastify.requireAuth() pour exiger un JWT valide
request.user contient les claims décodés du JWT pour les requêtes authentifiées
Le champ sub contient l’identifiant unique de l’utilisateur

Lancez votre API

Démarrez le serveur de développement :

npm run dev

Votre API est maintenant accessible à l’adresse http://localhost:3001.

L’option --watch de Node.js 20+ redémarre automatiquement le serveur lorsque les fichiers sont modifiés.

Testez votre API

Testez le point de terminaison public (aucune authentification requise) :

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

Vous devriez voir :

{
  "message": "Hello from a public endpoint! You don't need to be authenticated to see this.",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Testez l’endpoint protégé sans token (cela devrait échouer) :

curl http://localhost:3001/api/private

Vous devriez voir une erreur 401 Unauthorized :

{
  "error": "Unauthorized",
  "message": "No authorization token was found"
}

Pour tester avec un jeton valide, vous devez :

Créer une application cliente (application Web ou mobile) qui permet aux utilisateurs de s’authentifier
Configurer le client pour demander un jeton d’accès pour votre API (à l’aide du paramètre audience)
Utiliser ce jeton d’accès dans l’en-tête Authorization

Exemple avec un jeton :

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

VérificationVous devriez maintenant avoir une API protégée. Votre API :

Accepte les requêtes vers des points de terminaison publics sans authentification
Rejette les requêtes vers des points de terminaison protégés sans jeton valide
Valide les jetons JWT en fonction de votre domaine Auth0 et de votre audience
Fournit des renseignements sur l’utilisateur à partir des claims du jeton via request.user

Utilisation avancée

Claims de jeton personnalisés avec TypeScript

Étendez l’interface Token pour ajouter un typage sûr à vos claims personnalisés dans vos jetons d’accès :

server.ts

import '@auth0/auth0-fastify-api';

// Étendez l’interface Token avec vos claims personnalisés
declare module '@auth0/auth0-fastify-api' {
  interface Token {
    sub: string;
    permissions?: string[];
    'https://myapp.com/roles'?: string[];
    email?: string;
    email_verified?: boolean;
  }
}

TypeScript reconnaîtra maintenant vos claims personnalisés :

server.ts

fastify.get('/api/profile', {
  preHandler: fastify.requireAuth()
}, async (request, reply) => {
  // TypeScript reconnaît ces propriétés
  const userRoles = request.user['https://myapp.com/roles']; // string[] | undefined
  const permissions = request.user.permissions; // string[] | undefined
  const email = request.user.email; // string | undefined

  return {
    userId: request.user.sub,
    roles: userRoles || [],
    permissions: permissions || [],
    email: email,
  };
});

Les claims personnalisés doivent utiliser des URL avec espace de noms (par ex., https://myapp.com/roles), sauf s’il s’agit de claims OIDC standards. En savoir plus sur les claims personnalisés.

Autorisation basée sur les permissions

Vérifiez les permissions précises dans le jeton d’accès :

server.js

// Middleware pour vérifier une permission précise
function requirePermission(permission) {
  return async (request, reply) => {
    const permissions = request.user.permissions || [];

    if (!permissions.includes(permission)) {
      return reply.status(403).send({
        error: 'Forbidden',
        message: `Missing required permission: ${permission}`
      });
    }
  };
}

// Route nécessitant la permission 'read:messages'
fastify.get('/api/messages', {
  preHandler: [
    fastify.requireAuth(),
    requirePermission('read:messages')
  ]
}, async (request, reply) => {
  return {
    messages: ['Message 1', 'Message 2', 'Message 3']
  };
});

// Route nécessitant la permission 'write:messages'
fastify.post('/api/messages', {
  preHandler: [
    fastify.requireAuth(),
    requirePermission('write:messages')
  ]
}, async (request, reply) => {
  return {
    message: 'Message created successfully',
    id: 'msg_123'
  };
});

Les permissions doivent être configurées dans les paramètres de votre Auth0 API et accordées aux clients. En savoir plus sur les permissions d’API.

Autorisation basée sur les rôles

Mettez en place le contrôle d’accès basé sur les rôles à l’aide de claims personnalisés :

server.js

// Middleware pour vérifier un rôle précis
function requireRole(role) {
  return async (request, reply) => {
    const roles = request.user['https://myapp.com/roles'] || [];

    if (!roles.includes(role)) {
      return reply.status(403).send({
        error: 'Forbidden',
        message: `Missing required role: ${role}`
      });
    }
  };
}

// Route réservée aux admins
fastify.get('/api/admin/users', {
  preHandler: [
    fastify.requireAuth(),
    requireRole('admin')
  ]
}, async (request, reply) => {
  return {
    users: [
      { id: 1, name: 'User 1' },
      { id: 2, name: 'User 2' }
    ]
  };
});

// Route accessible au gestionnaire ou à l’admin
function requireAnyRole(...roles) {
  return async (request, reply) => {
    const userRoles = request.user['https://myapp.com/roles'] || [];
    const hasRole = roles.some(role => userRoles.includes(role));

    if (!hasRole) {
      return reply.status(403).send({
        error: 'Forbidden',
        message: `Missing required role. Need one of: ${roles.join(', ')}`
      });
    }
  };
}

fastify.get('/api/reports', {
  preHandler: [
    fastify.requireAuth(),
    requireAnyRole('admin', 'manager')
  ]
}, async (request, reply) => {
  return { reports: [] };
});

Les rôles doivent être ajoutés aux jetons à l’aide d’Auth0 Actions. Découvrez comment ajouter des rôles aux jetons.

Configuration de CORS

Activez CORS pour autoriser les requêtes provenant d’applications web :

npm install @fastify/cors

server.js

import cors from '@fastify/cors';

await fastify.register(cors, {
  origin: ['http://localhost:3000', 'http://localhost:5173'], // URL de votre application web
  credentials: true,
});

En production, précisez les origines exactes :

server.js

await fastify.register(cors, {
  origin: [
    'https://myapp.com',
    'https://www.myapp.com'
  ],
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
});

Gestion des erreurs

Ajoutez une gestion complète des erreurs d’authentification :

server.js

// Gestionnaire d’erreurs personnalisé
fastify.setErrorHandler((error, request, reply) => {
  fastify.log.error(error);

  // Gérer les erreurs de validation JWT
  if (error.statusCode === 401) {
    return reply.status(401).send({
      error: 'Unauthorized',
      message: error.message || 'Invalid or missing access token',
      code: 'UNAUTHORIZED'
    });
  }

  // Gérer les erreurs de permission ou de rôle
  if (error.statusCode === 403) {
    return reply.status(403).send({
      error: 'Forbidden',
      message: error.message || 'Insufficient permissions',
      code: 'FORBIDDEN'
    });
  }

  // Gérer les autres erreurs
  return reply.status(error.statusCode || 500).send({
    error: 'Internal Server Error',
    message: 'An unexpected error occurred',
    code: 'INTERNAL_ERROR'
  });
});

// Gestionnaire pour les routes introuvables
fastify.setNotFoundHandler((request, reply) => {
  return reply.status(404).send({
    error: 'Not Found',
    message: `Route ${request.method} ${request.url} not found`,
    code: 'NOT_FOUND'
  });
});

Limitation du nombre de requêtes

Protégez votre API contre les abus grâce à la limitation du nombre de requêtes :

npm install @fastify/rate-limit

server.js

import rateLimit from '@fastify/rate-limit';

await fastify.register(rateLimit, {
  max: 100, // Nombre maximal de requêtes
  timeWindow: '1 minute', // Fenêtre de temps
  errorResponseBuilder: (request, context) => {
    return {
      error: 'Too Many Requests',
      message: `Rate limit exceeded. Try again in ${context.after}`,
      retryAfter: context.after
    };
  }
});

// Appliquer des limites plus strictes à certaines routes
fastify.get('/api/expensive-operation', {
  preHandler: fastify.requireAuth(),
  config: {
    rateLimit: {
      max: 10,
      timeWindow: '1 minute'
    }
  }
}, async (request, reply) => {
  return { result: 'expensive operation result' };
});

Dépannage

Problèmes courants et solutions

”Aucun jeton d’autorisation n’a été trouvé”

Problème : L’API ne trouve pas le jeton d’accès dans la requête.Solutions :

Assurez-vous que l’en-tête Authorization est présent : Authorization: Bearer YOUR_TOKEN
Vérifiez que “Bearer” figure bien avant le jeton
Vérifiez que le jeton n’est pas expiré

”Jeton invalide” ou “jwt malformed”

Problème : Le format du jeton n’est pas valide.Solutions :

Assurez-vous d’utiliser un jeton d’accès, et non un ID token
Le jeton doit être obtenu avec le paramètre audience de votre API
Vérifiez que le jeton est un JWT valide (il doit comporter trois parties séparées par des points)

“Signature invalide”

Problème : La signature du jeton ne correspond pas.Solutions :

Vérifiez que AUTH0_DOMAIN correspond au domaine qui a émis le jeton
Assurez-vous d’utiliser l’algorithme de signature RS256 (par défaut)
Vérifiez que le jeton n’a pas été modifié

”Audience invalide”

Problème : L’audience du jeton ne correspond pas à votre API.Solution : L’application cliente doit demander un jeton avec la bonne audience :

// Dans votre application cliente
const token = await getAccessTokenSilently({
  authorizationParams: {
    audience: 'https://my-fastify-api.example.com' // Doit correspondre à votre identifiant d’API
  }
});

Erreurs CORS dans le navigateur

Problème : Le navigateur bloque les requêtes API à cause de la politique CORS.Solution : Installez et configurez @fastify/cors :

npm install @fastify/cors

import cors from '@fastify/cors';

await fastify.register(cors, {
  origin: 'http://localhost:3000', // URL de votre interface utilisateur
  credentials: true
});

Prochaines étapes

Maintenant que vous disposez d’une API protégée, vous pourriez explorer :

Quickstart d’application web Fastify - Créez une application web qui effectue des requêtes à votre API
Contrôle d’accès basé sur les rôles - Implémentez des permissions granulaires
Meilleures pratiques en matière d’autorisation des API - Découvrez les meilleures pratiques relatives aux jetons d’accès
Surveillez votre API - Configurez la journalisation et la surveillance

Ressources

auth0-fastify-api GitHub - Code source et exemples
Documentation de Fastify - En savoir plus sur Fastify
Authentification de l’API Auth0 - Comprendre les jetons d’accès
Auth0 Community - Obtenez de l’aide de la communauté

Quickstarts

Aperçu d’Auth0

Configurer Auth0

Applications

Protégez votre API Fastify

Pour commencer

Utilisation avancée

Dépannage

”Aucun jeton d’autorisation n’a été trouvé”

”Jeton invalide” ou “jwt malformed”

“Signature invalide”

”Audience invalide”

Erreurs CORS dans le navigateur

Prochaines étapes

Ressources

​Pour commencer

​Utilisation avancée

​Dépannage

​”Aucun jeton d’autorisation n’a été trouvé”

​”Jeton invalide” ou “jwt malformed”

​“Signature invalide”

​”Audience invalide”

​Erreurs CORS dans le navigateur

​Prochaines étapes

​Ressources

Pour commencer

Utilisation avancée

Dépannage

”Aucun jeton d’autorisation n’a été trouvé”

”Jeton invalide” ou “jwt malformed”

“Signature invalide”

”Audience invalide”

Erreurs CORS dans le navigateur

Prochaines étapes

Ressources