Protégez votre API Express.js

Ce guide explique comment protéger les points de terminaison d’une API Express.js à l’aide de jetons d’accès JWT avec le SDK express-oauth2-jwt-bearer.

Une nouvelle version Beta de ce Quickstart est maintenant offerte avec le SDK @auth0/auth0-express-api, qui remplacera bientôt ce guide. Essayer le Quickstart Beta →

Utiliser 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 de l’API Auth0 en quelques minutes à l’aide d’Agent Skills.

Installer :

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

Ensuite, demandez à votre assistant IA :

Add Auth0 JWT authentication to my Express API

Votre assistant IA créera automatiquement votre API Auth0, récupérera les identifiants, installera express-oauth2-jwt-bearer, configurera le middleware JWT et protégera vos points de terminaison d’API grâce à la validation des tokens. Documentation complète sur Agent Skills →

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

• Node.js 18 LTS ou une version ultérieure (prend en charge ^18.12.0 || ^20.2.0 || ^22.1.0 || ^24.0.0)
• npm 8+ ou yarn 1.22+ ou pnpm 8+

Vérifiez l’installation : node --version && npm --version

Compatibilité des versions d’Express : Ce Quickstart fonctionne avec Express 4.x et Express 5.x.

​

Pour commencer

Ce Quickstart montre comment protéger des points de terminaison d’API Express.js à l’aide de jetons d’accès JWT. Vous allez créer une API sécurisée qui valide les jetons d’accès Auth0, protège des routes et met en œuvre une autorisation basée sur les scopes.

1. Créer un nouveau projet

   Créez un nouveau répertoire pour votre API Express, puis initialisez un projet Node.js.

   mkdir auth0-express-api && cd auth0-express-api
   

   Initialiser le projet

   npm init -y
   

   Créer la structure du projet

   touch server.js .env
   
2. Installer le SDK express-oauth2-jwt-bearer

   Installez les dépendances nécessaires

   npm install express express-oauth2-jwt-bearer dotenv
   

   Ajoutez des scripts start à votre package.json :

   package.json

   {
     "scripts": {
       "start": "node server.js",
       "dev": "node --watch server.js"
     }
   }
   
3. 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 passer par le Dashboard manuellement :

   CLI

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

   Mac

   # 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 Express API" \
     --identifier https://my-express-api.example.com
   

   Cette commande va :

   1. Vérifier si vous êtes authentifié (et vous inviter à vous connecter au besoin)
   2. Créer une API Auth0 avec l’identifiant indiqué
   3. Afficher les détails de l’API, y compris le domaine et l’identifiant

   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
   

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

   Dashboard

   1. Accédez au Auth0 Dashboard
   2. Allez à Applications → APIs → Create API
   3. Saisissez un nom pour votre API (par exemple, “My Express API”)
   4. Définissez l’Identifier (par exemple, https://my-express-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 qu’il s’agisse d’une vraie URL : c’est simplement un identifiant
   5. Laissez Signing Algorithm à RS256
   6. Cliquez sur Create
   7. Copiez la valeur Identifier depuis 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 (par exemple, dev-abc123.us.auth0.com) et YOUR_API_IDENTIFIER par l’identifiant de votre API dans le dashboard (par exemple, https://my-express-api.example.com).

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

4. Configurer le middleware JWT

   Créez votre serveur Express et configurez la validation JWT :

   server.js

   require('dotenv').config();
   const express = require('express');
   const { auth } = require('express-oauth2-jwt-bearer');
   
   const app = express();
   const port = process.env.PORT || 3001;
   
   // Configurer le middleware de validation JWT
   const checkJwt = auth({
     issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
     audience: process.env.AUTH0_AUDIENCE,
   });
   
   // Démarrer le serveur
   app.listen(port, () => {
     console.log(`API server running at http://localhost:${port}`);
   });
   

   Ce que cela fait :

   • Crée un middleware de validation JWT à l’aide de votre domaine Auth0 et de l’audience de l’API
   • Valide les claims iss et aud des jetons d’accès reçus
   • Met checkJwt à disposition pour protéger des routes précises
5. Créer des routes d’API

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

   server.js

   require('dotenv').config();
   const express = require('express');
   const { auth, requiredScopes } = require('express-oauth2-jwt-bearer');
   
   const app = express();
   const port = process.env.PORT || 3001;
   
   // Configurer le middleware de validation JWT
   const checkJwt = auth({
     issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
     audience: process.env.AUTH0_AUDIENCE,
   });
   
   // Route publique - aucune authentification requise
   app.get('/api/public', (req, res) => {
     res.json({
       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 access token valide
   app.get('/api/private', checkJwt, (req, res) => {
     res.json({
       message: 'Hello from a protected endpoint! You successfully authenticated.',
       user: req.auth.payload.sub,
       timestamp: new Date().toISOString(),
     });
   });
   
   // Route protégée avec scope - nécessite le scope 'read:messages'
   app.get('/api/private-scoped', checkJwt, requiredScopes('read:messages'), (req, res) => {
     res.json({
       message: 'Hello from a scoped endpoint! You have the required permission.',
       user: req.auth.payload.sub,
       scope: req.auth.payload.scope,
       timestamp: new Date().toISOString(),
     });
   });
   
   // Middleware de gestion des erreurs
   app.use((err, req, res, next) => {
     const status = err.status || 500;
     const message = err.message || 'Internal Server Error';
   
     res.status(status).json({
       error: err.code || 'server_error',
       message: status === 401 ? 'Authentication required' : message,
     });
   });
   
   // Démarrer le serveur
   app.listen(port, () => {
     console.log(`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 le middleware checkJwt pour exiger un JWT valide
   • Les routes avec scopes utilisent requiredScopes() pour exiger des permissions précises dans le token
   • req.auth.payload contient les claims JWT décodés pour les requêtes authentifiées
   • Le claim sub contient l’identifiant unique de l’utilisateur
6. 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 18+ redémarre automatiquement le serveur lorsque des fichiers sont modifiés.

7. 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": "Authentication required"
   }
   

   Pour tester avec un jeton valide :

   1. Accédez à Auth0 Dashboard → Applications → APIs
   2. Sélectionnez votre API → onglet Test
   3. Copiez le jeton d’accès généré

   Testez votre point de terminaison protégé :

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

   Vous devriez voir :

   {
     "message": "Hello from a protected endpoint! You successfully authenticated.",
     "user": "auth0|abc123...",
     "timestamp": "2024-01-15T10:30:00.000Z"
   }
   

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 à l’aide de votre domaine Auth0 et de l’audience
4. Fournit des renseignements sur l’utilisateur à partir des claims du jeton au moyen de req.auth.payload

---

​

Utilisation avancée

Autorisation basée sur les scopes

Les scopes permettent un contrôle d’accès granulaire. Vous pouvez exiger des scopes précis pour différents points de terminaison.

Configurer les scopes dans Auth0 :

1. Dans le Auth0 Dashboard, accédez à Applications → APIs → votre API
2. Accédez à l’onglet Permissions
3. Ajoutez des permissions comme read:messages, write:messages, admin:access

Protéger des routes avec des scopes :

server.js

const { auth, requiredScopes } = require('express-oauth2-jwt-bearer');

// Exige le scope 'read:messages'
app.get('/api/messages', checkJwt, requiredScopes('read:messages'), (req, res) => {
  res.json({
    messages: [
      { id: 1, text: 'Hello!' },
      { id: 2, text: 'World!' },
    ],
  });
});

// Exige le scope 'admin:access'
app.get('/api/admin', checkJwt, requiredScopes('admin:access'), (req, res) => {
  res.json({
    message: 'Admin access granted',
    userId: req.auth.payload.sub,
  });
});

Si une requête ne contient pas le scope requis, l’API renvoie 403 Forbidden avec une erreur insufficient_scope. Assurez-vous que l’application cliente demande les bons scopes lors de l’obtention d’un jeton d’accès.

Validation de claims personnalisées

En plus des scopes, vous pouvez valider des claims personnalisées dans le payload JWT :

server.js

const { auth, claimEquals, claimIncludes, claimCheck } = require('express-oauth2-jwt-bearer');

// Exige une valeur exacte de claim
app.get('/api/org/:orgId',
  checkJwt,
  claimEquals('org_id', 'org_123'),
  (req, res) => {
    res.json({ message: 'Organization access granted' });
  }
);

// Exige que la claim inclue toutes les valeurs précisées
app.get('/api/roles',
  checkJwt,
  claimIncludes('roles', 'editor', 'viewer'),
  (req, res) => {
    res.json({ message: 'Role check passed' });
  }
);

// Logique de validation de claim personnalisée
app.get('/api/premium',
  checkJwt,
  claimCheck((claims) => {
    return claims.subscription === 'premium' && claims.verified === true;
  }),
  (req, res) => {
    res.json({ message: 'Premium feature access granted' });
  }
);

Les claims personnalisées doivent utiliser des URL avec espace de noms (p. ex., https://myapp.com/roles), à moins qu’il ne s’agisse de claims OIDC standard. En savoir plus sur les claims personnalisées.

Authentification facultative (routes publiques/privées mixtes)

Permettez l’accès authentifié et anonyme à une même route :

server.js

const optionalAuth = auth({
  issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
  audience: process.env.AUTH0_AUDIENCE,
  authRequired: false,
});

app.get('/api/feed', optionalAuth, (req, res) => {
  if (req.auth) {
    res.json({
      message: `Welcome back, ${req.auth.payload.sub}!`,
      personalizedContent: true,
    });
  } else {
    res.json({
      message: 'Welcome, guest!',
      personalizedContent: false,
    });
  }
});

Configuration CORS

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

npm install cors

server.js

const cors = require('cors');

app.use(cors({
  origin: ['http://localhost:3000', 'http://localhost:5173'],
  allowedHeaders: ['Authorization', 'Content-Type'],
  exposedHeaders: ['WWW-Authenticate'],
}));

En Production, précisez les origines exactes :

server.js

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

Gestion personnalisée des erreurs

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

server.js

const { UnauthorizedError, InvalidTokenError, InsufficientScopeError } = require('express-oauth2-jwt-bearer');

app.use((err, req, res, next) => {
  if (err instanceof InsufficientScopeError) {
    return res.status(403).json({
      error: 'forbidden',
      message: 'You do not have permission to access this resource',
      required_scopes: err.requiredScopes,
    });
  }

  if (err instanceof InvalidTokenError) {
    return res.status(401).json({
      error: 'invalid_token',
      message: 'The provided token is invalid or expired',
    });
  }

  if (err instanceof UnauthorizedError) {
    return res.status(401).set(err.headers).json({
      error: 'unauthorized',
      message: 'Authentication required',
    });
  }

  next(err);
});

Prise en charge de TypeScript

Pour les projets TypeScript, installez les définitions de types et configurez votre projet :

npm install -D typescript @types/express @types/node

Créez server.ts :

server.ts

import 'dotenv/config';
import express, { Request, Response, NextFunction } from 'express';
import { auth, requiredScopes, UnauthorizedError } from 'express-oauth2-jwt-bearer';

const app = express();
const port = process.env.PORT || 3001;

const checkJwt = auth({
  issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
  audience: process.env.AUTH0_AUDIENCE,
});

app.get('/api/public', (req: Request, res: Response) => {
  res.json({ message: 'Public endpoint - no authentication required' });
});

app.get('/api/private', checkJwt, (req: Request, res: Response) => {
  res.json({
    message: 'Private endpoint',
    user: req.auth?.payload.sub,
  });
});

app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  if (err instanceof UnauthorizedError) {
    res.status(err.status).set(err.headers).json({
      error: err.code || 'unauthorized',
      message: 'Authentication required',
    });
  } else {
    res.status(500).json({
      error: 'server_error',
      message: 'Internal Server Error',
    });
  }
});

app.listen(port, () => {
  console.log(`API server running at http://localhost:${port}`);
});

Ajoutez un tsconfig.json :

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist"
  },
  "include": ["*.ts"]
}

Exécutez avec : npx ts-node server.ts

---

​

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 :

1. Assurez-vous que l’en-tête Authorization est présent : Authorization: Bearer YOUR_TOKEN
2. Vérifiez que “Bearer” est bien indiqué 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)

​

Valeur “iss” ou “aud” inattendue

Problème : L’émetteur ou l’audience du jeton ne correspond pas à votre configuration.

Solutions :

1. Décodez votre jeton sur jwt.io
2. Vérifiez que la claim iss correspond à https://YOUR_AUTH0_DOMAIN/ (notez la barre oblique à la fin)
3. Vérifiez que la claim aud correspond exactement à votre AUTH0_AUDIENCE
4. Vérifiez les valeurs de votre .env :

AUTH0_DOMAIN=dev-abc123.us.auth0.com
AUTH0_AUDIENCE=https://my-express-api.example.com

​

“You must provide an issuerBaseURL” ou “audience is required”

Problème : Les variables d’environnement ne sont pas chargées.

Solutions :

1. Assurez-vous que le fichier .env existe à la racine de votre projet
2. Vérifiez que dotenv est installé : npm install dotenv
3. Ajoutez require('dotenv').config() tout en haut de votre fichier serveur
4. Vérifiez que les noms de variables correspondent exactement, y compris la casse

​

401 Unauthorized pour toutes les requêtes

Causes possibles :

• Le jeton est expiré
• L’audience ne correspond pas
• L’émetteur ne correspond pas

Étapes de débogage :

1. Décodez votre jeton sur jwt.io
2. Vérifiez que la claim exp n’est pas expirée
3. Vérifiez que la claim aud correspond exactement à votre AUTH0_AUDIENCE
4. Vérifiez que la claim iss est https://{AUTH0_DOMAIN}/
5. Assurez-vous que le format de l’en-tête Authorization est Bearer YOUR_TOKEN (avec un espace)

​

403 Forbidden avec “insufficient_scope”

Problème : Le jeton n’a pas les scopes requis.

Solutions :

1. Vérifiez que les scopes sont définis dans votre API Auth0 (Dashboard → Applications → APIs → Permissions)
2. Demandez les scopes au moment d’obtenir le jeton
3. Vérifiez que la claim scope du jeton inclut les scopes requis

​

Erreurs CORS dans le navigateur

Problème : Le navigateur bloque les requêtes API en raison de la politique CORS.

Solution : Installez et configurez cors :

npm install cors

const cors = require('cors');

app.use(cors({
  origin: 'http://localhost:3000',
}));

---

​

Prochaines étapes

Maintenant que vous avez une API protégée, songez à explorer :

• Contrôle d’accès basé sur les rôles - Mettez en œuvre des permissions granulaires
• Pratiques exemplaires en matière d’autorisation des API - Découvrez les pratiques exemplaires relatives aux jetons d’accès
• Surveillez votre API - Configurez la journalisation et la surveillance
• Auth0 Community - Obtenez de l’aide auprès de la communauté

---

​

Ressources

• express-oauth2-jwt-bearer GitHub - Code source et exemples
• Documentation d’Express.js - Pour en savoir plus sur Express
• Authentification de l’API Auth0 - Comprendre les jetons d’accès
• JWT.io - Déboguer et décoder les JWT