---
title: Protection par mot de passe
description: Verrouillez l'intégralité de votre site de documentation ou quelques pages avec un mot de passe partagé. Les visiteurs voient un écran de déverrouillage ; le reste reste ouvert.
---
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.
Vous devez avoir un projet Jamdesk [connecté à un dépôt Git](/fr/setup/connecting-github) avant d'activer la protection par mot de passe. La configuration se trouve dans `docs.json`, donc la protection par mot de passe s'intègre à votre flux habituel de build et de déploiement.
## 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.
| | **Mode site entier** | **Mode pages spécifiques** |
|---|---|---|
| **Utiliser quand** | Tout est privé : docs d'ingénierie interne, copie de staging de votre site public, produit non encore sorti. | La plupart des docs sont publiques. Vous souhaitez simplement masquer quelques pages (un runbook, une fonctionnalité bêta, une référence API interne). |
| **Comment l'activer** | Définir `auth.password.enabled: true` dans `docs.json`. | Marquer les pages comme privées avec `private: true` dans le frontmatter, ou lister les chemins sous `auth.password.private[]`. |
| **Exceptions publiques** | Oui : marquer des pages individuelles, des groupes de navigation ou des patterns glob comme publics. | N/A. Chaque page est publique sauf si vous la marquez comme privée. |
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
Ouvrez votre `docs.json` et déclarez la protection du site entier. Le champ `hint` est facultatif mais fortement recommandé, car c'est le seul indice affiché à l'écran pour indiquer à vos lecteurs comment obtenir le mot de passe.
```json docs.json
{
"$schema": "https://jamdesk.com/docs.json",
"name": "Acme Docs",
"theme": "jam",
"auth": {
"password": {
"enabled": true,
"hint": "Ask #docs-access on Slack"
}
}
}
```
Les indications sont en texte brut, 200 caractères maximum, sans HTML.
Ne mettez pas le mot de passe lui-même dans `docs.json`. Vous définissez le mot de passe dans le dashboard après le build. Votre dépôt contient uniquement le flag d'activation et un indice facultatif.
Poussez la modification sur votre branche configurée. Jamdesk lance un build et, pendant celui-ci, active la protection par mot de passe en mode site entier.
```bash
git add docs.json
git commit -m "Turn on password protection"
git push
```
Pendant que vous tapiez, la carte dans le dashboard est passée de **Désactivé** à **Mot de passe non défini**, et votre site a commencé à retourner `401` pour chaque page. Tant que vous n'avez pas défini de mot de passe, toutes les requêtes sont rejetées. La porte est fermée et n'a pas encore de clé.
Ouvrez **Paramètres du projet** dans le dashboard et faites défiler jusqu'à la carte **Protection par mot de passe**. Saisissez une phrase secrète robuste (8 caractères minimum), puis cliquez sur **Définir le mot de passe**.
La carte passe à l'état **Activé**. Toute personne possédant le mot de passe peut désormais parcourir le site ; les autres arrivent sur l'écran de déverrouillage.
Jamdesk ne stocke jamais votre mot de passe en clair. Il est haché avec scrypt dans la base de données du dashboard et n'est jamais écrit dans votre dépôt ni dans `docs.json`. Cela signifie aussi que Jamdesk ne peut pas vous l'envoyer par e-mail si vous l'oubliez. Effectuez une rotation à la place.
Ouvrez votre site de documentation dans une fenêtre de navigation privée (ou avec `curl`) et confirmez que vous obtenez l'écran de déverrouillage. Essayez un mauvais mot de passe pour vérifier l'état d'erreur, puis le bon pour accéder au contenu.
```bash
# 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_ cookie.
curl -i -X POST https://acme.jamdesk.app/jd/unlock \
-d "password=your-passphrase&from=/"
```
Un déverrouillage réussi retourne une redirection `303` avec un en-tête `Set-Cookie: jd_auth_acme=...; HttpOnly; Secure; SameSite=Lax; Max-Age=2592000`. Conservez ce cookie pour la requête suivante et vous êtes connecté.
### 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 :
```yaml
---
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 :
```json docs.json
{
"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.
```json docs.json
{
"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.
Ajoutez `private: true` dans le frontmatter de la page. C'est l'option la plus simple quand la décision appartient à celui qui possède la page.
```yaml
---
title: Incident Runbook
description: What to do when the deploys dashboard is on fire.
private: true
---
```
Ou, si vous préférez centraliser la liste des chemins verrouillés dans un seul fichier, ajoutez-les sous `auth.password.private[]` dans `docs.json`. Les deux approches sont additives, vous pouvez donc les combiner.
```json docs.json
{
"auth": {
"password": {
"hint": "Ask the on-call engineer",
"private": ["/admin/runbook", "/internal/api-keys"]
}
}
}
```
Notez l'absence d'`enabled: true`. Définir `auth.password.private[]` sans `enabled` est ce qui active automatiquement le mode pages spécifiques.
Poussez vos modifications. Le build suivant détecte les pages privées, active la protection en mode pages spécifiques, et affiche dans le dashboard l'invite pour définir un mot de passe, exactement comme en mode site entier.
```bash
git add content/runbook.mdx docs.json
git commit -m "Gate the incident runbook"
git push
```
Ouvrez **Paramètres du projet**, trouvez la carte **Protection par mot de passe**, et définissez une phrase secrète. L'en-tête de la carte indique maintenant **Activé** avec **Pages spécifiques** au lieu de **Site entier**, et affiche la liste des pages privées que le build a résolues afin que vous puissiez l'auditer d'un coup d'œil.
Parcourez votre site de documentation normalement. Les pages publiques doivent se charger comme avant ; les pages privées doivent vous rediriger vers l'écran de déverrouillage. Une fois le mot de passe saisi, vous êtes connecté pendant 30 jours sur cet appareil et pouvez lire n'importe quelle page privée sans avoir à le ressaisir.
## 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.
Votre dépôt source n'est pas protégé par mot de passe. La protection par mot de passe verrouille le site de documentation hébergé sur `*.jamdesk.app` (ou votre domaine personnalisé). Si votre dépôt GitHub est public, le contenu MDX y reste lisible. Rendez le dépôt privé si vous avez besoin d'une protection totale du contenu.
## 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_` (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 `.jamdesk.app` (ou votre domaine personnalisé) depuis une fenêtre de navigateur qui ne possède pas encore le cookie.
## Dépannage
La carte dans le dashboard affiche probablement **Mot de passe non défini**. La protection ne s'active pas tant que vous n'avez pas (1) poussé la configuration dans `docs.json` et (2) défini un mot de passe dans **Paramètres du projet**. Tant que la deuxième étape n'est pas complétée, chaque requête retourne `401` avec l'écran de déverrouillage comme corps de réponse, ce qui peut donner l'impression que l'écran « n'apparaît pas » si vous attendiez une destination spécifique.
Son navigateur possède un ancien cookie `jd_auth_` d'avant la rotation. Attendez soit 30 jours que le cookie expire, cliquez sur **Révoquer toutes les sessions** dans le dashboard, ou demandez-lui de supprimer les cookies pour le domaine de la documentation. Il lui sera demandé le mot de passe actuel lors de sa prochaine visite.
Pas directement. Jamdesk utilise un seul mot de passe partagé par site. Si vous avez besoin d'un accès par groupe, divisez vos docs en plusieurs projets (chacun avec son propre mot de passe) ou utilisez le mode pages spécifiques avec des limites publiques/privées distinctes pour chaque audience.
Oui. Le cookie de déverrouillage est lié à l'hôte, donc chaque hôte (le sous-domaine `*.jamdesk.app` et votre domaine personnalisé) s'authentifie indépendamment. Les lecteurs qui déverrouillent un hôte ne seront pas pré-authentifiés sur l'autre.
Non. Les sites protégés définissent `noindex, nofollow` sur l'écran de déverrouillage et retournent `401` pour chaque page verrouillée, de sorte que les robots d'indexation ne peuvent rien indexer derrière le verrouillage. Les pages publiques à l'intérieur d'un site protégé restent indexables normalement.
## Prochaines étapes
Comparez la protection par mot de passe avec SSO et le modèle multi-projets.
Remplacez les phrases secrètes partagées par une connexion par utilisateur via votre fournisseur d'identité.
Mettez vos docs sur votre propre domaine avant de partager le lien.
Référence complète des champs `enabled`, `hint`, `public` et `private`.