Protection par mot de passe

Parfois, vous souhaitez que votre documentation soit en ligne, indexable, versionnée dans Git, mais pas visible par tous. Runbooks, guides pré-release, docs réservées aux partenaires, fonctionnalités en accès anticipé. La protection par mot de passe vous offre une phrase secrète partagée qui verrouille soit l'intégralité de votre site, soit un ensemble de pages spécifiques, sans rien déplacer hors de votre dépôt existant.

Les captures d'écran montrent l'interface en anglais.

Quel mode choisir ?

Jamdesk propose deux modes de protection par mot de passe. Choisissez en fonction de ce qui est public et de ce qui ne l'est pas.

Les deux modes partagent la même carte dans le dashboard, le même écran de déverrouillage, et les mêmes contrôles de rotation et de révocation. Vous pouvez passer de l'un à l'autre à tout moment en modifiant docs.json et en poussant.

Protéger l'intégralité de votre site

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "Acme Docs",
  "theme": "jam",
  "auth": {
    "password": {
      "enabled": true,
      "hint": "Ask #docs-access on Slack"
    }
  }
}

git add docs.json
git commit -m "Turn on password protection"
git push

# Should respond with HTTP/1.1 401 and the unlock HTML
curl -I https://acme.jamdesk.app/

# Submit the password. On success, sets the jd_auth_<slug> cookie.
curl -i -X POST https://acme.jamdesk.app/jd/unlock \
  -d "password=your-passphrase&from=/"

Exceptions publiques

Le mode site entier dispose d'une échappatoire : vous pouvez garder des pages spécifiques publiques même lorsque le reste du site est verrouillé. C'est ainsi que vous publiez une page d'accueil marketing ou un formulaire d'inscription aux côtés de docs privées.

Vous disposez de trois façons de marquer une page comme publique, et elles fusionnent toutes dans la même liste d'autorisation à chaque build.

Le frontmatter est l'option la plus granulaire. Ajoutez public: true à n'importe quel fichier .mdx et seule cette page échappe au verrouillage :

---
title: Get started
public: true
---

Les groupes de navigation couvrent une section entière d'un coup. Définissez public: true sur un group ou un tab dans la navigation de votre docs.json, et chaque page sous celui-ci est publique. Pratique pour un onglet « Marketing » qui côtoie des docs d'ingénierie privées :

{
  "navigation": {
    "tabs": [
      {
        "tab": "Marketing",
        "public": true,
        "groups": [
          {
            "group": "Overview",
            "pages": ["landing", "pricing", "changelog"]
          }
        ]
      },
      {
        "tab": "Internal",
        "groups": [
          { "group": "Runbooks", "pages": ["deploys", "oncall"] }
        ]
      }
    ]
  }
}

Les globs explicites sous auth.password.public[] gèrent ce que le frontmatter et la navigation ne peuvent pas : pages d'accueil de premier niveau, routes générées dynamiquement, ou un sous-arbre entier que vous préférez ne pas réécrire.

{
  "auth": {
    "password": {
      "enabled": true,
      "hint": "Ask #docs-access on Slack",
      "public": [
        "/landing",
        "/pricing",
        "/marketing/**",
        "/blog/*"
      ]
    }
  }
}

Les globs supportent * (un segment de chemin) et ** (toute profondeur). Un simple / est rejeté à la validation : si Jamdesk l'acceptait, une seule faute de frappe pourrait silencieusement déverrouiller tout votre site. Après chaque build, la carte dans le dashboard affiche la liste d'autorisation résolue, afin que vous puissiez vérifier ce que le build a effectivement pris en compte.

Protéger uniquement quelques pages

Le mode pages spécifiques est le flux de travail inverse : tout est public par défaut, et vous optez des pages individuelles dans le verrouillage.

---
title: Incident Runbook
description: What to do when the deploys dashboard is on fire.
private: true
---

{
  "auth": {
    "password": {
      "hint": "Ask the on-call engineer",
      "private": ["/admin/runbook", "/internal/api-keys"]
    }
  }
}

git add content/runbook.mdx docs.json
git commit -m "Gate the incident runbook"
git push

Ce que voient les visiteurs

Lorsqu'un visiteur atteint une page verrouillée, il obtient une carte de déverrouillage centrée, sans barre latérale, sans chrome, et sans indication sur ce qui se trouve derrière la porte, hormis le nom du site et un indice facultatif.

La carte est personnalisée avec le logo et la couleur primaire de votre site issus de docs.json. Le champ de mot de passe dispose d'un bouton d'affichage et reçoit le focus automatiquement.

Les mauvais mots de passe affichent la même carte avec un message d'erreur, une nouvelle saisie, et un court délai entre les tentatives. Un mot de passe incorrect et une requête sans mot de passe aboutissent sur le même écran, de sorte que rien sur la page ne distingue « mot de passe incorrect » de « aucun mot de passe saisi ».

Une fois qu'un visiteur saisit le bon mot de passe, il reçoit un cookie signé et peut naviguer normalement jusqu'à l'expiration de la session ou à sa révocation.

Rotation et révocation des sessions

Les mots de passe se partagent. Les personnes partent. Vous voudrez le changer tôt ou tard.

Ouvrez la carte Protection par mot de passe, saisissez une nouvelle phrase secrète dans le champ Rotation du mot de passe, et cliquez sur Enregistrer le nouveau mot de passe. Toute personne avec l'ancien mot de passe est bloquée à sa prochaine requête ; toute personne avec le nouveau mot de passe accède au site. La rotation prend effet immédiatement et ne nécessite pas de rebuild.

Si vous souhaitez simplement forcer la déconnexion de toutes les sessions actives sans changer la phrase secrète (par exemple, l'ordinateur portable de quelqu'un a disparu), cliquez sur Révoquer toutes les sessions à la place. Cela incrémente un compteur de version côté serveur, qui invalide tous les cookies émis avant l'incrémentation. Les visiteurs ressaisissent le mot de passe actuel et retrouvent l'accès.

Désactiver la protection

La protection est pilotée par docs.json, donc la désactiver signifie modifier le fichier et pousser.

• Site entier : supprimez auth.password.enabled (ou mettez-le à false).
• Pages spécifiques : supprimez chaque marqueur private: true et videz auth.password.private.

Lors du build suivant, Jamdesk supprime le hash du mot de passe stocké et remet la carte à l'état Désactivé. Aucun état « dormant » ne subsiste. Si vous réactivez la protection ultérieurement, vous devrez choisir un nouveau mot de passe.

Règles de priorité

Une seule page peut être concernée par plusieurs signaux simultanément. L'ordre de résolution, du plus au moins spécifique :

• Si auth.password.enabled est true, l'intégralité du site est verrouillée. private: true sur des pages individuelles devient redondant.
• Si une page est marquée à la fois public: true et private: true, le public l'emporte. La valeur par défaut la plus sûre est celle qui ne laisse pas accidentellement fuiter une page.
• Le frontmatter public: true, le public: true d'un groupe de navigation, et les globs auth.password.public[] fusionnent tous en une seule liste d'autorisation. Aucune règle du « plus spécifique l'emporte ». Si un signal indique qu'une page est publique, elle est publique.
• Si auth.password.private[] est défini mais que auth.password.enabled ne l'est pas, Jamdesk active automatiquement le mode pages spécifiques. Vous n'avez rien d'autre à faire.

Fonctionnement des sessions et de la limitation de débit

Trois questions reviennent souvent avec tout nouveau système d'authentification.

Le cookie de session. Lors d'un déverrouillage réussi, Jamdesk définit un cookie nommé jd_auth_<slug> (par exemple, jd_auth_acme). Il est HttpOnly, Secure, SameSite=Lax, limité à l'hôte, et signé avec HMAC-SHA256. Le contenu inclut le slug du projet, le compteur de version actuel, et un horodatage d'expiration, de sorte que toute altération échoue à la validation. La durée de vie par défaut est de 30 jours, renouvelée à chaque déverrouillage réussi.

Limitation de débit. Le point de terminaison de déverrouillage applique deux compteurs par heure : 10 tentatives par IP et 100 tentatives par projet. Les deux sont appliqués avant la vérification du hash scrypt, de sorte qu'une tentative de force brute ne peut pas consommer du CPU ni laisser fuiter des informations de timing. Atteindre l'un ou l'autre des seuils retourne 429 Too Many Requests avec un en-tête Retry-After.

Stockage. Votre mot de passe est haché avec scrypt et stocké dans le Firestore du dashboard. Il ne se retrouve jamais dans votre dépôt, votre docs.json, ou un artefact de build. Si vous le perdez, effectuez une rotation. Aucune procédure de récupération n'existe.

Tests en développement local

jamdesk dev exécute vos docs avec le contenu R2 en production et la configuration en production. La protection par mot de passe n'est pas appliquée dans le serveur de développement local, vous pouvez donc prévisualiser les pages verrouillées sans connaître le mot de passe. C'est délibéré : vous êtes l'auteur, vous avez déjà accès au dépôt, et bloquer la prévisualisation locale sur un mot de passe serait une friction sans bénéfice pour la sécurité.

Si vous souhaitez vérifier le verrouillage réel, accédez au site déployé sur <slug>.jamdesk.app (ou votre domaine personnalisé) depuis une fenêtre de navigateur qui ne possède pas encore le cookie.

Dépannage

Prochaines étapes