Ajouter l’authentification à votre application Express

Ce guide montre comment intégrer Auth0, ajouter l’authentification et afficher les renseignements du profil utilisateur dans une application web Express.js à l’aide du SDK express-openid-connect.

Une nouvelle version bêta de ce Quickstart est disponible et utilise le SDK @auth0/auth0-express, qui remplacera bientôt ce guide. Essayer le Quickstart bêta →

Utiliser l’IA pour intégrer Auth0

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

Installer :

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

Demandez ensuite à votre assistant IA :

Add Auth0 authentication to my Express app

Votre assistant IA créera automatiquement votre application Auth0, récupérera les identifiants, installera express-openid-connect, configurera le middleware et mettra en place vos routes. 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
• npm 10+ ou yarn 1.22+
• jq - Requis pour la configuration d’Auth0 CLI (facultatif)

Compatibilité des versions d’Express : Ce Quickstart fonctionne avec Express 4.17.0 et les versions ultérieures.

​

Premiers pas

Ce guide explique comment intégrer Auth0, ajouter l’authentification et afficher les renseignements du profil utilisateur dans une application web Express.js à l’aide du SDK express-openid-connect.

---

​

1. Créez un nouveau projet

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

mkdir auth0-express && cd auth0-express

npm init -y

Créez la structure du projet :

touch index.js .env

---

​

2. Installer le SDK Auth0 Express

Installez express-openid-connect ainsi qu’Express et dotenv pour gérer les variables d’environnement.

npm install express express-openid-connect dotenv

En développement, installez nodemon pour redémarrer automatiquement votre serveur lorsque des fichiers sont modifiés :

npm install --save-dev nodemon

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

📁 package.json

{
  "name": "auth0-express",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js"
  },
  "dependencies": {
    "dotenv": "^16.3.1",
    "express": "^4.18.2",
    "express-openid-connect": "^2.17.1"
  },
  "devDependencies": {
    "nodemon": "^3.0.2"
  }
}

---

​

3. Configurez votre Auth0 App

Ensuite, vous devez créer une nouvelle application dans votre tenant Auth0 et ajouter les variables d’environnement à votre projet.

Vous pouvez choisir de configurer automatiquement votre application Auth0 en exécutant une commande CLI ou de le faire manuellement dans le Dashboard :

CLI

Exécutez la commande shell suivante dans le répertoire racine de votre projet pour créer une application Auth0 et générer votre fichier .env :

Mac

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

# Configurez l’application Auth0 et générez le fichier .env
auth0 qs setup --app --type regular --framework express --port 3000 --name "My Express App"

Cette commande va :

1. Vérifier si vous êtes authentifié (et vous inviter à vous connecter au besoin)
2. Créer une Auth0 Regular Web Application configurée pour http://localhost:3000
3. Générer un fichier .env avec ISSUER_BASE_URL, CLIENT_ID, SECRET et BASE_URL

Dashboard

1. Accédez au Auth0 Dashboard
2. Allez à Applications → Create Application
3. Entrez un nom pour votre application (par exemple, “My Express App”)
4. Sélectionnez Regular Web Applications, puis cliquez sur Create
5. Dans l’onglet Settings, configurez les éléments suivants :

Paramètre	Valeur
Allowed Callback URLs	http://localhost:3000
Allowed Logout URLs	http://localhost:3000

6. Faites défiler la page vers le bas, puis cliquez sur Save Changes
7. Copiez les valeurs Domain et Client ID de la section Basic Information

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

📁 .env

ISSUER_BASE_URL=https://YOUR_AUTH0_DOMAIN
CLIENT_ID=YOUR_CLIENT_ID
SECRET=use-a-long-random-string-at-least-32-characters
BASE_URL=http://localhost:3000

Remplacez YOUR_AUTH0_DOMAIN par le domaine de votre tenant Auth0 (par exemple, dev-abc123.us.auth0.com) et YOUR_CLIENT_ID par le Client ID de votre application dans le Dashboard.

Générez un secret sécurisé pour chiffrer la session :

openssl rand -hex 32

Copiez la valeur générée et utilisez-la comme valeur de SECRET dans votre fichier .env.

---

​

4. Configurer le middleware

Ajoutez le middleware Auth0 à votre application Express. Le middleware auth() gère la session et crée automatiquement les routes /login, /logout et /callback.

📁 index.js

require('dotenv').config();
const express = require('express');
const { auth } = require('express-openid-connect');

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

// Configuration Auth0
const config = {
  authRequired: false,      // Autoriser les routes publiques
  auth0Logout: true,        // Utiliser le endpoint de logout Auth0
  secret: process.env.SECRET,
  baseURL: process.env.BASE_URL,
  clientID: process.env.CLIENT_ID,
  issuerBaseURL: process.env.ISSUER_BASE_URL,
};

// Appliquer le middleware d'authentification
app.use(auth(config));

// Route d'accueil - publique
app.get('/', (req, res) => {
  res.send(req.oidc.isAuthenticated() ? 'Logged in' : 'Logged out');
});

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

Ce que cela fait :

• authRequired: false permet, par défaut, aux utilisateurs authentifiés ou non d’accéder aux routes
• auth0Logout: true garantit que les utilisateurs sont déconnectés à la fois d’Auth0 et de votre application
• Le middleware met automatiquement à disposition des routes à /login, /logout et /callback
• La session utilisateur est stockée dans un cookie chiffré

---

​

5. Créez des routes de login, de logout et de profil

Ajoutez maintenant des routes pour afficher des liens de login et de logout, ainsi qu’une page de profil protégée.

📁 index.js

require('dotenv').config();
const express = require('express');
const { auth, requiresAuth } = require('express-openid-connect');

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

// Configuration Auth0
const config = {
  authRequired: false,
  auth0Logout: true,
  secret: process.env.SECRET,
  baseURL: process.env.BASE_URL,
  clientID: process.env.CLIENT_ID,
  issuerBaseURL: process.env.ISSUER_BASE_URL,
};

// Appliquer le middleware d'authentification
app.use(auth(config));

// Route d'accueil - affiche le statut de connexion/déconnexion
app.get('/', (req, res) => {
  const isAuthenticated = req.oidc.isAuthenticated();

  res.send(`
    <html>
      <head>
        <title>Auth0 Express Quickstart</title>
        <style>
          body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; padding: 2rem; max-width: 600px; margin: 0 auto; }
          a { color: #0066cc; text-decoration: none; margin-right: 1rem; }
          a:hover { text-decoration: underline; }
          .status { padding: 1rem; border-radius: 4px; margin: 1rem 0; }
          .logged-in { background: #d4edda; color: #155724; }
          .logged-out { background: #f8d7da; color: #721c24; }
        </style>
      </head>
      <body>
        <h1>Auth0 Express Quickstart</h1>
        <div class="status ${isAuthenticated ? 'logged-in' : 'logged-out'}">
          ${isAuthenticated ? '✓ You are logged in' : '✗ You are logged out'}
        </div>
        <nav>
          ${isAuthenticated
            ? '<a href="/profile">Profile</a> | <a href="/logout">Logout</a>'
            : '<a href="/login">Login</a>'}
        </nav>
      </body>
    </html>
  `);
});

// Route de profil protégée - nécessite une authentification
app.get('/profile', requiresAuth(), (req, res) => {
  const user = req.oidc.user;

  res.send(`
    <html>
      <head>
        <title>Profile - Auth0 Express</title>
        <style>
          body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; padding: 2rem; max-width: 600px; margin: 0 auto; }
          a { color: #0066cc; text-decoration: none; }
          img { border-radius: 50%; }
          pre { background: #f4f4f4; padding: 1rem; border-radius: 4px; overflow-x: auto; }
          .card { border: 1px solid #ddd; border-radius: 8px; padding: 1.5rem; margin: 1rem 0; }
        </style>
      </head>
      <body>
        <h1>User Profile</h1>
        <div class="card">
          ${user.picture ? `<img src="${user.picture}" alt="Profile" width="80" />` : ''}
          <h2>${user.name || user.nickname || 'User'}</h2>
          <p><strong>Email:</strong> ${user.email || 'N/A'}</p>
        </div>
        <h3>Full User Object</h3>
        <pre>${JSON.stringify(user, null, 2)}</pre>
        <nav>
          <a href="/">← Back to Home</a> | <a href="/logout">Logout</a>
        </nav>
      </body>
    </html>
  `);
});

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

Points clés :

• Le middleware requiresAuth() protège la route /profile : les utilisateurs non authentifiés sont redirigés vers la page de connexion
• req.oidc.user contient les renseignements du profil de l’utilisateur authentifié
• req.oidc.isAuthenticated() renvoie un booléen indiquant l’état de la connexion
• Les routes de connexion et de logout (/login, /logout) sont créées automatiquement par le middleware auth()

---

​

6. Lancez votre application

Démarrez le serveur de développement :

npm run dev

Ouvrez http://localhost:3000 dans votre navigateur.

Checkpoint

Vous devriez maintenant avoir une page de connexion d’Auth0 entièrement fonctionnelle. Lorsque vous :

1. Cliquez sur “Login” - vous êtes redirigé vers la page Universal Login d’Auth0
2. Terminez l’authentification - vous êtes redirigé vers votre application
3. Accédez à “/profile” - vous voyez vos renseignements d’utilisateur
4. Cliquez sur “Logout” - vous êtes déconnecté à la fois de votre application et d’Auth0

---

​

Utilisation avancée

Protéger des routes précises avec requiresAuth()

Utilisez le middleware requiresAuth() pour protéger les routes qui nécessitent une authentification :

const { auth, requiresAuth } = require('express-openid-connect');

app.use(auth({ authRequired: false }));

// Route publique
app.get('/', (req, res) => {
  res.send('Welcome! This is public.');
});

// Routes protégées
app.get('/dashboard', requiresAuth(), (req, res) => {
  res.send(`Hello ${req.oidc.user.name}, welcome to your dashboard!`);
});

app.get('/settings', requiresAuth(), (req, res) => {
  res.send('Settings page - only for authenticated users');
});

Vous pouvez aussi protéger toutes les routes associées à un chemin précis à l’aide d’Express Router :

const protectedRouter = express.Router();

// Toutes les routes de ce routeur nécessitent une authentification
protectedRouter.use(requiresAuth());

protectedRouter.get('/dashboard', (req, res) => {
  res.send('Protected dashboard');
});

protectedRouter.get('/settings', (req, res) => {
  res.send('Protected settings');
});

app.use('/app', protectedRouter);
// Routes : /app/dashboard, /app/settings sont toutes protégées

Appel d’API protégées avec des jetons d’accès

Pour appeler des API externes qui nécessitent un jeton d’accès, configurez le SDK pour en demander un :

📁 index.js (configuration mise à jour)

const config = {
  authRequired: false,
  auth0Logout: true,
  secret: process.env.SECRET,
  baseURL: process.env.BASE_URL,
  clientID: process.env.CLIENT_ID,
  issuerBaseURL: process.env.ISSUER_BASE_URL,
  clientSecret: process.env.CLIENT_SECRET,  // Requis pour le flux de code
  authorizationParams: {
    response_type: 'code',
    audience: process.env.API_AUDIENCE,     // Votre identifiant d'API
    scope: 'openid profile email read:data',
  },
};

Ajoutez ce qui suit à votre fichier .env :

CLIENT_SECRET=your_client_secret_from_dashboard
API_AUDIENCE=https://your-api.example.com

Ensuite, utilisez votre access token pour appeler votre API :

app.get('/api-data', requiresAuth(), async (req, res) => {
  try {
    let { token_type, access_token, isExpired, refresh } = req.oidc.accessToken;

    // Actualiser le jeton s'il est expiré
    if (isExpired()) {
      const refreshed = await refresh();
      access_token = refreshed.access_token;
    }

    // Appeler votre API protégée
    const response = await fetch('https://your-api.example.com/data', {
      headers: {
        Authorization: `${token_type} ${access_token}`,
      },
    });

    const data = await response.json();
    res.json(data);
  } catch (error) {
    console.error('API call failed:', error);
    res.status(500).json({ error: 'Failed to fetch data' });
  }
});

Pour obtenir des jetons d’actualisation, ajoutez offline_access à votre scope :

scope: 'openid profile email offline_access read:data',

Utilisation de l’autorisation fondée sur les revendications

Protégez les routes selon les claims de l’utilisateur (rôles, permissions, etc.) :

const { auth, requiresAuth, claimEquals, claimIncludes, claimCheck } = require('express-openid-connect');

app.use(auth({ authRequired: false }));

// Uniquement les utilisateurs avec le rôle = 'admin'
app.get('/admin', claimEquals('role', 'admin'), (req, res) => {
  res.send('Admin dashboard');
});

// Utilisateurs dont le tableau de rôles contient 'editor'
app.get('/editor', claimIncludes('roles', 'editor'), (req, res) => {
  res.send('Editor dashboard');
});

// Vérification de revendication personnalisée avec logique conditionnelle
app.get('/premium', claimCheck((req, claims) => {
  return claims.subscription === 'premium' || claims.role === 'admin';
}), (req, res) => {
  res.send('Premium content');
});

Des claims comme role doivent être ajoutées à vos jetons au moyen d’Auth0 Rules ou d’Actions. En savoir plus sur l’ajout de claims personnalisés.

Magasin de sessions personnalisé (Redis)

Pour les environnements de production ou si vous exécutez plusieurs instances de serveur, utilisez un magasin de sessions personnalisé :

npm install redis connect-redis

const { auth } = require('express-openid-connect');
const { createClient } = require('redis');
const RedisStore = require('connect-redis').default;

// Créer le client Redis
const redisClient = createClient({
  url: process.env.REDIS_URL || 'redis://localhost:6379',
});
redisClient.connect().catch(console.error);

const config = {
  authRequired: false,
  auth0Logout: true,
  secret: process.env.SECRET,
  baseURL: process.env.BASE_URL,
  clientID: process.env.CLIENT_ID,
  issuerBaseURL: process.env.ISSUER_BASE_URL,
  session: {
    store: new RedisStore({ client: redisClient }),
  },
};

app.use(auth(config));

Quand utiliser un magasin de sessions personnalisé :

• Exécuter plusieurs instances de serveur (répartition de la charge)
• Les données de session dépassent les limites de taille des témoins (~4KB)
• Avoir besoin d’enregistrer la session lors des redémarrages du serveur
• Utiliser Back-Channel Logout

Gestion des erreurs

Ajoutez une gestion adéquate des erreurs d’authentification :

const { auth } = require('express-openid-connect');

app.use(auth({
  authRequired: false,
  auth0Logout: true,
  secret: process.env.SECRET,
  baseURL: process.env.BASE_URL,
  clientID: process.env.CLIENT_ID,
  issuerBaseURL: process.env.ISSUER_BASE_URL,
  errorOnRequiredAuth: true,  // Retourner 401 au lieu de rediriger pour les routes d'API
}));

// Gestionnaire d'erreurs personnalisé
app.use((err, req, res, next) => {
  // Gérer les erreurs d'authentification
  if (err.statusCode === 401) {
    // Pour les requêtes d'API, retourner du JSON
    if (req.accepts('json')) {
      return res.status(401).json({
        error: 'Authentication required',
        login_url: '/login',
      });
    }
    // Pour les requêtes du navigateur, rediriger vers la page de connexion
    return res.redirect('/login');
  }

  // Journaliser l'erreur (ne pas exposer les détails au client)
  console.error('Application error:', err.message);

  res.status(err.statusCode || 500).json({
    error: 'An unexpected error occurred',
  });
});

---

​

Dépannage

Problèmes courants et solutions

​

Erreur « invalid state » après la connexion

Problème : La valeur de state ne correspond pas entre la requête d’authentification et le rappel.

Solutions :

1. Assurez-vous d’utiliser HTTPS en production
2. Vérifiez que les cookies sont correctement enregistrés (et non bloqués par le navigateur)
3. Vérifiez que l’URL de rappel correspond exactement à celle configurée dans l’Auth0 Dashboard

​

req.oidc est undefined

Problème : Le middleware auth() n’est pas appliqué avant l’accès à req.oidc.

Solution : Assurez-vous que app.use(auth(config)) est appelé avant toute route qui accède à req.oidc :

// ✅ Ordre correct
app.use(auth(config));
app.get('/profile', requiresAuth(), (req, res) => { ... });

// ❌ Mauvais ordre
app.get('/profile', requiresAuth(), (req, res) => { ... });
app.use(auth(config));

​

Session trop volumineuse / erreurs liées aux cookies

Problème : Les données de session de l’utilisateur dépassent la taille maximale des cookies.

Solution : Utilisez un magasin de sessions personnalisé comme Redis :

session: {
  store: new RedisStore({ client: redisClient }),
}

​

Incompatibilité de l’URL de rappel

Problème : Erreur « Callback URL mismatch » provenant d’Auth0.

Solution :

1. Allez dans votre Auth0 Dashboard → Applications → Your App → Settings
2. Ajoutez http://localhost:3000 (ou votre URL de production) à Allowed Callback URLs
3. L’URL doit correspondre exactement (y compris les barres obliques finales)

​

Les variables d’environnement ne se chargent pas

Problème : Les valeurs de configuration sont undefined.

Solution :

1. Assurez-vous que require('dotenv').config() se trouve au début de votre fichier d’entrée
2. Vérifiez que le fichier .env se trouve dans le répertoire racine
3. Vérifiez qu’il n’y a pas de fautes de frappe dans les noms de variables

// Débogage : affichez les valeurs de configuration (à supprimer en production !)
console.log('Config check:', {
  hasSecret: !!process.env.SECRET,
  hasClientID: !!process.env.CLIENT_ID,
  issuerBaseURL: process.env.ISSUER_BASE_URL,
});

---

​

Prochaines étapes

Maintenant que l’authentification fonctionne, pensez à explorer :

• Ajouter l’autorisation - Implémentez le contrôle d’accès basé sur les rôles
• Appeler des API protégées - Utilisez des jetons d’accès pour appeler vos API côté serveur
• Personnaliser Universal Login - Adaptez l’image de marque de votre expérience de connexion
• Ajouter des connexions sociales - Activez Google, GitHub et d’autres options de connexion sociale
• Implémenter MFA - Ajoutez l’authentification multifacteur

---

​

Ressources

• express-openid-connect GitHub - Code source et exemples
• Documentation de l’API - Référence complète de l’API
• Application d’exemple Auth0 Express - Application d’exemple complète
• Auth0 Community - Obtenez de l’aide auprès de la communauté