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 et du SDK @auth0/auth0-express-api (bêta).

Ce Quickstart est actuellement en bêta. Nous aimerions connaître vos commentaires!

Prérequis : Avant de commencer, assurez-vous d’avoir installé les éléments suivants :

• Node.js 22 LTS ou une version ultérieure
• npm 10+ ou yarn 1.22+

​

Premiers pas

Ce Quickstart explique comment protéger des point de terminaison d’API Express.js à l’aide de jetons d’accès JWT. Vous créerez une API sécurisée qui valide les jetons d’accès Auth0, protège les routes et implémente une autorisation fondée sur les scopes et les claims.

1. Créer un nouveau projet

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

   Mettez à jour votre fichier package.json pour utiliser les modules ES et ajoutez des scripts de démarrage :

   {
     "name": "auth0-express-api",
     "version": "1.0.0",
     "type": "module",
     "main": "server.js",
     "scripts": {
       "start": "node server.js",
       "dev": "node --watch server.js"
     }
   }
   
2. Installer le SDK

   Installez @auth0/auth0-express-api, ainsi que express et dotenv :

   npm install @auth0/auth0-express-api@beta express dotenv
   
3. Configurez votre API Auth0

   Vous devez créer une API dans votre tenant Auth0 et configurer vos variables d’environnement.

   CLI

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

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

   Remplacez YOUR_API_IDENTIFIER par l’identifiant utilisé ci-dessus (par exemple, https://my-express-api.example.com).

   Dashboard

   1. Accédez à Auth0 Dashboard → Applications > APIs → Create API
   2. Entrez un nom (par exemple, “My Express API”)
   3. Définissez l’Identifier : il s’agit de l’audience de votre API (par exemple, https://my-express-api.example.com). Il n’a pas besoin d’être une véritable URL.
   4. Laissez Signing Algorithm à RS256
   5. Cliquez sur Create
   6. Copiez le Domain de votre tenant et l’Identifier dans API Settings

   Créez votre fichier .env :

   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 l’API défini ci-dessus.

4. Configurer le middleware JWT

   Enregistrez createAuth0Api() dans votre application Express pour configurer la validation des JWT. Ajoutez ensuite des routes publiques et protégées.

   server.js

   import 'dotenv/config';
   import express from 'express';
   import { createAuth0Api, requiresAuth } from '@auth0/auth0-express-api';
   
   const app = express();
   const port = process.env.PORT || 3001;
   
   app.use(express.json());
   app.use(createAuth0Api());
   
   // Route publique — aucun token requis
   app.get('/api/public', (req, res) => {
     res.json({
       message: 'Hello from a public endpoint! No authentication required.',
       timestamp: new Date().toISOString(),
     });
   });
   
   // Route protégée — requiert un access token valide
   app.get('/api/private', requiresAuth(), (req, res) => {
     res.json({
       message: 'Hello from a protected endpoint! You are authenticated.',
       sub: req.auth0.user?.sub,
       timestamp: new Date().toISOString(),
     });
   });
   
   app.listen(port, () => {
     console.log(`API server running at http://localhost:${port}`);
   });
   

   Fonctionnement :

   • createAuth0Api() lit automatiquement AUTH0_DOMAIN et AUTH0_AUDIENCE depuis les variables d’environnement
   • requiresAuth() valide l’en-tête Authorization: Bearer <token> de chaque requête
   • req.auth0.user contient les claims JWT décodés des requêtes authentifiées — sub est l’identifiant unique de l’utilisateur
5. Protéger une route avec un scope requis

   En plus d’exiger un token valide, vous pouvez exiger un scope précis. Passez l’option scopes à requiresAuth() : le SDK renvoie 403 insufficient_scope si le token ne comprend pas ce scope.

   server.js

   // Requiert le scope « read:messages »
   app.get('/api/messages', requiresAuth({ scopes: ['read:messages'] }), (req, res) => {
     res.json({ messages: ['Hello!', 'World!'] });
   });
   

   Définissez la portée dans l’onglet Permissions de votre API (consultez Utilisation avancée) et demandez-la lors de l’obtention du jeton d’accès. Pour faire correspondre plusieurs portées ou autoriser en fonction de revendications personnalisées, le SDK offre également scopesInclude, claimEquals, claimIncludes et claimCheck — décrits dans Utilisation avancée.

6. Exécutez votre API

   Démarrez le serveur de développement :

   npm run dev
   

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

7. Testez votre API

   Testez le endpoint public (aucun token requis) :

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

   Réponse attendue :

   {
     "message": "Hello from a public endpoint! No authentication required.",
     "timestamp": "2026-06-22T12:00:00.000Z"
   }
   

   Pour envoyer une requête à l’endpoint protégé, vous avez besoin d’un jeton d’accès :

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

   Testez l’endpoint protégé :

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

   Réponse attendue :

   {
     "message": "Hello from a protected endpoint! You are authenticated.",
     "sub": "auth0|abc123...",
     "timestamp": "2026-06-22T12:00:00.000Z"
   }
   

   Point de contrôle

   Vous devriez maintenant disposer d’une API protégée. Votre API :

   1. Accepte les requêtes vers des endpoints publics sans token
   2. Renvoie la réponse protégée lorsqu’un access token valide est fourni
   3. Valide les JWT par rapport à votre domaine Auth0 et à votre audience
   4. Expose les claims décodés du token via req.auth0.user

---

​

Utilisation avancée

Faire correspondre plusieurs scopes avec scopesInclude

Utilisez scopesInclude lorsqu’une route doit accepter l’un de plusieurs scopes ou en exiger plusieurs à la fois. Par défaut, cette fonction vérifie la présence d’au moins un des scopes indiqués; transmettez { match: 'all' } pour les exiger tous. Les scopes peuvent être fournis sous forme de tableau ou de chaîne séparée par des espaces — ces exemples utilisent des tableaux.

server.js

import { scopesInclude } from '@auth0/auth0-express-api';

// Nécessite L'UN de ces scopes
app.get('/api/feed', requiresAuth(), scopesInclude(['read:feed', 'read:admin']), (req, res) => {
  res.json({ feed: [] });
});

// Nécessite TOUS ces scopes
app.get('/api/admin/edit', requiresAuth(), scopesInclude(['read:admin', 'write:admin'], { match: 'all' }), (req, res) => {
  res.json({ message: 'Admin editor access granted.' });
});

Autoriser selon des claims personnalisés

Lorsque l’autorisation dépend de claims autres que scope, utilisez claimEquals, claimIncludes ou claimCheck. Ces fonctions s’exécutent après requiresAuth() et renvoient 401 invalid_token si l’exigence relative au claim n’est pas satisfaite.

server.js

import { claimEquals, claimIncludes, claimCheck } from '@auth0/auth0-express-api';

// claimEquals — le claim doit correspondre exactement à une valeur
app.get('/api/admin', requiresAuth(), claimEquals('isAdmin', true), (req, res) => {
  res.json({ message: 'Admin access granted.' });
});

// claimIncludes — le claim sous forme de tableau doit contenir toutes les valeurs indiquées
app.get('/api/editor', requiresAuth(), claimIncludes('roles', ['admin', 'editor']), (req, res) => {
  res.json({ message: 'Editor access granted.' });
});

// claimCheck — logique personnalisée appliquée au jeton décodé
app.get('/api/premium', requiresAuth(), claimCheck(
  (req, token) => token.tier === 'premium' || token.roles?.includes('admin'),
  { errorMessage: 'Premium tier or admin role required' }
), (req, res) => {
  res.json({ message: 'Premium content access granted.' });
});

Définir des claims de jeton personnalisés avec TypeScript

Si vous utilisez TypeScript, étendez l’interface Token pour accéder aux claims personnalisés de façon sécuritaire du point de vue des types :

server.ts

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

declare module '@auth0/auth0-express-api' {
  interface Token {
    tier: 'free' | 'premium';
    roles: string[];
    'https://myapp.com/org_id': string;
  }
}

Installez la prise en charge des types :

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

Configuration CORS pour les clients Web

Activez CORS pour permettre à votre application Web d’appeler l’API :

npm install cors

server.js

import cors from 'cors';

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

app.use(createAuth0Api());

En production, indiquez les origines autorisées exactes plutôt que d’utiliser des caractères génériques.

Configurer les scopes dans Auth0 Dashboard

Pour utiliser l’autorisation basée sur les scopes, commencez par définir les permissions de votre API :

1. Accédez à Auth0 Dashboard → Applications > APIs → votre API
2. Ouvrez l’onglet Permissions
3. Ajoutez des permissions telles que read:messages, write:messages, read:admin
4. Cliquez sur Save

Votre application cliente doit ensuite demander ces scopes lors de l’obtention d’un jeton d’accès. Si un jeton ne contient pas le scope requis, l’API renvoie 403 Forbidden.

---

​

Dépannage

401 avec un corps de réponse vide et seulement l’en-tête « WWW-Authenticate: Bearer »

Cause : L’en-tête Authorization est absent ou mal formé, de sorte qu’aucun jeton porteur n’a pu être extrait. Conformément à la RFC 6750, le SDK renvoie dans ce cas un 401 avec seulement l’en-tête WWW-Authenticate: Bearer et aucun corps d’erreur. Ce cas est distinct de celui où un jeton est présent, mais non valide ou expiré, qui renvoie un 401 avec l’erreur invalid_token et un corps JSON (voir ci-dessous).

Correctif :

1. Assurez-vous que l’en-tête est présent : Authorization: Bearer YOUR_TOKEN
2. Vérifiez que « Bearer » (avec un B majuscule et une espace) précède le jeton

« Invalid token » ou non-concordance entre l’audience et l’émetteur (401)

Cause : Le jeton n’a pas été émis pour cette API, ou les valeurs de domaine et d’audience ne correspondent pas.

Correctif :

1. Décodez votre jeton sur jwt.io
2. Vérifiez que iss correspond à https://{yourDomain}/ (notez la barre oblique finale)
3. Vérifiez que aud correspond exactement à votre AUTH0_AUDIENCE
4. Assurez-vous d’utiliser un jeton d’accès, et non un jeton ID — les jetons d’accès sont obtenus avec le paramètre audience

« Insufficient scope » (403)

Cause : Le jeton n’inclut pas le scope requis.

Correctif :

1. Vérifiez que le scope est défini dans l’onglet Permissions de votre API dans l’Auth0 Dashboard
2. Assurez-vous que le client demande le scope lors de l’obtention du jeton d’accès
3. Décodez le jeton sur jwt.io et vérifiez le claim scope

Variables d’environnement non chargées

Cause : dotenv n’est pas configuré ou les noms de variables sont incorrects.

Correctif :

1. Assurez-vous que import 'dotenv/config' est la première instruction d’importation dans votre fichier d’entrée
2. Vérifiez que .env contient AUTH0_DOMAIN et AUTH0_AUDIENCE
3. Déboguez :

console.log({
  domain: !!process.env.AUTH0_DOMAIN,
  audience: !!process.env.AUTH0_AUDIENCE,
});

Erreurs d’importation ESM (« Cannot use import statement »)

Cause : Le SDK @auth0/auth0-express-api utilise des modules ES.

Correctif : Ajoutez "type": "module" à votre package.json :

📁 package.json

{
  "type": "module"
}

Ou renommez le fichier de votre serveur en server.mjs.

---

​

Étapes suivantes

• Ajouter Login à une application web Express — Utilisez @auth0/auth0-express pour l’authentification par session dans les applications web
• Contrôle d’accès basé sur les rôles — Mettez en œuvre des permissions granulaires
• Bonnes pratiques relatives aux jetons d’accès — Découvrez comment gérer les jetons d’accès
• Surveiller votre API — Configurez la journalisation et la surveillance

---

​

Ressources

• auth0/auth0-express-api GitHub — Code source et exemples
• Auth0 Community — Obtenez de l’aide auprès de la communauté
• JWT.io — Déboguez et décodez les JWTs