Authentification JWT

Si votre produit dispose déjà de son propre système de connexion, l'authentification JWT vous permet de protéger vos docs avec celui-ci au lieu de distribuer une phrase de passe partagée. Votre backend signe un token de courte durée lorsqu'un utilisateur connecté accède aux docs. Jamdesk le vérifie une fois, crée une session, et le visiteur navigue ensuite normalement. Les visiteurs n'ont jamais besoin d'un compte Jamdesk ni d'un mot de passe partagé.

Différences avec la protection par mot de passe

Protection par mot de passe donne à chaque visiteur la même phrase de passe partagée, ce qui convient bien aux docs internes, aux previews de staging ou à une audience limitée à un seul partenaire. L'authentification JWT est propre à chaque utilisateur : l'identité, la durée de session et l'accès aux pages de chaque visiteur proviennent d'un token que votre backend signe. L'accès aux docs peut suivre vos comptes clients, plans ou rôles existants au lieu d'un secret unique partagé.

Les deux modes s'excluent mutuellement : auth.password et auth.jwt ne peuvent pas être activés en même temps. Consultez Migrer depuis la protection par mot de passe ci-dessous si vous passez de l'un à l'autre.

Étapes de configuration

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "Acme Docs",
  "theme": "jam",
  "auth": {
    "jwt": {
      "enabled": true,
      "loginUrl": "https://app.example.com/docs-login",
      "public": ["/changelog/*"]
    }
  }
}

git add docs.json
git commit -m "Turn on JWT authentication"
git push

Intégrer votre flux de connexion

Lorsqu'un utilisateur connecté accède à vos docs, votre backend signe un JWT et redirige le navigateur vers l'URL de callback du site de docs, avec le token dans le fragment de l'URL (après le #). Les fragments n'atteignent jamais vos journaux serveur ni aucun reverse proxy, car les navigateurs ne les envoient pas avec la requête.

Le token doit être signé avec EdDSA (Ed25519, correspondant à la clé générée dans le dashboard), et sa claim exp ne doit pas dépasser environ 10 secondes dans le futur. Il s'agit d'une fenêtre de handshake, pas d'une durée de session. La durée de session réelle est contrôlée séparément par le champ expiresAt du payload (voir la référence du payload ci-dessous).

import { SignJWT, importPKCS8 } from "jose";

// Store this in your secret manager. It's the private key Jamdesk showed
// you once when you generated it in Project Settings.
const privateKey = await importPKCS8(process.env.JAMDESK_JWT_PRIVATE_KEY!, "EdDSA");

async function signDocsToken(user: { groups: string[]; apiToken: string }) {
  return new SignJWT({
    host: "acme.jamdesk.app", // or your custom domain, e.g. "docs.example.com"
    expiresAt: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 7, // 7-day session
    groups: user.groups,
    apiPlaygroundInputs: {
      header: { Authorization: `Bearer ${user.apiToken}` },
    },
  })
    .setProtectedHeader({ alg: "EdDSA" })
    .setExpirationTime("10s") // handshake window, not session length
    .sign(privateKey);
}

// In your "open docs" route/button handler:
app.get("/docs-login", requireAuth, async (req, res) => {
  const token = await signDocsToken(req.user);
  const redirect = req.query.redirect ?? "/";
  res.redirect(
    `https://acme.jamdesk.app/_jd/auth/callback?redirect=${encodeURIComponent(
      String(redirect)
    )}#${token}`
  );
});

Flux de redirection

1. Un visiteur demande une page protégée (par exemple, /quickstart) sans session valide. Jamdesk répond par une redirection vers {loginUrl}?redirect=%2Fquickstart.
2. Votre flux de connexion authentifie le visiteur (de la manière habituelle), signe un JWT, et le redirige vers https://<your-docs-host>/_jd/auth/callback?redirect=%2Fquickstart#<jwt>.
3. La page de callback lit le token dans le fragment côté client et l'envoie à l'endpoint d'échange de token de Jamdesk. Jamdesk vérifie la signature et les claims, et en cas de succès définit un cookie de session signé.
4. Le navigateur est redirigé vers la destination d'origine, /quickstart, désormais avec une session valide. La valeur redirect est conservée de bout en bout afin que les visiteurs arrivent exactement là où ils avaient commencé.

Si votre backend ne peut pas déterminer de valeur redirect (si quelqu'un a mis votre page de connexion en favori directement, par exemple), omettez-la et Jamdesk se rabat sur /.

Pages publiques

Certaines pages doivent rester accessibles sans connexion, comme une page de statut ou un changelog public. Il existe trois façons de marquer une page comme publique, et elles fusionnent toutes dans une seule liste blanche :

Frontmatter, pour une page à la fois :

---
title: Changelog
public: true
---

Groupes de navigation, pour toute une section :

{
  "navigation": {
    "groups": [
      { "group": "Changelog", "public": true, "pages": ["changelog"] }
    ]
  }
}

Globs explicites, sous auth.jwt.public[] :

{
  "auth": {
    "jwt": {
      "enabled": true,
      "loginUrl": "https://app.example.com/docs-login",
      "public": ["/changelog/*", "/status"]
    }
  }
}

Marquer une page comme publique ouvre la page elle-même. Les images et vidéos qu'elle contient sont servies depuis les chemins d'assets de votre projet, qui restent derrière la protection, si bien qu'un visiteur non connecté voit une page publique sans ses images. Ajoutez les chemins d'assets à auth.jwt.public[] lorsqu'une page publique en a besoin :

{
  "auth": {
    "jwt": {
      "public": ["/changelog/*", "/status", "/_jd/images/changelog/**"]
    }
  }
}

Limitez le glob aux dossiers réellement utilisés par vos pages publiques. Les chemins d'assets ne sont jamais vérifiés par groupe, donc un glob large comme /_jd/images/** sert toutes les images du site à n'importe qui, y compris les captures d'écran des pages que vous avez restreintes avec groups. Gardez les images des pages publiques dans leur propre dossier et n'ouvrez que ce dossier.

Accès basé sur les groupes

Certaines pages ne doivent être visibles que par certains utilisateurs authentifiés, comme un runbook admin ou une référence réservée aux comptes enterprise. Ajoutez groups au frontmatter d'une page :

---
title: Admin API Keys
groups: ["admin"]
---

La session d'un visiteur porte le tableau groups que votre backend a placé dans le payload du JWT. Si une page déclare groups et que la session du visiteur ne recoupe pas cette liste, il obtient une 404 plutôt qu'une 401 ou un écran de déverrouillage. C'est volontaire : une page restreinte par groupe ne révèle pas sa propre existence aux utilisateurs qui n'en font pas partie.

Détails qui affectent votre utilisation de groups :

• Les pages de groupe sont exclues du sitemap, de la recherche, du chat IA et du MCP, même pour les utilisateurs qui font partie du groupe. L'exclusion de ces surfaces de découverte est une décision prise au moment du build, pas par visiteur. Un membre du groupe admin peut toujours ouvrir /admin/api-keys directement (par URL ou lien interne), mais elle n'apparaîtra pas dans les résultats de recherche, les réponses du chat, ou llms.txt. Si vous avez besoin qu'une page restreinte soit trouvable par son propre public, ajoutez-y un lien depuis une autre page que ce public peut déjà atteindre.
• Un groups: [] vide signifie qu'il n'y a aucune restriction, pas « personne ne peut voir ceci ». Pour supprimer la restriction de groupe d'une page, supprimez complètement le champ groups plutôt que de le définir comme un tableau vide.
• Pour restreindre une page à personne, dépubliez-la. Il n'existe aucune valeur de groups qui signifie « personne » : l'appartenance à un groupe est additive, et tout recoupement accorde l'accès.
• Les copies localisées héritent automatiquement du groups de la page de base, sauf si la traduction déclare son propre groups dans son frontmatter. Traduire une page restreinte ne rend pas accidentellement la traduction publique.
• Jamdesk détermine quels dossiers de premier niveau sont des traductions à partir de navigation.languages, ainsi que tout dossier de premier niveau nommé d'après un code de langue (fr, it, cs, etc.) qui contient des pages. Un dossier qui ne fait que partager son nom avec un code de langue, par exemple un dossier it contenant des runbooks informatiques, est lui aussi traité comme une traduction, et ses pages héritent du groups de toute page racine au même chemin. Cela ne peut que restreindre davantage, jamais moins. Renommez le dossier s'il vous gêne.
• groups restreint les pages, pas les images, vidéos et autres fichiers qu'une page intègre. Un asset auquel seule une page restreinte fait référence est toujours servi à tout visiteur connecté qui en demande l'URL, quels que soient les groupes portés par sa session. Les URLs d'assets suivent les chemins de fichiers de votre repo, donc un nom comme images/admin/sso-config.png est facile à deviner. Gardez hors du repo de docs tout ce que vous ne voulez pas que chaque lecteur connecté puisse voir.
• La barre latérale, les tabs, le fil d'Ariane et les liens précédent/suivant sont filtrés par visiteur. Une page que les groupes du visiteur ne couvrent pas est exclue, et un groupe ou un tab qui se retrouve vide est exclu avec elle, afin que le nom d'une section restreinte ne soit pas montré aux personnes qui n'en font pas partie. Ce filtrage a lieu au moment de la requête et est distinct des exclusions au moment du build mentionnées ci-dessus, qui s'appliquent à tout le monde.
• Gardez les noms de groupes courts. Les groupes voyagent dans le cookie de session : jusqu'à 32 groupes par session, 64 caractères chacun. Dépasser l'une ou l'autre limite ne tronque pas la liste ; Jamdesk rejette le token entier avec une 401 et n'accorde aucune session.

Pré-remplissage du playground API

Si vos docs ont un playground API, vous pouvez le pré-remplir pour les visiteurs connectés afin qu'ils n'aient pas à coller leur propre clé API. Incluez apiPlaygroundInputs dans le payload de votre JWT :

{
  "host": "acme.jamdesk.app",
  "apiPlaygroundInputs": {
    "header": { "Authorization": "Bearer sk_live_user_specific_token" },
    "query": { "org_id": "acme-corp" },
    "path": { "workspace_id": "ws_123" }
  }
}

• header.Authorization pré-remplit le champ d'authentification du playground. Un préfixe Bearer est retiré automatiquement s'il est présent.
• query et path pré-remplissent tout nom de paramètre correspondant sur l'endpoint actuel.
• Les sections server et cookie ne sont pas prises en charge. Seuls header, query, et path sont appliqués.
• Le pré-remplissage n'écrase jamais une valeur que le visiteur a déjà saisie dans le playground.

Référence du payload

Rotation de la clé de signature

Rotate signing key sur la carte du dashboard génère une nouvelle paire de clés et affiche la nouvelle clé privée une fois, de la même façon que lors de la première génération. Il n'y a pas de période de chevauchement. En environ 15 secondes, l'ancienne clé cesse d'être acceptée et toutes les sessions existantes se terminent. Tant que votre backend ne signe pas avec la nouvelle clé, chaque connexion est rejetée et les visiteurs font des allers-retours entre votre page de connexion et les docs.

L'ordre a donc de l'importance :

1. Préparez un déploiement qui lit la clé de signature depuis votre gestionnaire de secrets plutôt que depuis une valeur codée en dur.
2. Cliquez sur Rotate signing key et copiez la nouvelle clé privée.
3. Mettez à jour le secret et déployez. Les connexions refonctionnent dès que votre backend utilise la nouvelle clé.

Effectuez la rotation à un moment calme si possible, et prévenez la personne responsable du déploiement backend avant de cliquer.

Si vous voulez simplement terminer la session de tout le monde, par exemple après la perte d'un ordinateur portable, utilisez plutôt Revoke sessions. Cela conserve la clé, donc rien ne change dans votre backend ; chaque visiteur doit simplement se reconnecter.

Clear signing key supprime la clé publique de Jamdesk. auth.jwt reste activé dans docs.json, donc le site reste protégé, mais aucun token ne peut être vérifié tant que vous n'avez pas généré une nouvelle clé. Ne l'utilisez que lorsque vous faites passer le site à un autre mode d'accès ou que vous le retirez.

Déconnexion

Les visiteurs connectés obtiennent un lien Log out dans l'en-tête des docs. Il les envoie vers /_jd/auth/logout, qui efface le cookie de session et redirige vers votre loginUrl. Vous pouvez aussi y créer un lien directement depuis votre propre application si vous voulez un lien « se déconnecter des docs » ailleurs. C'est une simple requête GET sans corps ni en-têtes requis.

Se déconnecter des docs ne déconnecte pas le visiteur de votre produit. Si votre flux de connexion signe un token pour toute personne ayant déjà une session dans l'application, un visiteur qui clique sur Log out puis ouvre un lien vers les docs est immédiatement reconnecté. C'est généralement le comportement souhaité. Si vous avez besoin d'une vraie déconnexion, faites en sorte que votre gestionnaire de loginUrl vérifie une connexion explicite plutôt que de créer un token automatiquement, ou faites aussi pointer votre propre déconnexion vers l'URL de déconnexion des docs.

Comportement des fonctionnalités sous authentification

Dépannage

Note de sécurité

apiPlaygroundInputs, y compris toute valeur d'Authorization que vous y placez, est lisible par le JavaScript s'exécutant sur votre site de docs via l'endpoint session-info qui alimente le pré-remplissage du playground. Le pré-remplissage est pratique, mais ce n'est pas un endroit pour des secrets à haut privilège.

Envoyez des identifiants par utilisateur, à privilège minimal, limités à ce que ce visiteur est autorisé à faire, jamais une clé admin valable pour toute l'organisation. Considérez que tout ce que vous placez dans apiPlaygroundInputs est visible par la personne qui parcourt les docs, car c'est le cas.

Migrer depuis la protection par mot de passe

Passer d'un mot de passe partagé à l'authentification JWT ne nécessite aucune interruption de service, et le site reste protégé pendant toute la durée. Procédez dans cet ordre :

{
  "auth": {
    "password": { "enabled": false },
    "jwt": { "enabled": true, "loginUrl": "https://app.example.com/docs-login" }
  }
}

Et ensuite ?