Añade el inicio de sesión a tu aplicación Hono

Esta guía de inicio rápido muestra cómo proteger tus aplicaciones Hono con la autenticación de Auth0. Sigue los pasos para añadir inicio de sesión, cierre de sesión y rutas protegidas a una aplicación Hono.

Esta guía de inicio rápido se encuentra actualmente en beta. ¡Nos encantaría recibir tus comentarios!

Requisitos previos:

• Node.js 20 LTS o posterior
• npm 10+ o yarn 1.22+ o pnpm 8+
• Opcional: jq: para configurar Auth0 CLI y openssl para generar secretos seguros
• Los proyectos de Hono deben usar Hono >= 3.x (peer dependency)

​

Primeros pasos

Esta guía de inicio rápido muestra la forma mínima y recomendada de proteger una aplicación Hono mediante @auth0/auth0-hono. Sigue los patrones recomendados del repositorio: configuración basada en variables de entorno, middleware app.use(auth0(...)) y requiresAuth() para aplicar protección de forma selectiva.

1. Crear una nueva aplicación de Hono

   Cree una nueva aplicación de Hono con la utilidad create-hono.

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

   Selecciona la plantilla nodejs

2. Instala las dependencias

   Instala el middleware de Auth0.

   npm install @auth0/auth0-hono
   

   Esta guía de inicio rápido utiliza el paquete dotenv para cargar variables de entorno desde un archivo .env.

   Para instalar dotenv localmente:

   npm install -D dotenv
   

   Como alternativa, si prefiere no agregar una dependencia, puede cargar un archivo de entorno al iniciar el proceso con la marca --env-file de Node, lo que le permite omitir la instalación y la importación de dotenv.

   Modifique el script start en package.json para que quede así:

     "scripts": {
       "start": "node --env-file=.env dist/index.js"
     }
   
3. Crear una aplicación en Auth0

   Cree una aplicación de Auth0 en su inquilino de Auth0 (Regular Web Application) y guarde el dominio, el ID de cliente y el Secreto del cliente en las variables de entorno de su proyecto. Puede hacerlo automáticamente ejecutando un comando de la CLI o manualmente desde el Auth0 Dashboard:

   CLI

   Ejecute el siguiente comando de shell en el directorio raíz de su proyecto para crear una aplicación de Auth0 y generar un archivo .env:

   Use el archivo .env generado o actualice los valores manualmente según sea necesario.

   Dashboard

   Pasos manuales:

   1. Vaya al Auth0 Dashboard
   2. Applications → Create Application → Regular Web Application
   3. En la configuración de la aplicación, establezca lo siguiente:

   Allowed Callback URLs

   http://localhost:3000/auth/callback
   

   Allowed Logout URLs

   http://localhost:3000
   

   4. Cree un archivo .env en la raíz de su proyecto y complételo con estos valores:

   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
   # Opcional para APIs
   AUTH0_AUDIENCE=YOUR_API_IDENTIFIER
   

   Nota: AUTH0_SESSION_ENCRYPTION_KEY debe tener al menos 32 caracteres. Use openssl rand -hex 32 para generar una.

4. Configura el servidor web de Hono con el middleware de Auth0

   Reemplace la plantilla inicial del archivo index.ts por el siguiente ejemplo. El código muestra una configuración sin ajustes previos, en la que las variables de entorno se leen automáticamente, creando un middleware auth0() con rutas públicas de forma predeterminada y rutas protegidas mediante 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>();
   
   // Configuración cero: lee AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET,
   // APP_BASE_URL, AUTH0_SESSION_ENCRYPTION_KEY del entorno
   app.use(
     auth0({
       authRequired: false, // Público por defecto, protege rutas específicas
     })
   );
   
   // Ruta pública
   app.get('/', (c) => c.text('Public — no login required'));
   
   // Rutas protegidas
   app.use('/profile/*', requiresAuth());
   
   app.get('/profile', (c) => {
     const user = c.var.auth0.user;
     return c.json({ message: 'Protected profile', user });
   });
   
   // Manejo de errores
   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. Ejecuta tu aplicación

   Inicie el servidor y abra http://localhost:3000.

   npm run dev
   

Punto de control

Tu aplicación Hono debería estar ejecutándose en http://localhost:3000. La ruta / es pública. Al acceder a /profile, debería redirigirte al inicio de sesión (si no estás autenticado) y, tras autenticarte correctamente, devolver los datos del perfil.

​

Solución de problemas

Problemas comunes

El callback o la redirección no coinciden

Causa: La URL de callback configurada en el Auth0 Dashboard no coincide exactamente con APP_BASE_URL + la ruta de callback (por ejemplo, http://localhost:3000/auth/callback).

Solución:

1. Verifique el valor de APP_BASE_URL en .env.
2. Asegúrese de que Allowed Callback URLs en Auth0 Dashboard incluya http://localhost:3000/auth/callback.
3. Reinicie el servidor de desarrollo después de realizar los cambios.

Descifrado de sesión / JWEDecryptionFailed

Causa: Falta AUTH0_SESSION_ENCRYPTION_KEY, es demasiado corta o la cambió mientras aún quedaban cookies de una clave anterior.

Solución:

• Asegúrese de que AUTH0_SESSION_ENCRYPTION_KEY tenga al menos 32 caracteres.
• Borre las cookies del navegador para localhost después de cambiar la clave.
• Reinicie el servidor de desarrollo.

Rutas 404 (por ejemplo, /auth/login devuelve 404)

Causa: El middleware no está instalado o se colocó después del registro de rutas.

Solución:

• Asegúrese de que app.use(auth0(...)) se ejecute antes de las rutas que dependen de la autenticación.
• Confirme que el paquete esté instalado: npm ls @auth0/auth0-hono.

Faltan variables de entorno en producción

Causa: La plataforma de implementación no proporciona variables de entorno o usa nombres distintos.

Solución:

• Asigne en el panel de su proveedor de hosting las variables de entorno a los nombres usados en esta guía de inicio rápido.
• En Cloudflare Workers, verifique que el manejo de sesiones y cookies sea compatible con la plataforma.

​

Uso avanzado

• Protección selectiva: usa app.use(auth0({ authRequired: false })) para que las rutas sean públicas de forma predeterminada y app.use('/private/*', requiresAuth()) para proteger rutas concretas.
• Inicio de sesión silencioso: usa el middleware attemptSilentLogin() para intentar una autenticación silenciosa y mejorar la experiencia de usuario.
• Flujo de inicio de sesión personalizado: llama a login({...}) para personalizar los parámetros de consulta que se reenvían, redirectAfterLogin o las opciones de inicio de sesión silencioso.
• Gestión de tokens: el middleware expone tokens de acceso y tokens de ID a través de la sesión; sigue el principio de privilegio mínimo para los alcances y rota los tokens de actualización de forma segura.

​

Prácticas recomendadas y seguridad

• Mantenga los secretos fuera del control de versiones; use variables de entorno.
• Use una AUTH0_SESSION_ENCRYPTION_KEY de 32 caracteres o más.
• Establezca la cookie secure en true en producción y configure una política sameSite adecuada.
• Limite los alcances del token; use audience solo cuando solicite tokens de acceso para APIs.
• Capture Auth0Error en app.onError para manejar correctamente los errores específicos de autenticación.

---