> ## Documentation Index
> Fetch the complete documentation index at: https://translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

export const HowToSchema = () => <script type="application/ld+json">
    {'{"@context":"https://schema.org","@type":"HowTo"}'}
  </script>;

export const AuthCodeGroup = ({children, dropdown}) => {
  const [processedChildren, setProcessedChildren] = useState(children);
  useEffect(() => {
    let unsubscribe = null;
    function init() {
      unsubscribe = window.autorun(() => {
        const processChildren = node => {
          if (typeof node === "string") {
            let processedNode = node;
            for (const [key, value] of window.rootStore.variableStore.values.entries()) {
              const escapedKey = key.replaceAll(/[.*+?^${}()|[\]\\]/g, (String.raw)`\$&`);
              processedNode = processedNode.replaceAll(new RegExp(escapedKey, "g"), value);
            }
            return processedNode;
          } else if (Array.isArray(node)) {
            return node.map(processChildren);
          } else if (node && node.props && node.props.children) {
            return {
              ...node,
              props: {
                ...node.props,
                children: processChildren(node.props.children)
              }
            };
          }
          return node;
        };
        setProcessedChildren(processChildren(children));
      });
    }
    if (window.rootStore) {
      init();
    } else {
      window.addEventListener("adu:storeReady", init);
    }
    return () => {
      window.removeEventListener("adu:storeReady", init);
      unsubscribe?.();
    };
  }, [children]);
  return <CodeGroup dropdown={dropdown}>{processedChildren}</CodeGroup>;
};

<HowToSchema />

<Callout icon="pencil" color="#FFC107" iconType="solid">
  Esta guía de inicio rápido se encuentra actualmente en **beta**. ¡Nos encantaría recibir tus comentarios!
</Callout>

<Note>
  **Requisitos previos:**

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

<div id="get-started">
  ## Primeros pasos
</div>

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.

<Steps>
  <Step title="Crear una nueva aplicación de Hono" stepNumber={1}>
    Cree una nueva aplicación de Hono con la utilidad `create-hono`.

    ```shellscript theme={null}
    npm create hono@latest auth0-hono-app && cd auth0-hono-app
    ```

    Selecciona la plantilla `nodejs`
  </Step>

  <Step title="Instala las dependencias" stepNumber={2}>
    Instala el middleware de Auth0.

    ```shellscript theme={null}
    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:

    ```shellscript theme={null}
    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í:

    ```json theme={null}
      "scripts": {
        "start": "node --env-file=.env dist/index.js"
      }
    ```
  </Step>

  <Step title="Crear una aplicación en Auth0" stepNumber={3}>
    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:

    <Tabs>
      <Tab title="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`:

        <AuthCodeGroup>
          ```shellscript Mac theme={null}
          AUTH0_APP_NAME="Hono Quickstart" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apps create -n "${AUTH0_APP_NAME}" -t regular -c http://localhost:3000/auth/callback -l http://localhost:3000 -o http://localhost:3000 --reveal-secrets --json --metadata created_by="quickstart-docs-cli" > auth0-app-details.json && CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) && CLIENT_SECRET=$(jq -r '.client_secret' auth0-app-details.json) && DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && SECRET=$(openssl rand -hex 32) && echo "AUTH0_DOMAIN=${DOMAIN}" > .env && echo "AUTH0_CLIENT_ID=${CLIENT_ID}" >> .env && echo "AUTH0_CLIENT_SECRET=${CLIENT_SECRET}" >> .env && echo "APP_BASE_URL=http://localhost:3000" >> .env && echo "AUTH0_SESSION_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env && rm auth0-app-details.json && cat .env
          ```

          ```shellscript Windows theme={null}
          $AppName = "Hono Quickstart"; winget install Auth0.CLI; auth0 login --no-input; auth0 apps create -n "$AppName" -t regular -c http://localhost:3000/auth/callback -l http://localhost:3000 -o http://localhost:3000 --reveal-secrets --json --metadata created_by="quickstart-docs-cli" | Set-Content -Path auth0-app-details.json; $ClientId = (Get-Content -Raw auth0-app-details.json | ConvertFrom-Json).client_id; $ClientSecret = (Get-Content -Raw auth0-app-details.json | ConvertFrom-Json).client_secret; $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; $Secret = [System.Convert]::ToHexString([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32)).ToLower(); Set-Content -Path .env -Value "AUTH0_DOMAIN=$Domain"; Add-Content -Path .env -Value "AUTH0_CLIENT_ID=$ClientId"; Add-Content -Path .env -Value "AUTH0_CLIENT_SECRET=$ClientSecret"; Add-Content -Path .env -Value "AUTH0_SESSION_ENCRYPTION_KEY=$Secret"; Add-Content -Path .env -Value "APP_BASE_URL=http://localhost:3000"; Remove-Item auth0-app-details.json; Write-Output ".env file created with your Auth0 details:"; Get-Content .env
          ```
        </AuthCodeGroup>

        Use el archivo `.env` generado o actualice los valores manualmente según sea necesario.
      </Tab>

      <Tab title="Dashboard">
        Pasos manuales:

        1. Vaya al [Auth0 Dashboard](https://manage.auth0.com/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:

        ```env theme={null}
        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.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configura el servidor web de Hono con el middleware de Auth0" stepNumber={4}>
    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()`.

    ```typescript ./src/index.ts wrap lines theme={null}
    // 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}`);
    });
    ```
  </Step>

  <Step title="Ejecuta tu aplicación" stepNumber={5}>
    Inicie el servidor y abra `http://localhost:3000`.

    ```shellscript theme={null}
    npm run dev
    ```
  </Step>
</Steps>

<Check>
  **Punto de control**

  Tu aplicación Hono debería estar ejecutándose en [http://localhost:3000](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.
</Check>

<div id="troubleshooting">
  ## Solución de problemas
</div>

<Accordion title="Problemas comunes">
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</Accordion>

<div id="advanced-usage">
  ## Uso avanzado
</div>

* 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.

<div id="best-practices-security">
  ## Prácticas recomendadas y seguridad
</div>

* 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.

***