---
title: Passwortschutz
description: Schütze deine Dokumentationswebsite oder einzelne Seiten mit einem gemeinsamen Passwort. Besucher sehen einen Entsperrbildschirm, übrige Inhalte bleiben offen.
---
> **For AI agents:** the complete documentation index is at [llms.txt](https://jamdesk.com/docs/llms.txt). Append `.md` to any page URL for its markdown version.
Manchmal sollen Dokumentationen zwar in Git und online verfügbar, aber nicht für alle sichtbar sein. Typische Beispiele sind Runbooks, Anleitungen vor der Veröffentlichung, Dokumentationen nur für Partner und Funktionen mit Early Access. Mit dem Passwortschutz legst du ein gemeinsames Passwort fest, das entweder den Zugriff auf die gesamte Website oder auf bestimmte Seiten beschränkt, ohne dass du etwas aus deinem bestehenden Repository verschieben musst.
Die Screenshots zeigen die Benutzeroberfläche auf Englisch.
Du benötigst eine Authentifizierung pro Benutzer? Mit der [JWT-Authentifizierung](https://jamdesk.com/docs/de/setup/jwt-authentication) schützt du deine Dokumentation mit deinem eigenen Anmeldesystem statt mit einem gemeinsamen Passwort – inklusive Sitzungen pro Benutzer und gruppenbasiertem Seitenzugriff.
Bevor du den Passwortschutz aktivieren kannst, benötigst du ein Jamdesk-Projekt, das mit einem [Git-Repository verbunden ist](https://jamdesk.com/docs/de/setup/connecting-github). Die Konfiguration befindet sich in `docs.json`. Der Passwortschutz ist daher Teil deines üblichen Build- und Deploy-Workflows.
## Welchen Modus soll ich wählen?
Jamdesk bietet zwei Modi für den Passwortschutz. Wähle den passenden Modus danach aus, was öffentlich sein soll und was nicht.
| | **Modus für die gesamte Website** | **Modus für bestimmte Seiten** |
|---|---|---|
| **Verwenden, wenn** | Alles privat ist: interne Entwicklungsdokumentation, eine Staging-Kopie deiner öffentlichen Website oder ein noch nicht veröffentlichtes Produkt. | Die meisten Dokumente öffentlich sind und du nur einige Seiten verbergen möchtest, etwa ein Runbook, eine Beta-Funktion oder eine interne API-Referenz. |
| **Aktivierung** | Setze `auth.password.enabled: true` in `docs.json`. | Markiere Seiten mit `private: true` im Frontmatter oder liste Pfade unter `auth.password.private[]` auf. |
| **Öffentliche Ausnahmen** | Ja: Markiere einzelne Seiten, Navigationsgruppen oder Glob-Muster als öffentlich. | Nicht zutreffend. Alle Seiten sind öffentlich, sofern du sie nicht als privat markierst. |
Beide Modi verwenden dieselbe Dashboard-Karte, denselben Entsperrbildschirm sowie dieselben Funktionen zum Ändern und Widerrufen des Passworts. Du kannst jederzeit zwischen den Modi wechseln, indem du `docs.json` bearbeitest und die Änderungen pushst.
## Gesamte Website schützen
### 1. auth.password.enabled zu docs.json hinzufügen
Öffne deine `docs.json` und aktiviere den Schutz für die gesamte Website. Das Feld `hint` ist optional, wird aber dringend empfohlen, da es der einzige Hinweis auf dem Bildschirm ist, den Leser dazu erhalten, wie sie das Passwort bekommen.
```json docs.json
{
"$schema": "https://jamdesk.com/docs.json",
"name": "Acme Docs",
"theme": "jam",
"auth": {
"password": {
"enabled": true,
"hint": "Ask #docs-access on Slack"
}
}
}
```
Hinweise sind einfacher Text mit maximal 200 Zeichen und dürfen kein HTML enthalten.
Trage das Passwort nicht in `docs.json` ein. Du legst es nach dem Build im Dashboard fest. Dein Repository enthält nur die Aktivierungsoption und einen optionalen Hinweis.
### 2. Commit erstellen und pushen
Pushe die Änderung in deinen konfigurierten Branch. Jamdesk führt einen Build aus und aktiviert dabei den Passwortschutz im Modus für die gesamte Website.
```bash
git add docs.json
git commit -m "Turn on password protection"
git push
```
Nach Abschluss des Builds wechselt die Dashboard-Karte von **Off** zu **Password not set**, und die Website ist gesperrt. Jede Seite gibt `401` zurück und zeigt den Passwortbildschirm an. Bis du ein Passwort festlegst, funktioniert keines. Als öffentlich markierte Seiten bleiben zugänglich, und Projekt-API-Schlüssel funktionieren weiterhin für die Search API und MCP. Um die gesamte Website wieder öffentlich zu machen, setze `auth.password.enabled` auf `false` und pushe die Änderung.
### 3. Passwort im Dashboard festlegen
Öffne im Dashboard **Project Settings** und scrolle zur Karte **Password Protection**. Gib ein sicheres Passwort mit mindestens 8 Zeichen ein und klicke auf **Set password**.
Die Karte wechselt zum Status **On**. Alle Personen mit dem Passwort können nun die Website aufrufen; allen anderen wird der Entsperrbildschirm angezeigt.
Jamdesk speichert dein Passwort niemals im Klartext. Es wird mit scrypt in der Dashboard-Datenbank gehasht und weder in deinem Repository noch in `docs.json` abgelegt. Deshalb kann Jamdesk dir das Passwort auch nicht per E-Mail zusenden, wenn du es vergisst. Ändere es stattdessen.
### 4. Zugriffsschutz überprüfen
Öffne deine Dokumentationswebsite in einem privaten Browserfenster (oder rufe sie mit `curl` ab) und prüfe, ob der Entsperrbildschirm angezeigt wird. Gib ein falsches Passwort ein, um den Fehlerstatus zu überprüfen, und anschließend das richtige, um dich anzumelden.
```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=/"
```
Bei erfolgreicher Entsperrung wird eine Weiterleitung mit Status `303` und einem Header `Set-Cookie: jd_auth_acme=...; HttpOnly; Secure; SameSite=Lax; Max-Age=2592000` zurückgegeben. Speichere das Cookie für die nächste Anfrage – dann bist du angemeldet.
### Öffentliche Ausnahmen
Im Modus für die gesamte Website gibt es eine Ausnahme: Du kannst bestimmte Seiten öffentlich zugänglich lassen, während der Rest der Website geschützt ist. So kannst du neben privaten Dokumenten beispielsweise eine Marketing-Landingpage oder ein Anmeldeformular veröffentlichen.
Es gibt drei Möglichkeiten, eine Seite als öffentlich zu markieren. Sie fließen bei jedem Build in dieselbe Zulassungsliste ein.
**Frontmatter** bietet die genaueste Steuerung. Füge einer beliebigen `.mdx`-Datei `public: true` hinzu, damit nur diese Seite vom Schutz ausgenommen ist:
```yaml
---
title: Get started
public: true
---
```
**Navigationsgruppen** umfassen einen ganzen Abschnitt. Setze `public: true` für eine `group` oder `tab` in der Navigation von `docs.json`, damit alle darunterliegenden Seiten öffentlich sind. Das eignet sich beispielsweise für einen Tab „Marketing“ neben privaten Entwicklungsdokumenten:
```json docs.json
{
"navigation": {
"tabs": [
{
"tab": "Marketing",
"public": true,
"groups": [
{
"group": "Overview",
"pages": ["landing", "pricing", "changelog"]
}
]
},
{
"tab": "Internal",
"groups": [
{ "group": "Runbooks", "pages": ["deploys", "oncall"] }
]
}
]
}
}
```
**Explizite Glob-Muster** unter `auth.password.public[]` decken Fälle ab, die sich nicht mit Frontmatter oder der Navigation lösen lassen: Landingpages auf oberster Ebene, dynamisch generierte Routen oder ganze Teilbäume, die du nicht umstrukturieren möchtest.
```json docs.json
{
"auth": {
"password": {
"enabled": true,
"hint": "Ask #docs-access on Slack",
"public": [
"/landing",
"/pricing",
"/marketing/**",
"/blog/*"
]
}
}
}
```
Glob-Muster unterstützen `*` (ein Pfadsegment) und `**` (beliebige Tiefe). Ein einzelnes `/` wird bei der Validierung abgelehnt: Würde Jamdesk es akzeptieren, könnte ein Tippfehler unbemerkt die gesamte Website freigeben. Nach jedem Build zeigt die Dashboard-Karte die aufgelöste Zulassungsliste an, damit du prüfen kannst, welche Einträge der Build tatsächlich übernommen hat.
## Nur einige Seiten schützen
Der Modus für bestimmte Seiten funktioniert umgekehrt: Standardmäßig sind alle Seiten öffentlich. Du entscheidest, welche einzelnen Seiten geschützt werden.
### 1. Seite als privat markieren
Füge `private: true` zum Frontmatter der Seite hinzu. Das ist die einfachste Möglichkeit, wenn die Entscheidung bei der für die Seite verantwortlichen Person liegt.
```yaml
---
title: Incident Runbook
description: What to do when the deploys dashboard is on fire.
private: true
---
```
Wenn du die Liste der geschützten Pfade lieber in einer Datei verwalten möchtest, trage sie unter `auth.password.private[]` in `docs.json` ein. Beide Methoden ergänzen sich, sodass du sie kombinieren kannst.
```json docs.json
{
"auth": {
"password": {
"hint": "Ask the on-call engineer",
"private": ["/admin/runbook", "/internal/api-keys"]
}
}
}
```
Beachte, dass hier kein `enabled: true` steht. Wenn du `auth.password.private[]` ohne `enabled` festlegst, wird der Modus für bestimmte Seiten automatisch aktiviert.
### 2. Commit erstellen und pushen
Pushe deine Änderungen. Beim nächsten Build erkennt Jamdesk die privaten Seiten, aktiviert den Schutz im Modus für bestimmte Seiten und fordert dich im Dashboard zum Festlegen eines Passworts auf – genau wie im Modus für die gesamte Website.
```bash
git add content/runbook.mdx docs.json
git commit -m "Gate the incident runbook"
git push
```
### 3. Passwort festlegen
Öffne **Project Settings**, suche die Karte **Password Protection** und lege ein Passwort fest. Der Kartenkopf zeigt nun **On** und **Specific pages** statt **Whole site** an. Außerdem wird die Liste der privaten Seiten angezeigt, die der Build ermittelt hat, damit du sie schnell überprüfen kannst.
### 4. Zugriffsschutz überprüfen
Rufe deine Dokumentationswebsite wie gewohnt auf. Öffentliche Seiten sollten wie zuvor geladen werden; private Seiten sollten dich zum Entsperrbildschirm weiterleiten. Sobald du das Passwort eingegeben hast, bist du auf diesem Gerät 30 Tage lang angemeldet und kannst alle privaten Seiten ohne erneute Eingabe lesen.
## Was Besucher sehen
Wer eine geschützte Seite aufruft, sieht eine zentrierte Entsperrkarte. Sie zeigt nur den Namen der Website und einen optionalen Hinweis, ohne Seitenleiste oder Navigation.
Die Karte verwendet das Logo und die Primärfarbe deiner Website aus `docs.json`. Das Passwortfeld bietet eine Einblendeoption und erhält automatisch den Fokus.
Bei falschen Passwörtern wird dieselbe Karte mit einer Fehlermeldung, einem leeren Eingabefeld und einer kurzen Verzögerung zwischen Versuchen angezeigt. Sowohl ein falsches Passwort als auch eine Anfrage ohne Passwort führen zum selben Bildschirm. Daher lässt sich nicht erkennen, ob das Passwort falsch war oder noch gar keines eingegeben wurde.
Sobald ein Besucher das richtige Passwort eingibt, erhält er ein signiertes Cookie und kann die Website normal nutzen, bis die Sitzung abläuft oder du sie widerrufst.
## Sitzungen ändern und widerrufen
Ein gemeinsames Passwort muss irgendwann geändert werden, zum Beispiel wenn es weitergegeben wurde oder jemand das Team verlässt.
Öffne die Karte **Password Protection**, gib im Feld **Rotate password** ein neues Passwort ein und klicke auf **Save new password**. Alle Personen mit dem alten Passwort werden bei ihrer nächsten Anfrage ausgesperrt; mit dem neuen Passwort erhalten sie Zugriff. Die Änderung wird sofort wirksam und erfordert keinen erneuten Build.
Wenn du alle aktiven Sitzungen beenden möchtest, ohne das Passwort zu ändern – etwa weil jemand seinen Laptop verloren hat –, klicke stattdessen auf **Revoke all sessions**. Dadurch wird ein serverseitiger Versionszähler erhöht, wodurch alle zuvor ausgestellten Cookies ungültig werden. Besucher müssen das aktuelle Passwort erneut eingeben, um wieder Zugriff zu erhalten.
## Schutz deaktivieren
Der Schutz wird über `docs.json` gesteuert. Um ihn zu deaktivieren, bearbeitest du die Datei und pushst die Änderung.
- **Gesamte Website:** Entferne `auth.password.enabled` oder setze es auf `false`.
- **Bestimmte Seiten:** Entferne alle Markierungen `private: true` und leere `auth.password.private`.
Beim nächsten Build löscht Jamdesk den gespeicherten Passwort-Hash und setzt die Karte wieder auf **Off**. Es bleibt kein „inaktiver“ Status zurück. Wenn du den Schutz später erneut aktivierst, musst du ein neues Passwort festlegen.
Dein Quell-Repository ist nicht durch ein Passwort geschützt. Der Passwortschutz sichert die gehostete Dokumentationswebsite unter `*.jamdesk.app` oder deiner benutzerdefinierten Domain. Wenn dein GitHub-Repository öffentlich ist, bleiben die MDX-Inhalte dort weiterhin lesbar. Mache das Repository privat, wenn du sämtliche Inhalte schützen musst.
## Regeln für die Priorität
Eine Seite kann gleichzeitig von mehreren Einstellungen betroffen sein. Die Reihenfolge der Auswertung, von der spezifischsten bis zur allgemeinsten:
- Wenn `auth.password.enabled` den Wert `true` hat, ist die gesamte Website geschützt. `private: true` auf einzelnen Seiten ist dann überflüssig.
- Wenn eine Seite sowohl mit `public: true` als auch mit `private: true` markiert ist, hat **öffentlich Vorrang**. Die sicherere Standardeinstellung ist diejenige, bei der nicht versehentlich eine Seite offengelegt wird.
- Frontmatter mit `public: true`, `public: true` für eine Navigationsgruppe und Glob-Muster in `auth.password.public[]` werden zu einer Zulassungsliste zusammengeführt. Es gilt nicht die Regel „die spezifischste Einstellung gewinnt“. Sobald ein Eintrag eine Seite als öffentlich kennzeichnet, ist sie öffentlich.
- Wenn `auth.password.private[]` festgelegt ist, `auth.password.enabled` aber nicht, aktiviert Jamdesk automatisch den Modus für bestimmte Seiten. Weitere Schritte sind nicht erforderlich.
## Funktionsweise von Sitzungen und Ratenbegrenzung
In diesem Abschnitt geht es um das Sitzungscookie, Ratenbegrenzungen und die Passwortspeicherung.
**Das Sitzungscookie.** Bei erfolgreicher Entsperrung setzt Jamdesk ein Cookie namens `jd_auth_` (zum Beispiel `jd_auth_acme`). Es ist `HttpOnly` und `Secure`, verwendet `SameSite=Lax`, ist auf den Host beschränkt und mit HMAC-SHA256 signiert. Die Nutzdaten enthalten den Projekt-Slug, den aktuellen Versionszähler und einen Ablaufzeitpunkt. Manipulationen führen daher dazu, dass die Validierung fehlschlägt. Die Standardlaufzeit beträgt **30 Tage** und wird bei jeder erfolgreichen Entsperrung erneuert.
**Ratenbegrenzung.** Der Entsperr-Endpoint verwendet zwei stündliche Zähler: **10 Versuche pro IP-Adresse** und **100 Versuche pro Projekt**. Beide werden vor der Überprüfung des scrypt-Hashs angewendet, damit ein Brute-Force-Versuch weder CPU-Ressourcen verbrauchen noch zeitbezogene Informationen preisgeben kann. Wird eines der Limits erreicht, gibt der Endpoint `429 Too Many Requests` mit einem `Retry-After`-Header zurück.
**Speicherung.** Dein Passwort wird mit scrypt gehasht und in Firestore des Dashboards gespeichert. Es wird weder in deinem Repository noch in `docs.json` oder einem Build-Artefakt abgelegt. Wenn du es verlierst, ändere es. Eine Wiederherstellung ist nicht möglich.
## Testen während der lokalen Entwicklung
`jamdesk dev` führt deine Dokumentation mit den aktuellen R2-Inhalten und der aktuellen Konfiguration aus. Auf dem lokalen Entwicklungsserver wird der Passwortschutz **nicht durchgesetzt**, sodass du geschützte Seiten ohne Passwort ansehen kannst. Das ist beabsichtigt: Du bist der Autor und hast bereits Zugriff auf das Repository. Die lokale Vorschau durch eine Passwortabfrage zu blockieren, würde nur stören, ohne die Sicherheit zu erhöhen.
Um den tatsächlichen Zugriffsschutz zu überprüfen, rufe die bereitgestellte Website unter `.jamdesk.app` oder deiner benutzerdefinierten Domain in einem Browserfenster auf, in dem das Cookie noch nicht gesetzt ist.
## Fehlerbehebung
### Mein Build ist abgeschlossen, aber der Entsperrbildschirm wird nicht angezeigt
Wahrscheinlich zeigt die Dashboard-Karte **Password not set** an. Der Schutz wird erst aktiviert, wenn du sowohl (1) die Konfiguration in `docs.json` gepusht als auch (2) ein Passwort in **Project Settings** festgelegt hast. Bis der zweite Schritt abgeschlossen ist, gibt jede Anfrage `401` zurück und enthält den Entsperrbildschirm. Wenn du eine bestimmte Zielseite erwartet hast, kann es so wirken, als würde der Bildschirm „nicht angezeigt“.
### Ich habe das Passwort festgelegt, aber mein Teamkollege sieht weiterhin den Entsperrbildschirm
Im Browser befindet sich noch ein altes `jd_auth_`-Cookie von vor der Passwortänderung. Warte entweder, bis das Cookie nach 30 Tagen abläuft, klicke im Dashboard auf **Revoke all sessions** oder bitte die Person, die Cookies für die Dokumentationsdomain zu löschen. Beim nächsten Besuch wird sie zur Eingabe des aktuellen Passworts aufgefordert.
### Kann ich verschiedenen Gruppen unterschiedliche Passwörter geben?
Nicht direkt. Jamdesk verwendet pro Website ein gemeinsames Passwort. Wenn du den Zugriff nach Gruppen aufteilen musst, teile deine Dokumentation auf mehrere Projekte mit jeweils eigenem Passwort auf oder verwende den Modus für bestimmte Seiten mit getrennten öffentlichen und privaten Bereichen für jede Zielgruppe.
### Funktioniert der Passwortschutz mit benutzerdefinierten Domains und Subpfad-Proxys?
Ja, beides ist möglich. Das Entsperr-Cookie ist an den Host gebunden. Daher wird jeder Host – die `*.jamdesk.app`-Subdomain und deine benutzerdefinierte Domain – unabhängig authentifiziert. Wer einen Host entsperrt, ist auf dem anderen nicht automatisch angemeldet.
Subpfad-Konfigurationen, bei denen die Dokumentation unter `yoursite.com/docs` hinter einem eigenen Proxy liegt, funktionieren direkt: Das Entsperrformular wird unter dem Pfadpräfix `/_jd/` gesendet, den jede dokumentierte Proxy-Konfiguration bereits weiterleitet. Wenn du den Passwortschutz aktivierst oder deaktivierst, sind keine Proxy-Änderungen erforderlich.
Wenn du deinen Proxy konfiguriert hast, bevor die Weiterleitung von `/_jd/` in die Einrichtungsanleitung aufgenommen wurde, ergänze `/_jd/*` in den weitergeleiteten Pfaden.
### Wird eine geschützte Website weiterhin in Suchmaschinen angezeigt?
Nein. Geschützte Websites setzen auf dem Entsperrbildschirm `noindex, nofollow` und geben für jede geschützte Seite `401` zurück. Suchmaschinen-Crawler können daher keine Inhalte hinter dem Schutz indexieren. Öffentliche Seiten innerhalb einer geschützten Website können weiterhin wie gewohnt indexiert werden.
## Wie geht es weiter?
Vergleiche den Passwortschutz mit SSO und dem Muster mit mehreren Projekten.
Ersetze das gemeinsame Passwort durch Sitzungen pro Benutzer über dein eigenes Anmeldesystem.
Ersetze gemeinsame Passwörter durch die Anmeldung einzelner Benutzer über deinen Identitätsanbieter.
Stelle deine Dokumentation unter deiner eigenen Domain bereit, bevor du den Link teilst.
Vollständige Referenz der Felder `enabled`, `hint`, `public` und `private`.