JWT-Authentifizierung

Wenn Ihr Produkt bereits über ein eigenes Login-System verfügt, können Sie mit der JWT-Authentifizierung Ihre Dokumentation darüber schützen, anstatt ein gemeinsames Passwort zu vergeben. Ihr Backend signiert ein kurzlebiges Token, wenn ein angemeldeter Benutzer über einen Link zur Dokumentation gelangt. Jamdesk überprüft es einmal, erstellt eine Sitzung und der Besucher kann anschließend normal navigieren. Besucher benötigen weder ein Jamdesk-Konto noch ein gemeinsames Passwort.

Unterschiede zum Passwortschutz

Passwortschutz gibt jedem Besucher dasselbe gemeinsame Passwort. Das eignet sich gut für interne Dokumentation, Staging-Vorschauen oder eine einzelne Partnerzielgruppe. Die JWT-Authentifizierung gilt pro Benutzer: Identität, Sitzungsdauer und Seitenzugriff jedes Besuchers werden durch ein Token bestimmt, das Ihr Backend signiert. Der Zugriff auf die Dokumentation kann Ihren bestehenden Kundenkonten, Tarifen oder Rollen folgen, anstatt auf einem gemeinsamen Geheimnis zu beruhen.

Die beiden Modi schließen sich gegenseitig aus: auth.password und auth.jwt können nicht gleichzeitig aktiviert sein. Wenn Sie von einem Modus zum anderen wechseln, lesen Sie unten Von Passwortschutz migrieren.

Einrichtungsschritte

{
  "$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

Ihren Login-Ablauf integrieren

Wenn ein angemeldeter Benutzer über einen Link zu Ihrer Dokumentation gelangt, signiert Ihr Backend ein JWT und leitet den Browser mit dem Token im URL-Fragment (nach dem #) zur Callback-URL der Dokumentations-Website weiter. Fragmente gelangen niemals in Ihre Serverprotokolle oder zu einem Reverse Proxy, da Browser sie nicht zusammen mit der Anfrage senden.

Das Token muss mit EdDSA (Ed25519, passend zum im Dashboard generierten Schlüssel) signiert sein. Sein exp-Claim sollte höchstens etwa 10 Sekunden in der Zukunft liegen. Dies ist ein Zeitfenster für den Handshake, keine Sitzungsdauer. Die tatsächliche Sitzungsdauer wird separat durch das Feld expiresAt in der Payload gesteuert (siehe unten die Payload-Referenz).

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[] }) {
  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}`
  );
});

import time
import jwt  # PyJWT >= 2.4, with the cryptography extra installed

with open("jamdesk_jwt_private_key.pem", "rb") as f:
    PRIVATE_KEY = f.read()

def sign_docs_token(user):
    payload = {
        "host": "acme.jamdesk.app",  # or your custom domain
        "exp": int(time.time()) + 10,  # handshake window, not session length
        "expiresAt": int(time.time()) + 60 * 60 * 24 * 7,  # 7-day session
        "groups": user.groups,
        "apiPlaygroundInputs": {
            "header": {"Authorization": f"Bearer {user.api_token}"},
        },
    }
    return jwt.encode(payload, PRIVATE_KEY, algorithm="EdDSA")

@app.route("/docs-login")
def docs_login():
    token = sign_docs_token(current_user)
    redirect_path = request.args.get("redirect", "/")
    return redirect(
        f"https://acme.jamdesk.app/_jd/auth/callback"
        f"?redirect={quote(redirect_path)}#{token}"
    )

Weiterleitungsablauf

1. Ein Besucher ruft eine geschützte Seite (zum Beispiel /quickstart) ohne gültige Sitzung auf. Jamdesk antwortet mit einer Weiterleitung zu {loginUrl}?redirect=%2Fquickstart.
2. Ihr Login-Ablauf authentifiziert den Besucher (auf die für Sie übliche Weise), signiert ein JWT und leitet ihn zu https://<your-docs-host>/_jd/auth/callback?redirect=%2Fquickstart#<jwt> weiter.
3. Die Callback-Seite liest das Token clientseitig aus dem Fragment und sendet es an Jamdesks Token-Austausch-Endpoint. Jamdesk überprüft Signatur und Claims und setzt bei Erfolg ein signiertes Sitzungscookie.
4. Der Browser wird nun mit einer gültigen Sitzung zum ursprünglichen Ziel /quickstart weitergeleitet. Der Wert von redirect bleibt durchgehend erhalten, sodass Besucher genau dort landen, wo sie gestartet sind.

Wenn Ihr Backend keinen redirect-Wert bestimmen kann (beispielsweise weil jemand Ihre Login-Seite direkt als Lesezeichen aufgerufen hat), lassen Sie ihn weg. Jamdesk verwendet dann /.

Öffentliche Seiten

Einige Seiten sollten ohne Anmeldung erreichbar bleiben, etwa eine Statusseite oder ein öffentliches Changelog. Es gibt drei Möglichkeiten, eine Seite als öffentlich zu kennzeichnen. Sie werden alle zu einer einzigen Allowlist zusammengeführt:

Frontmatter, jeweils für eine Seite:

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

Navigationsgruppen, für einen ganzen Abschnitt:

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

Explizite Globs unter auth.jwt.public[]:

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

Gruppenbasierter Zugriff

Einige Seiten sollen nur für bestimmte authentifizierte Benutzer sichtbar sein, etwa ein Runbook für Administratoren oder eine Referenz nur für Unternehmenskunden. Fügen Sie dem Frontmatter einer Seite groups hinzu:

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

Die Sitzung eines Besuchers enthält das Array groups, das Ihr Backend in die JWT-Payload eingefügt hat. Wenn eine Seite groups definiert und sich die Sitzung des Besuchers nicht mit dieser Liste überschneidet, erhält der Besucher statt einer 401- oder einer Entsperrseite eine 404. Dies ist beabsichtigt: Eine gruppenbeschränkte Seite soll ihre eigene Existenz gegenüber Benutzern außerhalb der Gruppe nicht preisgeben.

Details zur Verwendung von groups:

• Gruppenseiten werden aus Sitemap, Suche, AI-Chat und MCP ausgeschlossen, auch für Benutzer, die der Gruppe angehören. Der Ausschluss von diesen Auffindbarkeitsflächen wird beim Build und nicht pro Besucher entschieden. Ein Mitglied der Gruppe admin kann /admin/api-keys weiterhin direkt öffnen (über URL oder internen Link), die Seite erscheint jedoch nicht in Suchergebnissen, Chat-Antworten oder llms.txt. Wenn eine eingeschränkte Seite für ihre eigene Zielgruppe auffindbar sein soll, verlinken Sie sie von einer anderen Seite, die diese Zielgruppe bereits erreichen kann.
• Ein leeres groups: [] bedeutet keinerlei Einschränkung, nicht „niemand kann diese Seite sehen“. Um die Gruppenbeschränkung einer Seite zu entfernen, löschen Sie das Feld groups vollständig, anstatt ein leeres Array festzulegen.
• Um eine Seite für niemanden zugänglich zu machen, heben Sie ihre Veröffentlichung auf. Es gibt keinen groups-Wert für „niemand“: Die Gruppenmitgliedschaft ist additiv, und jede Überschneidung gewährt Zugriff.
• Lokalisierte Kopien übernehmen automatisch die groups-Angabe der Ausgangsseite, sofern die Übersetzung nicht ein eigenes groups-Feld in ihrem Frontmatter definiert. Durch die Übersetzung einer eingeschränkten Seite wird die Übersetzung nicht versehentlich öffentlich.
• Halten Sie Gruppennamen kurz. Gruppen werden im Sitzungscookie übertragen: bis zu 32 Gruppen pro Sitzung mit jeweils 64 Zeichen. Wird eines dieser Limits überschritten, wird die Liste nicht gekürzt. Jamdesk weist stattdessen das gesamte Token mit einer 401 zurück und gewährt keine Sitzung.

API-Playground vorausfüllen

Wenn Ihre Dokumentation einen API-Playground enthält, können Sie ihn für angemeldete Besucher vorausfüllen, damit sie ihren eigenen API-Schlüssel nicht einfügen müssen. Fügen Sie apiPlaygroundInputs in Ihre JWT-Payload ein:

{
  "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 füllt das Authentifizierungsfeld des Playgrounds voraus. Ein Präfix Bearer wird automatisch entfernt, falls vorhanden.
• query und path füllen passende Parameternamen des aktuellen Endpoints voraus.
• Die Bereiche server und cookie werden nicht unterstützt. Nur header, query und path werden angewendet.
• Beim Vorausfüllen wird kein Wert überschrieben, den der Besucher bereits in den Playground eingegeben hat.

Referenz zur Payload

Abmelden

Angemeldete Besucher sehen im Header der Dokumentation einen Link Log out. Dieser führt zu /_jd/auth/logout, löscht das Sitzungscookie und leitet zu Ihrer loginUrl weiter. Sie können auch direkt aus Ihrer eigenen App darauf verlinken, wenn Sie an anderer Stelle einen Link zum Abmelden aus der Dokumentation anbieten möchten. Es handelt sich um eine einfache GET-Anfrage, für die weder Body noch Header erforderlich sind.

Verhalten von Funktionen bei aktivierter Authentifizierung

Fehlerbehebung

Sicherheitshinweis

apiPlaygroundInputs, einschließlich jedes darin abgelegten Authorization-Werts, kann von JavaScript gelesen werden, das auf Ihrer Dokumentations-Website über den Session-Info-Endpoint ausgeführt wird, der das Vorausfüllen des Playgrounds ermöglicht. Das Vorausfüllen ist praktisch, aber kein geeigneter Ort für hochprivilegierte Geheimnisse.

Senden Sie benutzerbezogene Zugangsdaten mit den geringstmöglichen Berechtigungen, die auf die erlaubten Aktionen des jeweiligen Besuchers beschränkt sind, niemals einen organisationsweiten Administratorschlüssel. Behandeln Sie alles, was Sie in apiPlaygroundInputs einfügen, als für die Person sichtbar, die die Dokumentation aufruft, denn genau das ist es.

Von Passwortschutz migrieren

Der Wechsel von einem gemeinsamen Passwort zur JWT-Authentifizierung erfordert keine Ausfallzeit, und die Website bleibt durchgehend geschützt. Gehen Sie in dieser Reihenfolge vor:

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

Wie geht es weiter?