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

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

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">
  Ce guide de démarrage rapide est actuellement en **bêta**. Nous aimerions connaître vos commentaires!
</Callout>

<Note>
  **Prérequis :**

  * **Node.js** 20 LTS ou version ultérieure
  * **npm** 10+ ou **yarn** 1.22+ ou **pnpm** 8+
  * Facultatif : **[jq](https://jqlang.org/)** - 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)
</Note>

<div id="get-started">
  ## Pour commencer
</div>

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.

<Steps>
  <Step title="Créer une nouvelle application Hono" stepNumber={1}>
    Créez une nouvelle application Hono à l’aide de l’utilitaire create-hono.

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

    Sélectionnez le gabarit `nodejs`
  </Step>

  <Step title="Installez les dépendances" stepNumber={2}>
    Installez le middleware Auth0.

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

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

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

  <Step title="Créer une application Auth0" stepNumber={3}>
    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 :

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

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

        Utilisez le fichier `.env` généré ou mettez les valeurs à jour manuellement au besoin.
      </Tab>

      <Tab title="Dashboard">
        Étapes manuelles :

        1. Accédez à l’[Auth0 Dashboard](https://manage.auth0.com/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 :

        ```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
        # 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.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configurer le serveur web Hono avec le middleware Auth0" stepNumber={4}>
    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()`.

    ```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>();

    // 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}`);
    });
    ```
  </Step>

  <Step title="Exécutez votre application" stepNumber={5}>
    Démarrez le serveur et ouvrez `http://localhost:3000`.

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

<Check>
  **Vérification**

  Votre application Hono devrait s’exécuter à l’adresse [http://localhost:3000](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.
</Check>

<div id="troubleshooting">
  ## Dépannage
</div>

<Accordion title="Problèmes courants">
  <Accordion title="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.
  </Accordion>

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

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

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

<div id="advanced-usage">
  ## Utilisation avancée
</div>

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

<div id="best-practices-security">
  ## Bonnes pratiques et sécurité
</div>

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

***