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 eine gemeinsame Passphrase zu vergeben. Ihr Backend signiert ein kurzlebiges Token, wenn ein angemeldeter Benutzer zur Dokumentation wechselt. Jamdesk überprüft es einmal, erstellt eine Sitzung und der Besucher kann danach normal navigieren. Besucher benötigen weder ein Jamdesk-Konto noch ein gemeinsames Passwort.

Unterschiede zum Passwortschutz

Passwortschutz stellt jedem Besucher dieselbe gemeinsame Passphrase bereit. 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 stammen aus einem Token, das Ihr Backend signiert. Der Zugriff auf die Dokumentation kann Ihren bestehenden Kundenkonten, Tarifen oder Rollen folgen, statt auf einem gemeinsamen Geheimnis zu basieren.

Die beiden Modi schließen sich gegenseitig aus: auth.password und auth.jwt können nicht gleichzeitig aktiviert sein. Lesen Sie weiter unten Migration vom Passwortschutz, wenn Sie von einem Modus zum anderen wechseln.

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 zu Ihrer Dokumentation wechselt, signiert Ihr Backend ein JWT und leitet den Browser mit dem Token im URL-Fragment (nach dem #) an die Callback-URL der Dokumentationsseite weiter. Fragmente erreichen weder Ihre Serverprotokolle noch einen Reverse Proxy, da Browser sie nicht mit der Anfrage senden.

Das Token muss mit EdDSA (Ed25519, passend zu dem im Dashboard generierten Schlüssel) signiert sein. Sein exp-Claim sollte höchstens etwa 10 Sekunden in der Zukunft liegen. Das ist ein Zeitfenster für den Handshake, keine Sitzungsdauer. Die tatsächliche Sitzungsdauer wird separat über 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[]; 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}`
  );
});

import time
from urllib.parse import quote

import jwt  # PyJWT >= 2.4, with the cryptography extra installed
from flask import redirect, request  # or your framework's equivalents

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 fordert eine geschützte Seite an, beispielsweise /quickstart, ohne gültige Sitzung an. Jamdesk antwortet mit einer Weiterleitung zu {loginUrl}?redirect=%2Fquickstart.
2. Ihr Login-Ablauf authentifiziert den Besucher (auf die ü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 Sitzungs-Cookie.
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 begonnen haben.

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

Öffentliche Seiten

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

Frontmatter, für jeweils 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"]
    }
  }
}

Eine Seite öffentlich zu machen, öffnet die Seite selbst. Die Bilder und Videos darauf werden über die Asset-Pfade Ihres Projekts ausgeliefert, und die bleiben hinter der Absicherung, sodass ein nicht angemeldeter Besucher eine öffentliche Seite ohne ihre Abbildungen sieht. Nehmen Sie die Asset-Pfade in auth.jwt.public[] auf, wenn eine öffentliche Seite sie braucht:

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

Beschränken Sie den Glob auf die Ordner, die Ihre öffentlichen Seiten tatsächlich verwenden. Asset-Pfade werden nie auf Gruppen geprüft. Ein weit gefasster Glob wie /_jd/images/** liefert deshalb jedes Bild der Website an beliebige Besucher aus, einschließlich der Screenshots in Seiten, die Sie mit groups eingeschränkt haben. Legen Sie die Bilder öffentlicher Seiten in einen eigenen Ordner und öffnen Sie nur diesen.

Zugriff auf Gruppenbasis

Einige Seiten sollten 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 geschrieben hat. Wenn eine Seite groups festlegt und sich die Sitzung des Besuchers nicht mit dieser Liste überschneidet, erhält der Besucher statt einer 401 oder eines Entsperrbildschirms einen 404. Dies ist beabsichtigt: Eine auf eine Gruppe beschränkte Seite soll ihre Existenz für Benutzer außerhalb der Gruppe nicht preisgeben.

Details zur Verwendung von groups:

• Gruppenseiten werden aus Sitemap, Suche, KI-Chat und MCP ausgeschlossen, selbst für Benutzer, die der Gruppe angehören. Der Ausschluss aus diesen Auffindbarkeitsflächen wird beim Build festgelegt, nicht pro Besucher. 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 keine Einschränkung, nicht „niemand darf 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“: Gruppenmitgliedschaften sind additiv, und jede Überschneidung gewährt Zugriff.
• Lokalisierte Kopien übernehmen automatisch die groups-Angabe der Basisseite, sofern die Übersetzung nicht eigene groups im Frontmatter festlegt. Durch die Übersetzung einer eingeschränkten Seite wird die Übersetzung nicht versehentlich öffentlich.
• Jamdesk ermittelt anhand von navigation.languages, welche Ordner auf oberster Ebene Übersetzungen enthalten. Zusätzlich gelten alle Ordner auf oberster Ebene als Übersetzungen, die nach einem Sprachcode benannt sind (fr, it, cs usw.) und Seiten enthalten. Ein Ordner, der nur denselben Namen wie ein Sprachcode trägt, beispielsweise ein it-Ordner mit Runbooks der IT-Abteilung, wird ebenfalls als Übersetzung behandelt. Seine Seiten übernehmen die groups-Angaben jeder Root-Seite am selben Pfad. Dies kann nur stärker einschränken, niemals weniger. Benennen Sie den Ordner um, wenn dies störend ist.
• groups schränkt Seiten ein, nicht die Bilder, Videos und sonstigen Dateien, die eine Seite einbindet. Ein Asset, auf das nur eine eingeschränkte Seite verweist, wird weiterhin an jeden angemeldeten Besucher ausgeliefert, der seine URL aufruft, unabhängig von den Gruppen seiner Sitzung. Asset-URLs folgen den Dateipfaden Ihres Repositorys, sodass ein Name wie images/admin/sso-config.png leicht zu erraten ist. Bewahren Sie alles, was nicht jede angemeldete Leserschaft sehen soll, außerhalb des Dokumentations-Repositorys auf.
• Seitenleiste, Tabs, Breadcrumbs sowie vorherige/nächste Links werden pro Besucher gefiltert. Eine Seite, die von den Gruppen des Besuchers nicht abgedeckt ist, wird ausgelassen. Ebenso wird eine Gruppe oder ein Tab ausgelassen, der dadurch leer wird, sodass der Name eines eingeschränkten Abschnitts Personen außerhalb der Gruppe nicht angezeigt wird. Diese Filterung erfolgt zur Anfragezeit und ist von den oben genannten Ausschlüssen beim Build getrennt, die für alle gelten.
• Halten Sie Gruppennamen kurz. Gruppen werden im Sitzungscookie übertragen: bis zu 32 Gruppen pro Sitzung, jeweils mit 64 Zeichen. Wird eines der beiden Limits überschritten, wird die Liste nicht gekürzt. Jamdesk lehnt das gesamte Token mit einer 401 ab und gewährt keine Sitzung.

API-Playground vorausfüllen

Wenn Ihre Dokumentation ein 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, sofern vorhanden.
• query und path füllen alle übereinstimmenden Parameternamen am aktuellen Endpoint voraus.
• Die Bereiche server und cookie werden nicht unterstützt. Nur header, query und path werden angewendet.
• Beim Vorausfüllen wird ein Wert, den der Besucher bereits in den Playground eingegeben hat, niemals überschrieben.

Payload-Referenz

Signaturschlüssel rotieren

Rotate signing key auf der Dashboard-Karte erstellt ein neues Schlüsselpaar und zeigt den neuen privaten Schlüssel einmal an, genauso wie bei der ersten Erstellung. Es gibt keine Überschneidungsphase. Nach etwa 15 Sekunden wird der alte Schlüssel nicht mehr akzeptiert und jede bestehende Sitzung endet. Bis Ihr Backend mit dem neuen Schlüssel signiert, wird jede Anmeldung abgelehnt und Besucher wechseln zwischen Ihrer Login-Seite und der Dokumentation hin und her.

Daher ist die Reihenfolge wichtig:

1. Halten Sie einen Deploy bereit, der den Signaturschlüssel aus Ihrem Secret-Manager statt aus einem fest codierten Wert liest.
2. Klicken Sie auf Rotate signing key und kopieren Sie den neuen privaten Schlüssel.
3. Aktualisieren Sie das Secret und führen Sie den Deploy aus. Anmeldungen funktionieren wieder, sobald Ihr Backend den neuen Schlüssel verwendet.

Rotieren Sie nach Möglichkeit zu einer ruhigen Zeit und informieren Sie die für den Backend-Deploy zuständige Person, bevor Sie klicken.

Wenn Sie lediglich die Sitzungen aller Benutzer beenden möchten, beispielsweise nachdem ein Laptop verloren gegangen ist, verwenden Sie stattdessen Revoke sessions. Der Schlüssel bleibt erhalten, sodass sich in Ihrem Backend nichts ändert. Jeder Besucher muss sich lediglich erneut anmelden.

Clear signing key entfernt den öffentlichen Schlüssel aus Jamdesk. auth.jwt bleibt in docs.json aktiviert, sodass die Website weiterhin geschützt ist, aber kein Token überprüft werden kann, bis Sie einen neuen Schlüssel generieren. Löschen Sie ihn nur, wenn Sie die Website auf einen anderen Zugriffsmodus umstellen oder außer Betrieb nehmen.

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 zur 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 kein Body und keine Header erforderlich sind.

Das Abmelden aus der Dokumentation meldet den Besucher nicht aus Ihrem Produkt ab. Wenn Ihr Login-Ablauf für jeden, der bereits eine App-Sitzung besitzt, ein Token signiert, wird ein Besucher, der auf Log out klickt und anschließend einen Dokumentationslink öffnet, direkt wieder angemeldet. Das ist normalerweise erwünscht. Wenn Sie eine tatsächliche Abmeldung benötigen, lassen Sie Ihren loginUrl-Handler eine explizite Anmeldung prüfen, statt automatisch ein Token zu erstellen, oder verweisen Sie beim Abmelden Ihrer App ebenfalls auf die Abmelde-URL der Dokumentation.

Verhalten von Funktionen mit Authentifizierung

Fehlerbehebung

Sicherheitshinweis

apiPlaygroundInputs, einschließlich aller darin enthaltenen Authorization-Werte, kann von JavaScript gelesen werden, das auf Ihrer Dokumentationsseite über den Sitzungsinformations-Endpoint für das Vorausfüllen des Playgrounds ausgeführt wird. Das Vorausfüllen ist praktisch, aber kein geeigneter Ort für Geheimnisse mit weitreichenden Berechtigungen.

Senden Sie benutzerspezifische Anmeldedaten mit den geringstmöglichen Berechtigungen, die auf das beschränkt sind, was der Besucher tun darf, niemals einen organisationsweiten Administratorschlüssel. Behandeln Sie alles, was Sie in apiPlaygroundInputs einfügen, als für die Person sichtbar, die die Dokumentation durchsucht, denn genau das ist es.

Migration vom Passwortschutz

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?