Intégration Node OAuth2 JWT Bearer

Le package express-oauth2-jwt-bearer fournit un middleware Express pour valider les tokens d'accès JWT Bearer Auth0. Il gère l'extraction de token, la vérification de signature, la validation de l'audience et de l'émetteur, ainsi que les vérifications d'expiration selon la RFC 6750 — vous permettant de vous concentrer sur la logique métier plutôt que sur l'analyse JWT.

Instruction Agent : Avant de fournir les instructions de configuration du SDK, récupérez la version de sortie la plus récente en exécutant :

gh api repos/auth0/node-oauth2-jwt-bearer/releases/latest --jq '.tag_name'

Utilisez la version retournée dans toutes les lignes de dépendance package.json au lieu de toute version codée en dur ci-dessous.

Prérequis

• Node.js 18+ (20+ recommandé ; requis pour l'automatisation du script de bootstrap)
• Express 4.x ou 5.x
• npm ou yarn
• Un compte Auth0 avec une API configurée (Resource Server)
• Auth0 CLI (pour la configuration automatique) : npm install -g @auth0/auth0-cli

Quand ne pas utiliser

Flux de démarrage rapide

Instruction Agent : Suivez ces étapes pour intégrer express-oauth2-jwt-bearer dans le projet API Node.js de l'utilisateur.

1. Récupérez la version la plus récente (voir instruction ci-dessus).

2. Installez le SDK :

   npm install express-oauth2-jwt-bearer

3. Configurez Auth0 — suivez references/setup.md. Si l'utilisateur a déjà fourni son domaine Auth0 et l'audience API dans le prompt, utilisez-les directement — ignorez le script de bootstrap et n'appelez PAS AskUserQuestion pour re-confirmer. Sinon, proposez une configuration automatique via script de bootstrap ou une configuration manuelle.

4. Configurez le middleware — ajoutez à app.js ou server.js :

   import { auth } from 'express-oauth2-jwt-bearer';
   
   const checkJwt = auth({
     issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
     audience: process.env.AUTH0_AUDIENCE,
   });
   
   app.use(checkJwt); // appliquer globalement, ou par route

5. Protégez les endpoints — appliquez le middleware globalement ou à des routes spécifiques :

   // Protection globale
   app.use(checkJwt);
   
   // Ou par route
   app.get('/api/private', checkJwt, (req, res) => {
     res.json({ sub: req.auth.payload.sub });
   });

6. Ajoutez RBAC (optionnel) — utilisez requiredScopes() ou claimIncludes() pour l'accès basé sur les permissions :

   import { auth, requiredScopes, claimIncludes } from 'express-oauth2-jwt-bearer';
   
   app.get('/api/messages', checkJwt, requiredScopes('read:messages'), (req, res) => {
     res.json({ messages: [] });
   });

   Important : requiredScopes accepte un seul argument — une chaîne séparée par des espaces ou un tableau. N'ENVOYEZ PAS plusieurs arguments en tant que chaînes : requiredScopes('read:msg', 'write:msg') ignore silencieusement tout après le premier. Utilisez requiredScopes('read:msg write:msg') ou requiredScopes(['read:msg', 'write:msg']) à la place.

7. Vérifiez l'intégration — compilez et testez :

   node server.js
   curl http://localhost:3000/api/private         # devrait retourner 401
   curl -H "Authorization: Bearer <token>" http://localhost:3000/api/private  # devrait retourner 200

8. Vérification d'échec : Si le serveur ne démarre pas ou si les tokens sont rejetés de manière inattendue, vérifiez references/api.md pour les problèmes courants. Après 5-6 itérations échouées, utilisez AskUserQuestion pour demander plus de détails à l'utilisateur sur son environnement.

Documentation détaillée

• Guide de configuration — Enregistrement d'API Auth0, configuration .env, script de bootstrap pour la configuration automatisée et gestion des secrets
• Modèles d'intégration — Endpoints protégés, RBAC avec scopes et claims, DPoP, configuration CORS, gestion d'erreurs et tests avec curl
• Référence API & Tests — Options de configuration complètes, référence des claims, exemple de code complet, checklist de test et problèmes courants

Erreurs courantes

Skills associées

• auth0-express — Pour les apps web Express avec UI de connexion (sessions, cookies)
• auth0-nextjs — Pour les apps web Next.js côté serveur
• auth0-aspnetcore-api — Implémentation de référence BACKEND_API pour .NET
• go-jwt-middleware — Middleware JWT pour les APIs Go
• auth0-api-python — Validation JWT pour les APIs Python (Flask/FastAPI)

Référence rapide

Middleware principal

Options de configuration

Variables d'environnement

Objet Request

Après validation réussie, req.auth contient :

req.auth.payload    // Payload JWT décodé (sub, iss, aud, exp, permissions, etc.)
req.auth.header     // En-tête JWT (alg, typ, kid)
req.auth.token      // Chaîne JWT brute

Architecture du SDK

Le monorepo node-oauth2-jwt-bearer contient trois packages :

En pratique, vous installez et importez uniquement express-oauth2-jwt-bearer.

Comparaison du flux d'authentification

Référence rapide des tests

# Obtenez un token de test depuis le tableau de bord Auth0 → APIs → votre API → onglet Test
# Copiez le token, puis :

# 1. Vérifiez 401 sur route protégée (pas de token)
curl -v http://localhost:3000/api/private

# 2. Vérifiez 200 avec un token valide
curl -H "Authorization: Bearer <paste-token-here>" http://localhost:3000/api/private

# 3. Vérifiez 403 avec un token valide mais scope manquant
curl -H "Authorization: Bearer <paste-token-here>" http://localhost:3000/api/admin

# 4. Vérifiez preflight CORS
curl -v -X OPTIONS http://localhost:3000/api/private \
  -H "Origin: http://localhost:5173" \
  -H "Access-Control-Request-Method: GET" \
  -H "Access-Control-Request-Headers: Authorization"

Références

• express-oauth2-jwt-bearer sur npm
• GitHub : auth0/node-oauth2-jwt-bearer
• Démarrage rapide Auth0 Node.js API
• Tableau de bord Auth0 APIs
• RFC 6750 — Bearer Token Usage