---
title: Passwortschutz
description: Schützen Sie Ihre gesamte Dokumentationsseite oder einzelne Seiten mit einem gemeinsamen Passwort. Besucher sehen einen Entsperrbildschirm.
---
> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.
Manchmal soll eine Dokumentation zwar in Git und online bleiben, aber nicht für alle sichtbar sein. Typische Beispiele sind Runbooks, Anleitungen vor der Veröffentlichung, Dokumentation nur für Partner und Funktionen mit frühem Zugriff. Der Passwortschutz stellt eine gemeinsame Passphrase bereit, mit der Sie entweder Ihre gesamte Website oder bestimmte Seiten schützen können, ohne Inhalte aus Ihrem bestehenden Repository zu verschieben.
Die Screenshots zeigen die Benutzeroberfläche auf Englisch.
Benötigen Sie eine Authentifizierung pro Benutzer? [JWT authentication](/de/setup/jwt-authentication) schützt Ihre Dokumentation mit Ihrem eigenen Anmeldesystem anstelle einer gemeinsamen Passphrase und bietet Sitzungen pro Benutzer sowie gruppenbasierten Seitenzugriff.
Sie benötigen ein Jamdesk-Projekt, das [mit einem Git-Repository verbunden](/de/setup/connecting-github) ist, bevor Sie den Passwortschutz aktivieren können. Die Konfiguration befindet sich in `docs.json`, sodass der Passwortschutz in Ihren normalen Build-and-Deploy-Ablauf integriert ist.
## Welchen Modus sollte ich wählen?
Jamdesk bietet zwei Modi für den Passwortschutz. Wählen Sie anhand dessen, was öffentlich und was nicht öffentlich sein soll.
| | **Gesamte Website** | **Bestimmte Seiten** |
|---|---|---|
| **Verwenden, wenn** | Alles privat ist: interne Engineering-Dokumentation, eine Staging-Kopie Ihrer öffentlichen Website oder ein noch nicht veröffentlichtes Produkt. | Der Großteil der Dokumentation öffentlich ist und Sie nur einige Seiten ausblenden müssen (ein Runbook, eine Beta-Funktion oder eine interne API-Referenz). |
| **Aktivierung** | Setzen Sie `auth.password.enabled: true` in `docs.json`. | Kennzeichnen Sie Seiten im Frontmatter mit `private: true` oder listen Sie Pfade unter `auth.password.private[]` auf. |
| **Öffentliche Ausnahmen** | Ja: Kennzeichnen Sie einzelne Seiten, Navigationsgruppen oder Glob-Muster als öffentlich. | Nicht zutreffend. Jede Seite ist öffentlich, sofern Sie sie nicht als privat kennzeichnen. |
Beide Modi verwenden dieselbe Dashboard-Karte, denselben Entsperrbildschirm sowie dieselben Steuerelemente zum Ändern und Widerrufen. Sie können jederzeit zwischen ihnen wechseln, indem Sie `docs.json` bearbeiten und die Änderungen pushen.
## Gesamte Website schützen
Öffnen Sie `docs.json` und aktivieren Sie den Schutz der gesamten Website. Das Feld `hint` ist optional, wird aber dringend empfohlen, da es der einzige Hinweis auf dem Bildschirm ist, den Ihre Leser erhalten, um das Passwort zu erfahren.
```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.
Tragen Sie das Passwort selbst nicht in `docs.json` ein. Sie legen das Passwort nach dem Build im Dashboard fest. Ihr Repository enthält nur das Aktivierungs-Flag und einen optionalen Hinweis.
Pushen Sie die Änderung in Ihren konfigurierten Branch. Jamdesk führt einen Build aus und aktiviert währenddessen 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 gibt für jede Seite `401` zurück. Bis Sie ein Passwort festlegen, wird jede Anfrage abgewiesen.
Öffnen Sie **Project Settings** im Dashboard und scrollen Sie zur Karte **Password Protection**. Geben Sie eine starke Passphrase ein (mindestens 8 Zeichen) und klicken Sie anschließend auf **Set password**.
Die Karte wechselt in den Status **On**. Alle Personen mit dem Passwort können die Website nun durchsuchen; alle anderen sehen den Entsperrbildschirm.
Jamdesk speichert Ihr Passwort niemals im Klartext. Es wird mit scrypt in der Dashboard-Datenbank gehasht und niemals in Ihr Repository oder in `docs.json` geschrieben. Das bedeutet auch, dass Jamdesk Ihnen das Passwort nicht per E-Mail senden kann, wenn Sie es vergessen. Ändern Sie es stattdessen.
Öffnen Sie Ihre Dokumentationsseite in einem privaten Browserfenster (oder verwenden Sie `curl`) und prüfen Sie, ob der Entsperrbildschirm angezeigt wird. Testen Sie zunächst ein falsches Passwort, um den Fehlerstatus zu prüfen, und anschließend das richtige Passwort, um die Website zu öffnen.
```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=/"
```
Eine erfolgreiche Entsperrung gibt eine `303`-Weiterleitung mit einem `Set-Cookie: jd_auth_acme=...; HttpOnly; Secure; SameSite=Lax; Max-Age=2592000`-Header zurück. Speichern Sie dieses Cookie für die nächste Anfrage, dann haben Sie Zugriff.
### Öffentliche Ausnahmen
Der Modus für die gesamte Website bietet eine Möglichkeit, bestimmte Seiten öffentlich zu halten, während der Rest der Website geschützt ist. So können Sie beispielsweise eine Marketing-Landingpage oder ein Anmeldeformular neben privaten Dokumentationsseiten veröffentlichen.
Sie können eine Seite auf drei Arten als öffentlich kennzeichnen. Alle drei werden bei jedem Build zu derselben Zulassungsliste zusammengeführt.
**Frontmatter** ist die granularste Option. Fügen Sie einer beliebigen `.mdx`-Datei `public: true` hinzu. Nur diese Seite umgeht dann den Schutz:
```yaml
---
title: Get started
public: true
---
```
**Navigationsgruppen** decken jeweils einen gesamten Abschnitt ab. Setzen Sie `public: true` für eine `group` oder einen `tab` in der Navigation von `docs.json`. Dann ist jede darin enthaltene Seite öffentlich. Das ist praktisch für einen Tab „Marketing“ neben privaten Engineering-Dokumentationsseiten:
```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 Globs** unter `auth.password.public[]` decken alles ab, was sich nicht über Frontmatter und Navigation steuern lässt: Landingpages der obersten Ebene, dynamisch generierte Routen oder einen gesamten Teilbaum, den Sie nicht umstrukturieren möchten.
```json docs.json
{
"auth": {
"password": {
"enabled": true,
"hint": "Ask #docs-access on Slack",
"public": [
"/landing",
"/pricing",
"/marketing/**",
"/blog/*"
]
}
}
}
```
Globs unterstützen `*` (ein Pfadsegment) und `**` (beliebige Tiefe). Ein alleinstehendes `/` wird bei der Validierung abgewiesen: Würde Jamdesk es akzeptieren, könnte ein einzelner Tippfehler unbemerkt die gesamte Website entsperren. Nach jedem Build zeigt die Dashboard-Karte die aufgelöste Zulassungsliste an, damit Sie prüfen können, was der Build tatsächlich übernommen hat.
## Nur einige Seiten schützen
Der Modus für bestimmte Seiten funktioniert umgekehrt: Standardmäßig ist alles öffentlich, und Sie fügen einzelne Seiten zum Schutz hinzu.
Fügen Sie dem Frontmatter der Seite `private: true` hinzu. Das ist die einfachste Option, 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 Sie die Liste der geschützten Pfade lieber in einer Datei verwalten möchten, fügen Sie sie unter `auth.password.private[]` in `docs.json` hinzu. Beide Ansätze sind additiv und können kombiniert werden.
```json docs.json
{
"auth": {
"password": {
"hint": "Ask the on-call engineer",
"private": ["/admin/runbook", "/internal/api-keys"]
}
}
}
```
Beachten Sie, dass `enabled: true` nicht erforderlich ist. Das Setzen von `auth.password.private[]` ohne `enabled` aktiviert den Modus für bestimmte Seiten automatisch.
Pushen Sie Ihre Änderungen. Der nächste Build erkennt die privaten Seiten, aktiviert den Schutz im Modus für bestimmte Seiten und zeigt im Dashboard die Aufforderung zum Festlegen eines Passworts an – 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
```
Öffnen Sie **Project Settings**, suchen Sie die Karte **Password Protection** und legen Sie eine Passphrase fest. Der Kartenkopf zeigt nun **On** mit **Specific pages** anstelle von **Whole site**. Außerdem wird die Liste der privaten Seiten angezeigt, die der Build aufgelöst hat, sodass Sie sie auf einen Blick prüfen können.
Durchsuchen Sie Ihre Dokumentationsseite wie gewohnt. Öffentliche Seiten sollten wie bisher geladen werden; private Seiten sollten Sie zum Entsperrbildschirm weiterleiten. Sobald Sie das Passwort eingeben, sind Sie auf diesem Gerät 30 Tage lang angemeldet und können jede private Seite lesen, ohne das Passwort erneut eingeben zu müssen.
## Was Besucher sehen
Wenn jemand eine geschützte Seite aufruft, wird eine zentrierte Entsperrkarte angezeigt. Sie enthält nur den Namen der Website und einen optionalen Hinweis, ohne Seitenleiste oder Navigation.
Die Karte verwendet das Logo und die Primärfarbe Ihrer Website aus `docs.json`. Das Passwortfeld verfügt über eine Option zum Anzeigen des Passworts und erhält automatisch den Fokus.
Falsche Passwörter zeigen dieselbe Karte mit einer Fehlermeldung, einem neuen Eingabefeld und einer kurzen Verzögerung zwischen den Versuchen. Ein falsches Passwort und eine Anfrage ohne Passwort führen zum selben Bildschirm. Daher lässt sich auf der Seite nicht erkennen, ob das Passwort falsch war oder noch kein Passwort eingegeben wurde.
Sobald ein Besucher das richtige Passwort eingibt, erhält er ein signiertes Cookie und kann die Website normal durchsuchen, bis die Sitzung abläuft oder Sie sie widerrufen.
## Sitzungen ändern und widerrufen
Ein gemeinsames Passwort muss irgendwann geändert werden, beispielsweise nachdem es weitergegeben wurde oder jemand das Team verlässt.
Öffnen Sie die Karte **Password Protection**, geben Sie eine neue Passphrase in das Feld **Rotate password** ein und klicken Sie auf **Save new password**. Alle Personen mit dem alten Passwort werden bei ihrer nächsten Anfrage ausgesperrt; alle Personen mit dem neuen Passwort erhalten Zugriff. Die Änderung wird sofort wirksam und erfordert keinen neuen Build.
Wenn Sie lediglich alle aktiven Sitzungen abmelden möchten, ohne die Passphrase zu ändern (beispielsweise weil der Laptop einer Person verloren gegangen ist), klicken Sie stattdessen auf **Revoke all sessions**. Dadurch wird ein versionsbasierter Zähler auf dem Server erhöht, der alle vor dieser Erhöhung ausgestellten Cookies ungültig macht. Besucher geben das aktuelle Passwort erneut ein und erhalten wieder Zugriff.
## Schutz deaktivieren
Der Schutz wird durch `docs.json` gesteuert. Zum Deaktivieren müssen Sie daher die Datei bearbeiten und die Änderung pushen.
- **Gesamte Website:** Entfernen Sie `auth.password.enabled` (oder setzen Sie es auf `false`).
- **Bestimmte Seiten:** Entfernen Sie jedes `private: true`-Kennzeichen und leeren Sie `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 bestehen. Wenn Sie den Schutz später erneut aktivieren, müssen Sie ein neues Passwort auswählen.
Ihr Quell-Repository ist nicht durch ein Passwort geschützt. Der Passwortschutz schützt die gehostete Dokumentationsseite unter `*.jamdesk.app` (oder Ihrer benutzerdefinierten Domain). Wenn Ihr GitHub-Repository öffentlich ist, bleibt der MDX-Inhalt dort lesbar. Machen Sie das Repository privat, wenn Sie den vollständigen Inhalt schützen müssen.
## Regeln zur Priorität
Eine einzelne Seite kann gleichzeitig von mehreren Signalen betroffen sein. Die Auflösungsreihenfolge von der spezifischsten bis zur allgemeinsten Regel lautet:
- Wenn `auth.password.enabled` auf `true` gesetzt ist, wird die gesamte Website geschützt. `private: true` auf einzelnen Seiten ist dann redundant.
- Wenn eine Seite sowohl mit `public: true` als auch mit `private: true` gekennzeichnet ist, **hat public Vorrang**. Die sicherere Standardeinstellung ist diejenige, die eine Seite nicht versehentlich offenlegt.
- Frontmatter `public: true`, `public: true` für Navigationsgruppen und Globs unter `auth.password.public[]` werden zu einer gemeinsamen Zulassungsliste zusammengeführt. Es gilt nicht die Regel „die spezifischste Einstellung gewinnt“. Sobald ein Signal eine Seite als öffentlich kennzeichnet, ist sie öffentlich.
- Wenn `auth.password.private[]` gesetzt ist, `auth.password.enabled` jedoch nicht, aktiviert Jamdesk den Modus für bestimmte Seiten automatisch. Sie müssen nichts weiter tun.
## Funktionsweise von Sitzungen und Ratenbegrenzung
Dieser Abschnitt behandelt das Sitzungs-Cookie, Ratenbegrenzungen und die Passwortspeicherung.
**Das Sitzungs-Cookie.** Nach einer erfolgreichen Entsperrung setzt Jamdesk ein Cookie namens `jd_auth_` (beispielsweise `jd_auth_acme`). Es ist `HttpOnly`, `Secure`, `SameSite=Lax`, auf den Host beschränkt und mit HMAC-SHA256 signiert. Die Nutzlast enthält den Projektslug, den aktuellen Versionszähler und einen Ablaufzeitpunkt, sodass Manipulationen bei der Validierung fehlschlagen. Die Standardgültigkeit beträgt **30 Tage** und wird bei jeder erfolgreichen Entsperrung verlängert.
**Ratenbegrenzung.** Der Entsperrungs-Endpoint verwendet zwei Zähler pro Stunde: **10 Versuche pro IP-Adresse** und **100 Versuche pro Projekt**. Beide werden vor der Prüfung des scrypt-Hashs durchgesetzt, damit ein Brute-Force-Versuch keine Rechenleistung verbrauchen oder Informationen über das Timing preisgeben kann. Das Erreichen eines der beiden Limits gibt `429 Too Many Requests` mit einem `Retry-After`-Header zurück.
**Speicherung.** Ihr Passwort wird mit scrypt gehasht und in der Firestore-Datenbank des Dashboards gespeichert. Es gelangt niemals in Ihr Repository, in Ihre `docs.json` oder in ein Build-Artefakt. Wenn Sie es verlieren, ändern Sie es. Es gibt keinen Wiederherstellungsweg.
## Lokale Entwicklung testen
`jamdesk dev` führt Ihre Dokumentation mit den Live-Inhalten aus R2 und der Live-Konfiguration aus. Der Passwortschutz wird **nicht** auf dem lokalen Entwicklungsserver durchgesetzt, sodass Sie geschützte Seiten anzeigen können, ohne das Passwort zu kennen. Dies ist beabsichtigt: Sie sind der Autor, haben bereits Zugriff auf das Repository, und eine lokale Vorschau durch eine Passwortabfrage zu blockieren, würde Aufwand ohne Sicherheitsgewinn verursachen.
Wenn Sie den tatsächlichen Schutz überprüfen möchten, rufen Sie die bereitgestellte Website unter `.jamdesk.app` (oder Ihrer benutzerdefinierten Domain) in einem Browserfenster auf, das noch kein Cookie enthält.
## Fehlerbehebung
Die Dashboard-Karte zeigt wahrscheinlich **Password not set** an. Der Schutz wird erst aktiviert, wenn Sie sowohl (1) die Konfiguration in `docs.json` gepusht als auch (2) im **Project Settings** ein Passwort festgelegt haben. Bis der zweite Schritt abgeschlossen ist, gibt jede Anfrage `401` zurück, wobei der Entsperrbildschirm den Antwortinhalt bildet. Wenn Sie ein bestimmtes Ziel erwartet haben, kann es daher so wirken, als würde der Bildschirm „nicht angezeigt“.
Sein Browser enthält ein altes `jd_auth_`-Cookie aus der Zeit vor Ihrer Änderung. Warten Sie entweder 30 Tage, bis das Cookie abläuft, klicken Sie im Dashboard auf **Revoke all sessions** oder lassen Sie die Cookies für die Dokumentationsdomain löschen. Beim nächsten Besuch wird die aktuelle Passphrase abgefragt.
Nicht direkt. Jamdesk verwendet ein gemeinsames Passwort pro Website. Wenn Sie Zugriff nach Gruppen benötigen, teilen Sie Ihre Dokumentation in mehrere Projekte auf (jeweils mit eigenem Passwort) oder verwenden Sie den Modus für bestimmte Seiten mit separaten öffentlichen und privaten Bereichen pro Zielgruppe.
Ja, beides wird unterstützt. Das Entsperr-Cookie ist an den Host gebunden, sodass jeder Host (die `*.jamdesk.app`-Subdomain und Ihre benutzerdefinierte Domain) unabhängig authentifiziert wird. Leser, die einen Host entsperren, sind beim anderen nicht vorab authentifiziert.
Setups mit einem Subpfad (Dokumentation unter `yoursite.com/docs` hinter Ihrem eigenen Proxy) funktionieren sofort: Das Entsperrformular sendet seine Anfrage unter dem Pfadpräfix `/_jd/`, das von jeder dokumentierten Proxy-Konfiguration bereits weitergeleitet wird. Beim Aktivieren oder Deaktivieren des Passwortschutzes sind keine Proxy-Änderungen erforderlich.
Wenn Ihr Proxy konfiguriert wurde, bevor die Weiterleitung von `/_jd/` Teil des Einrichtungsleitfadens war, fügen Sie `/_jd/*` zu den weitergeleiteten Pfaden hinzu.
Nein. Geschützte Websites setzen auf dem Entsperrbildschirm `noindex, nofollow` und geben für jede geschützte Seite `401` zurück. Suchcrawler können daher nichts hinter dem Schutz indexieren. Öffentliche Seiten innerhalb einer geschützten Website bleiben normal indexierbar.
## Wie geht es weiter?
Vergleichen Sie den Passwortschutz mit SSO und dem Muster mit mehreren Projekten.
Ersetzen Sie die gemeinsame Passphrase durch Sitzungen pro Benutzer aus Ihrem eigenen Anmeldesystem.
Ersetzen Sie gemeinsame Passphrasen durch die Anmeldung pro Benutzer über Ihren Identitätsanbieter.
Legen Sie Ihre Dokumentation auf Ihrer eigenen Domain ab, bevor Sie den Link teilen.
Vollständige Feldreferenz für `enabled`, `hint`, `public` und `private`.