> ## Documentation Index
> Fetch the complete documentation index at: https://translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Ce guide explique comment protéger des points de terminaison d’API Fastify à l’aide de jetons d’accès JWT avec le SDK d’API Fastify d’Auth0.
# Protégez votre API Fastify
export const HowToSchema = () => ;
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](https://agentskills.io/home).
**Installer :**
```bash theme={null}
npx skills add auth0/agent-skills --skill auth0
```
**Demandez ensuite à votre assistant IA :**
```text theme={null}
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 →](/docs/fr-ca/quickstart/agent-skills)
**Prérequis :** Avant de commencer, assurez-vous d’avoir installé ce qui suit :
* **[Node.js](https://nodejs.org/en/download)** 20 LTS ou une version plus récente
* **[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)** 10+ ou **[yarn](https://classic.yarnpkg.com/lang/en/docs/install/)** 1.22+ ou **[pnpm](https://pnpm.io/installation)** 8+
Vérifiez l’installation : `node --version && npm --version`
**Compatibilité 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éez un nouveau répertoire pour votre API Fastify et initialisez un projet Node.js.
```shellscript theme={null}
mkdir auth0-fastify-api && cd auth0-fastify-api
```
Initialiser le projet
```shellscript theme={null}
npm init -y
```
Créez l’arborescence du projet
```shellscript theme={null}
touch server.js .env
```
Installez les dépendances nécessaires
```shellscript theme={null}
npm install @auth0/auth0-fastify-api fastify dotenv
```
Mettez à jour votre `package.json` pour y ajouter des scripts de démarrage :
```json package.json theme={null}
{
"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"
}
}
```
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 :
Exécutez la commande suivante à la racine de votre projet pour créer une API Auth0 :
```shellscript Mac theme={null}
# 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
```
```powershell Windows theme={null}
# 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` :
```bash .env theme={null}
AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
AUTH0_AUDIENCE=YOUR_API_IDENTIFIER
```
Cette commande effectue les actions suivantes :
1. Vérifie si vous êtes authentifié(e) (et vous invite à vous connecter au besoin)
2. Crée une API Auth0 avec l’identifiant indiqué
3. Affiche les détails de l’API, y compris le domaine et l’identifiant
1. Accédez au [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
2. Allez à **Applications** → **APIs** → **Create API**
3. Entrez un nom pour votre API (p. ex., "My Fastify API")
4. 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
5. Laissez **Signing Algorithm** à **RS256**
6. Cliquez sur **Create**
7. Copiez la valeur **Identifier** dans l’onglet **Settings**
Créez votre fichier `.env` avec les valeurs suivantes :
```bash .env theme={null}
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)
Créez votre serveur Fastify et enregistrez le plugin de l’Auth0 API :
```javascript server.js {1-3,6-7,10-13,16-17} lines theme={null}
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
Ajoutez des routes publiques et protégées à votre `server.js` :
```javascript server.js expandable lines theme={null}
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
Démarrez le serveur de développement :
```shellscript theme={null}
npm run dev
```
Votre API est maintenant accessible à l’adresse [http://localhost:3001](http://localhost:3001).
L’option `--watch` de Node.js 20+ redémarre automatiquement le serveur lorsque les fichiers sont modifiés.
Testez le point de terminaison public (aucune authentification requise) :
```bash theme={null}
curl http://localhost:3001/api/public
```
Vous devriez voir :
```json theme={null}
{
"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) :
```bash theme={null}
curl http://localhost:3001/api/private
```
Vous devriez voir une erreur 401 Unauthorized :
```json theme={null}
{
"error": "Unauthorized",
"message": "No authorization token was found"
}
```
Pour tester avec un jeton valide, vous devez :
1. Créer une application cliente (application Web ou mobile) qui permet aux utilisateurs de s’authentifier
2. Configurer le client pour demander un jeton d’accès pour votre API (à l’aide du paramètre audience)
3. Utiliser ce jeton d’accès dans l’en-tête Authorization
Exemple avec un jeton :
```bash theme={null}
curl http://localhost:3001/api/private \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
**Vérification**
Vous devriez maintenant avoir une API protégée. Votre API :
1. Accepte les requêtes vers des points de terminaison publics sans authentification
2. Rejette les requêtes vers des points de terminaison protégés sans jeton valide
3. Valide les jetons JWT en fonction de votre domaine Auth0 et de votre audience
4. Fournit des renseignements sur l’utilisateur à partir des claims du jeton via `request.user`
***
## Utilisation avancée
Étendez l’interface Token pour ajouter un typage sûr à vos claims personnalisés dans vos jetons d’accès :
```typescript server.ts theme={null}
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 :
```typescript server.ts theme={null}
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](https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims).
Vérifiez les permissions précises dans le jeton d’accès :
```javascript server.js theme={null}
// 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](https://auth0.com/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-permissions-users).
Mettez en place le contrôle d’accès basé sur les rôles à l’aide de claims personnalisés :
```javascript server.js theme={null}
// 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](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow/add-user-roles-to-id-and-access-tokens).
Activez CORS pour autoriser les requêtes provenant d’applications web :
```bash theme={null}
npm install @fastify/cors
```
```javascript server.js theme={null}
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 :
```javascript server.js theme={null}
await fastify.register(cors, {
origin: [
'https://myapp.com',
'https://www.myapp.com'
],
credentials: true,
methods: ['GET', 'POST', 'PUT', 'DELETE'],
});
```
Ajoutez une gestion complète des erreurs d’authentification :
```javascript server.js theme={null}
// 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'
});
});
```
Protégez votre API contre les abus grâce à la limitation du nombre de requêtes :
```bash theme={null}
npm install @fastify/rate-limit
```
```javascript server.js theme={null}
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
### "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 :**
1. Assurez-vous que l’en-tête `Authorization` est présent : `Authorization: Bearer YOUR_TOKEN`
2. Vérifiez que "Bearer" figure bien avant le jeton
3. 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 :**
1. Assurez-vous d’utiliser un **jeton d’accès**, et non un ID token
2. Le jeton doit être obtenu avec le paramètre `audience` de votre API
3. 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 :**
1. Vérifiez que `AUTH0_DOMAIN` correspond au domaine qui a émis le jeton
2. Assurez-vous d’utiliser l’algorithme de signature RS256 (par défaut)
3. 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 :
```javascript theme={null}
// 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` :
```bash theme={null}
npm install @fastify/cors
```
```javascript theme={null}
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](/docs/fr-ca/quickstart/webapp/fastify)** - Créez une application web qui effectue des requêtes à votre API
* **[Contrôle d’accès basé sur les rôles](https://auth0.com/docs/manage-users/access-control/rbac)** - Implémentez des permissions granulaires
* **[Meilleures pratiques en matière d’autorisation des API](https://auth0.com/docs/secure/tokens/access-tokens)** - Découvrez les meilleures pratiques relatives aux jetons d’accès
* **[Surveillez votre API](https://auth0.com/docs/deploy-monitor/logs)** - Configurez la journalisation et la surveillance
***
## Ressources
* **[auth0-fastify-api GitHub](https://github.com/auth0/auth0-fastify/tree/main/packages/auth0-fastify-api)** - Code source et exemples
* **[Documentation de Fastify](https://fastify.dev/)** - En savoir plus sur Fastify
* **[Authentification de l’API Auth0](https://auth0.com/docs/secure/tokens/access-tokens)** - Comprendre les jetons d’accès
* **[Auth0 Community](https://community.auth0.com/)** - Obtenez de l’aide de la communauté