Contrôle d'accès
Choisissez comment les lecteurs accèdent à vos docs : public, protégé par mot de passe, mixte, JWT ou SSO. Trouvez la formule adaptée à votre audience.
Jamdesk vous offre cinq façons de contrôler qui peut lire vos docs. La plupart des équipes en choisissent une et s'y tiennent ; certaines combinent plusieurs approches.
Choisir la bonne approche
| Approche | À utiliser quand | Configuration |
|---|---|---|
| Entièrement public | Documentation produit destinée à l'externe, projets open source, tout contenu que vous voulez indexé et partageable. | Par défaut ; aucune configuration nécessaire. |
| Mot de passe pour tout le site | Tout est interne : runbooks d'ingénierie, docs réservées aux partenaires, un produit non publié. Une phrase de passe partagée protège l'ensemble du site. | auth.password.enabled: true dans docs.json + définir le mot de passe dans le dashboard. Voir Protection par mot de passe. |
| Mixte (certaines pages privées) | La plupart des docs sont publiques ; quelques-unes sont internes (un runbook, une fonctionnalité bêta, une référence API interne). | Ajoutez private: true au frontmatter des pages internes, ou listez-les sous auth.password.private[]. Voir Protection par mot de passe. |
| Votre propre connexion (JWT) | Les lecteurs se connectent déjà à votre produit. Votre backend signe un jeton de courte durée pour chacun d'eux, Jamdesk le transforme en session, et les pages peuvent être limitées aux groupes que vous nommez dans le jeton. | auth.jwt.enabled: true plus une loginUrl dans docs.json, et une clé de signature depuis le dashboard. Inclus dans tous les plans. Voir Authentification JWT. |
| SSO (Enterprise) | Les lecteurs se connectent avec votre fournisseur d'identité existant : pas de mots de passe partagés, une piste d'audit, et une révocation d'accès en supprimant l'utilisateur. | Plan Enterprise. Voir SSO. |
Vous pouvez changer d'approche à tout moment en modifiant docs.json et en poussant. Passer du mode site entier au mode mixte (ou inversement) ne prend qu'un build.
Modèles courants
Docs internes et externes dans un seul projet
La plupart des équipes veulent une documentation interne complète derrière une connexion, ainsi qu'un site public plus restreint pour les clients. Vous n'avez pas besoin de deux projets. Utilisez le mode mixte dans un seul projet Jamdesk :
---
title: Incident Runbook
private: true
---Les pages avec private: true sont protégées ; tout le reste reste public. Tout est hébergé dans un seul dépôt avec un seul build et un seul dashboard. L'écran de déverrouillage n'apparaît que lorsqu'un lecteur accède à une page protégée.
Pour des sections internes plus vastes, listez les chemins dans docs.json plutôt que de marquer chaque fichier. Remarque : auth.password.private[] active automatiquement le mode pages spécifiques. N'ajoutez pas enabled: true en même temps (c'est le mode site entier, l'inverse de ce que vous voulez ici).
{
"auth": {
"password": {
"hint": "Ask the on-call engineer",
"private": ["/internal/**", "/admin/runbook"]
}
}
}Deux projets séparés
N'utilisez deux projets que lorsque les audiences ont besoin d'une image de marque totalement différente, de domaines personnalisés séparés, d'une analytique séparée, ou de niveaux de plan différents. Exemples : un site de documentation public sur docs.acme.com et un wiki interne séparé sur internal.acme.com. Le coût de maintenance est plus élevé : deux builds, deux dashboards, deux domaines.
Accès par utilisateur via votre propre connexion
Si vos clients ont déjà des comptes chez vous, un mot de passe partagé est un pas en arrière : il se transmet, il n'expire jamais de lui-même, et il ne peut pas distinguer un client d'un autre. Avec l'authentification JWT, un utilisateur connecté qui ouvre vos docs est redirigé vers une URL de votre côté, votre backend signe un jeton, et Jamdesk crée une session pour cette personne. Les lecteurs n'ont besoin d'aucun compte Jamdesk, et il n'y a aucun secret partagé à faire circuler.
Le jeton peut aussi transporter des groupes. Ajoutez groups: ["admin"] au frontmatter d'une page et seuls les visiteurs dont le jeton liste admin peuvent l'ouvrir ou la voir dans la navigation. Tous les autres obtiennent une 404, si bien que la page ne révèle pas son existence.
---
title: Enterprise audit log API
groups: ["enterprise"]
---Associez-le à des chemins public pour les parties du site qui doivent rester ouvertes, comme un changelog ou une page de statut.
SSO pour le site de documentation
Sur les plans Enterprise, les lecteurs se connectent avec votre fournisseur d'identité (Okta, Google Workspace, Azure AD, etc.) au lieu de saisir un mot de passe partagé. Idéal lorsque vous avez besoin d'une piste d'audit de qui a lu quoi, ou lorsque le départ d'un utilisateur doit immédiatement révoquer son accès aux docs. Voir SSO pour une vue d'ensemble et savoir comment entamer une conversation avec l'équipe commerciale.
Éditeurs et lecteurs
Les gens confondent parfois trois concepts d'accès différents :
| Rôle | Ce qu'ils font | Comment l'accès est accordé |
|---|---|---|
| Éditeurs | Rédigent et mettent à jour le contenu MDX. | Les docs sont modifiées en committant du MDX dans votre dépôt GitHub connecté, donc les permissions de votre dépôt GitHub sont les permissions d'éditeur. Il n'y a pas de rôle d'éditeur Jamdesk séparé superposé : quiconque peut pousser sur votre branche de docs peut publier une modification. |
| Lecteurs | Consultent le site de documentation publié. | Tout le monde (public), toute personne disposant du mot de passe (mode mot de passe), toute personne pour laquelle votre flux de connexion signe un jeton (JWT), ou toute personne authentifiée via votre IdP (SSO). |
| Membres de l'équipe du dashboard | Gèrent les builds, l'analytique et les paramètres du projet dans le dashboard Jamdesk. | Invités via Settings → Team dans le dashboard. Ils ne rédigent pas de contenu directement. Voir Membres de l'équipe. |
Un coéquipier peut être n'importe quelle combinaison des trois. Ce sont des axes indépendants.