Passwortschutz

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.

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.

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

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "Acme Docs",
  "theme": "jam",
  "auth": {
    "password": {
      "enabled": true,
      "hint": "Ask #docs-access on Slack"
    }
  }
}

git add docs.json
git commit -m "Turn on password protection"
git push

# 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_<slug> cookie.
curl -i -X POST https://acme.jamdesk.app/jd/unlock \
  -d "password=your-passphrase&from=/"

Ö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:

---
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:

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

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

---
title: Incident Runbook
description: What to do when the deploys dashboard is on fire.
private: true
---

{
  "auth": {
    "password": {
      "hint": "Ask the on-call engineer",
      "private": ["/admin/runbook", "/internal/api-keys"]
    }
  }
}

git add content/runbook.mdx docs.json
git commit -m "Gate the incident runbook"
git push

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.

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_<slug> (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 <slug>.jamdesk.app (oder Ihrer benutzerdefinierten Domain) in einem Browserfenster auf, das noch kein Cookie enthält.

Fehlerbehebung

Wie geht es weiter?