Protection par mot de passe

Il arrive que vous vouliez une documentation qui reste dans Git et en ligne, mais qui ne soit pas visible de tous. Exemples courants : runbooks, guides pré-lancement, documentation réservée aux partenaires et fonctionnalités en accès anticipé. La protection par mot de passe vous donne une phrase de passe partagée unique qui verrouille soit tout votre site, soit un ensemble spécifique de pages, sans rien déplacer hors de votre dépôt existant.

Quel mode choisir ?

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

Les deux modes partagent la même carte du dashboard, le même écran de déverrouillage, ainsi que les mêmes contrôles de rotation et de révocation. Vous pouvez basculer entre les deux à tout moment en modifiant docs.json et en poussant vos changements.

Protéger tout 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 certaines pages publiques même si le reste du site est verrouillé. C'est ainsi que vous publiez une page d'atterrissage marketing ou un formulaire d'inscription à côté d'une documentation privée.

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 à la protection :

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

Les groupes de navigation couvrent toute une section à la fois. Définissez public: true sur un group ou un tab dans la navigation de votre docs.json, et chaque page qui en dépend devient publique. Pratique pour un onglet « Marketing » situé à côté d'une documentation d'ingénierie privée :

{
  "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 tout ce que le frontmatter et la navigation ne peuvent pas : pages d'atterrissage de premier niveau, routes générées dynamiquement, ou toute une sous-arborescence 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 prennent en charge * (un segment de chemin) et ** (n'importe quelle profondeur). Un simple / est rejeté lors de la validation : si Jamdesk l'acceptait, une seule faute de frappe pourrait déverrouiller silencieusement tout votre site. Après chaque build, la carte du dashboard affiche la liste d'autorisation résolue, afin que vous puissiez vérifier ce que le build a réellement pris en compte.

Protéger seulement quelques pages

Le mode pages spécifiques fonctionne à l'inverse : tout est public par défaut, et vous faites entrer individuellement des pages dans la protection.

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

Lorsque quelqu'un accède à une page verrouillée, il obtient une carte de déverrouillage centrée. Elle n'affiche que le nom du site et un indice facultatif, sans barre latérale ni navigation.

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

La carte est habillée du logo et de la couleur principale de votre site, définis dans docs.json. Le champ mot de passe dispose d'un bouton pour révéler la saisie et bénéficie du focus automatique.

Les mots de passe erronés affichent la même carte avec un message d'erreur, un champ de saisie réinitialisé et un léger délai entre les tentatives. Un mot de passe incorrect et une requête sans mot de passe atterrissent tous deux sur le même écran, de sorte que rien sur la page ne distingue « mot de passe erroné » de « aucun mot de passe saisi pour l'instant ».

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 jusqu'à ce que vous la révoquiez.

Rotation et révocation des sessions

Un mot de passe partagé doit finir par changer, par exemple après avoir circulé ou lorsqu'une personne quitte l'équipe.

Ouvrez la carte Password Protection, saisissez une nouvelle phrase de passe dans le champ Rotate password, et cliquez sur Save new password. Toute personne disposant de l'ancien mot de passe est bloquée dès sa prochaine requête ; toute personne disposant du nouveau mot de passe peut entrer. La rotation prend effet immédiatement et ne nécessite pas de nouveau build.

Si vous souhaitez simplement forcer la déconnexion de toutes les sessions actives sans changer la phrase de passe (par exemple, l'ordinateur portable de quelqu'un a disparu), cliquez plutôt sur Revoke all sessions. Cela incrémente un compteur de version côté serveur, ce qui invalide chaque cookie émis avant l'incrément. Les visiteurs ressaisissent le mot de passe actuel et peuvent revenir.

Désactiver la protection

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

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

Au build suivant, Jamdesk supprime le hachage de mot de passe stocké et fait basculer la carte de nouveau à Off. Aucun état « dormant » ne subsiste. Si vous réactivez la protection plus tard, vous devrez choisir un nouveau mot de passe.

Règles de priorité

Une seule page peut être touchée par plusieurs signaux à la fois. L'ordre de résolution, du plus au moins spécifique :

• Si auth.password.enabled vaut true, tout le site est verrouillé. private: true sur des pages individuelles devient redondant.
• Si une page est marquée à la fois public: true et private: true, public l'emporte. Le comportement par défaut le plus sûr est celui qui ne divulgue pas accidentellement une page.
• Le frontmatter public: true, le public: true d'un groupe de navigation, et les globs auth.password.public[] fusionnent tous dans une seule liste d'autorisation. Il n'y a pas de règle « le plus spécifique l'emporte ». Si un seul signal indique qu'une page est publique, elle l'est.
• 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

Cette section couvre le cookie de session, les limites de débit et le stockage du mot de passe.

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. La charge utile 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. L'endpoint 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 hachage scrypt afin qu'une tentative de force brute ne puisse ni consommer de CPU ni divulguer d'informations de timing. Atteindre l'une ou l'autre limite renvoie 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 n'atterrit jamais dans votre dépôt, votre docs.json, ou un artefact de build. Si vous le perdez, faites une rotation. Aucun chemin de récupération n'existe.

Tester en développement local

jamdesk dev exécute votre documentation contre le contenu R2 en direct et la configuration en direct. La protection par mot de passe n'est pas appliquée dans le serveur de développement local, ce qui vous permet de 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à les clés du dépôt, et bloquer la prévisualisation locale derrière un mur de mot de passe serait une friction sans bénéfice de sécurité.

Si vous souhaitez vérifier la protection réelle, accédez au site déployé sur <slug>.jamdesk.app (ou votre domaine personnalisé) depuis une fenêtre de navigateur qui n'a pas encore le cookie.

Dépannage

Et ensuite ?