Ajouter la connexion à votre application Hono

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

Ce Quickstart est actuellement en bêta. Nous serions ravis d’avoir vos commentaires!

Prérequis :

• Node.js 20 LTS ou une version ultérieure
• npm 10+ ou yarn 1.22+ ou pnpm 8+
• Facultatif : jq — pour configurer Auth0 CLI — et openssl pour générer des secrets sécurisés
• Les projets Hono doivent utiliser Hono >= 3.x (dépendance homologue)

​

Pour commencer

Ce Quickstart 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 : une configuration gérée par l’environnement, le middleware app.use(auth0(...)) et requiresAuth() pour protéger certaines routes de façon sélective.

1. Créer une nouvelle application Hono

   Utilisez l’utilitaire create-hono pour créer une nouvelle application Hono.

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

   Sélectionnez le gabarit nodejs

2. Installer 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 de faire l’importation de 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 tenant Auth0 (Regular Web Application), puis enregistrez le Domain, le Client ID et le Client Secret dans les variables d’environnement de 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 à la racine de votre projet pour créer une application Auth0 et générer un fichier .env :

   Mac

   # Installer Auth0 CLI (s’il n’est pas déjà installé)
   brew tap auth0/auth0-cli && brew install auth0
   
   # Configurer l’application Auth0 et générer le fichier .env
   auth0 qs setup --app --type regular --framework hono --port 3000 --name "My Hono App"
   

   Cette commande va :

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

   Dashboard

   Étapes manuelles :

   1. Accédez au 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 réglage préalable, où les variables d’environnement sont lues automatiquement, ce qui crée un middleware auth0() avec des routes publiques par défaut et des routes protégées à l’aide 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-config : 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. Lancez votre application

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

   npm run dev
   

Checkpoint

Votre application Hono devrait être en cours d’exécution à l’adresse http://localhost:3000. La route / est publique. Si vous visitez /profile, vous devriez être redirigé vers la page de connexion (si vous n’êtes pas authentifié), puis obtenir les données de profil une fois l’authentification réussie.

​

Dépannage

Problèmes courants

Incompatibilité de callback ou de redirection

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

Correctif :

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

Déchiffrement de session / JWEDecryptionFailed

Cause : AUTH0_SESSION_ENCRYPTION_KEY est absente ou trop courte, ou vous l’avez modifiée alors que des cookies provenant d’un ancien secret sont toujours présents.

Correctif :

• Assurez-vous que AUTH0_SESSION_ENCRYPTION_KEY contient au moins 32 caractères.
• Supprimez les cookies 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 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 :

• Mappez les variables d’environnement dans le tableau de bord de votre fournisseur d’hébergement aux noms utilisés dans ce Quickstart.
• Pour Cloudflare Workers, vérifiez que la gestion des sessions/cookies 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 certains chemins précis.
• Connexion silencieuse : utilisez le middleware attemptSilentLogin() pour tenter une authentification silencieuse et offrir une meilleure expérience utilisateur.
• Processus 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 rend les jetons d’accès et ID accessibles via la session; appliquez le principe du moindre privilège aux scopes et effectuez la rotation des jetons d’actualisation en toute sécurité.

​

Meilleures pratiques et sécurité

• Gardez les secrets hors du contrôle de version — utilisez des variables d’environnement.
• Utilisez une clé AUTH0_SESSION_ENCRYPTION_KEY d’au moins 32 caractères.
• Réglez le cookie secure à true en production et définissez une politique sameSite appropriée.
• Limitez les scopes des jetons; n’utilisez audience que lorsque vous demandez des jetons d’accès pour des API.
• Interceptez Auth0Error dans app.onError pour gérer proprement les erreurs liées à l’authentification.

---