Ajouter la connexion à votre application Hono

Ce guide de démarrage rapide explique comment sécuriser vos applications Hono avec l’authentification Auth0. Suivez les étapes pour ajouter la connexion, la déconnexion et des routes protégées à une application Hono.

Ce guide de démarrage rapide est actuellement en bêta. Nous aimerions connaître vos commentaires!

Prérequis :

• Node.js 20 LTS ou version ultérieure
• npm 10+ ou yarn 1.22+ ou pnpm 8+
• Facultatif : jq - pour configurer l’interface de ligne de commande Auth0 et openssl pour générer des secrets sécurisés
• Les projets Hono doivent utiliser Hono >= 3.x (dépendance pair)

​

Pour commencer

Ce guide de démarrage rapide présente la façon minimale recommandée de sécuriser une application Hono à l’aide de @auth0/auth0-hono. Il suit les pratiques recommandées du dépôt : configuration basée sur l’environnement, middleware app.use(auth0(...)) et requiresAuth() pour une protection sélective.

1. Créer une nouvelle application Hono

   Créez une nouvelle application Hono à l’aide de l’utilitaire create-hono.

   npm create hono@latest auth0-hono-app && cd auth0-hono-app
   

   Sélectionnez le gabarit nodejs

2. Installez les dépendances

   Installez le middleware Auth0.

   npm install @auth0/auth0-hono
   

   Ce guide de démarrage rapide utilise le module dotenv pour charger les variables d’environnement à partir d’un fichier .env.

   Pour installer dotenv localement :

   npm install -D dotenv
   

   Sinon, si vous préférez ne pas ajouter de dépendance, vous pouvez charger un fichier d’environnement au démarrage du processus à l’aide de l’option --env-file de Node, ce qui vous évite d’installer et d’importer dotenv.

   Modifiez le script start dans package.json comme suit :

     "scripts": {
       "start": "node --env-file=.env dist/index.js"
     }
   
3. Créer une application Auth0

   Créez une application Auth0 dans votre locataire Auth0 (Regular Web Application) et consignez le Domaine, l’ID client et le Secret client dans les variables d’environnement de votre projet. Vous pouvez le faire automatiquement en exécutant une commande CLI, ou manuellement dans l’Auth0 Dashboard :

   CLI

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

   Utilisez le fichier .env généré ou mettez les valeurs à jour manuellement au besoin.

   Dashboard

   Étapes manuelles :

   1. Accédez à l’Auth0 Dashboard
   2. Applications → Create Application → Regular Web Application
   3. Dans les paramètres de l’application, définissez :

   Allowed Callback URLs

   http://localhost:3000/auth/callback
   

   Allowed Logout URLs

   http://localhost:3000
   

   4. Créez un fichier .env à la racine de votre projet et renseignez les valeurs suivantes :

   AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
   AUTH0_CLIENT_ID=YOUR_AUTH0_CLIENT_ID
   AUTH0_CLIENT_SECRET=YOUR_AUTH0_CLIENT_SECRET
   APP_BASE_URL=http://localhost:3000
   AUTH0_SESSION_ENCRYPTION_KEY=your_32_char_min_secret
   # Facultatif pour les API
   AUTH0_AUDIENCE=YOUR_API_IDENTIFIER
   

   Remarque : AUTH0_SESSION_ENCRYPTION_KEY doit contenir au moins 32 caractères. Utilisez openssl rand -hex 32 pour en générer une.

4. Configurer le serveur web Hono avec le middleware Auth0

   Remplacez le modèle initial dans le fichier index.ts par l’exemple suivant. Le code illustre une configuration sans intervention, où les variables d’environnement sont lues automatiquement, créant un middleware auth0() avec des routes publiques par défaut et des routes protégées au moyen de requiresAuth().

   ./src/index.ts

   // src/index.ts
   import { serve } from '@hono/node-server';
   import { Hono } from 'hono';
   import { auth0, requiresAuth, Auth0Error, type OIDCEnv } from '@auth0/auth0-hono';
   
   const app = new Hono<OIDCEnv>();
   
   // Zéro configuration : lit AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET,
   // APP_BASE_URL, AUTH0_SESSION_ENCRYPTION_KEY depuis l'environnement
   app.use(
     auth0({
       authRequired: false, // Public par défaut, protéger des routes spécifiques
     })
   );
   
   // Route publique
   app.get('/', (c) => c.text('Public — no login required'));
   
   // Routes protégées
   app.use('/profile/*', requiresAuth());
   
   app.get('/profile', (c) => {
     const user = c.var.auth0.user;
     return c.json({ message: 'Protected profile', user });
   });
   
   // Gestion des erreurs
   app.onError((err, c) => {
     if (err instanceof Auth0Error) {
       return c.json({ error: err.code, error_description: err.description }, err.status);
     }
     return c.json({ error: 'Internal server error' }, 500);
   });
   
   const port = Number(process.env.PORT) || 3000;
   serve({ fetch: app.fetch, port }, (info) => {
     console.log(`Server is running on http://localhost:${info.port}`);
   });
   
5. Exécutez votre application

   Démarrez le serveur et ouvrez http://localhost:3000.

   npm run dev
   

Vérification

Votre application Hono devrait s’exécuter à l’adresse http://localhost:3000. La route / est publique. Si vous accédez à /profile, vous devriez être redirigé vers la page de connexion (si vous n’êtes pas authentifié), puis voir s’afficher les données du profil une fois l’authentification réussie.

​

Dépannage

Problèmes courants

Incompatibilité du callback ou de la redirection

Cause : l’URL de rappel configurée dans l’Auth0 Dashboard ne correspond pas exactement à APP_BASE_URL + la route de rappel (p. ex., http://localhost:3000/auth/callback).

Correctif :

1. Vérifiez la valeur de APP_BASE_URL dans .env.
2. Assurez-vous que Allowed Callback URLs dans l’Auth0 Dashboard contiennent http://localhost:3000/auth/callback.
3. Redémarrez le serveur de développement après les modifications.

Déchiffrement de session / JWEDecryptionFailed

Cause : AUTH0_SESSION_ENCRYPTION_KEY est manquante ou trop courte, ou vous l’avez modifiée alors que des témoins associés à un ancien secret sont encore présents.

Correctif :

• Assurez-vous que AUTH0_SESSION_ENCRYPTION_KEY contient au moins 32 caractères.
• Effacez les témoins du navigateur pour localhost après avoir modifié la clé.
• Redémarrez le serveur de développement.

Routes 404 (p. ex., /auth/login retourne 404)

Cause : le middleware n’est pas installé ou il est placé après l’enregistrement des routes.

Correctif :

• Assurez-vous que app.use(auth0(...)) s’exécute avant les routes qui dépendent de l’authentification.
• Confirmez que le package est installé : npm ls @auth0/auth0-hono.

Variables d’environnement manquantes en production

Cause : la plateforme de déploiement ne fournit pas les variables d’environnement ou utilise des noms différents.

Correctif :

• Faites correspondre, dans le tableau de bord de votre fournisseur d’hébergement, les variables d’environnement aux noms utilisés dans ce guide de démarrage rapide.
• Pour Cloudflare Workers, vérifiez que la gestion des sessions et des témoins est compatible avec la plateforme.

​

Utilisation avancée

• Protection sélective : utilisez app.use(auth0({ authRequired: false })) pour rendre les routes publiques par défaut et app.use('/private/*', requiresAuth()) pour protéger des chemins spécifiques.
• Connexion silencieuse : utilisez le middleware attemptSilentLogin() pour tenter une authentification silencieuse et améliorer l’expérience utilisateur.
• Flux de connexion personnalisé : appelez login({...}) pour personnaliser les paramètres de requête transmis, redirectAfterLogin ou les options de connexion silencieuse.
• Gestion des jetons : le middleware expose les jetons d’accès et d’identité via la session ; appliquez le principe du moindre privilège aux scopes et effectuez la rotation des jetons d’actualisation de façon sécuritaire.

​

Bonnes pratiques et sécurité

• Ne stockez pas les secrets dans le contrôle de version — utilisez des variables d’environnement.
• Utilisez une clé AUTH0_SESSION_ENCRYPTION_KEY d’au moins 32 caractères.
• Définissez le paramètre secure du cookie à true en production et utilisez une stratégie sameSite appropriée.
• Limitez les scopes des jetons; utilisez audience uniquement lorsque vous demandez des jetons d’accès pour des API.
• Capturez Auth0Error dans app.onError pour gérer proprement les erreurs d’authentification.

---