Zugriffskontrolle
Legen Sie fest, wer Ihre Dokumentation lesen darf: öffentlich, passwortgeschützt, teilweise privat, per JWT-Login oder SSO – passend zu Ihrer Zielgruppe.
Jamdesk bietet fünf Möglichkeiten, den Zugriff auf Ihre Dokumentation zu steuern.
Den richtigen Ansatz wählen
| Ansatz | Geeignet für | Einrichtung |
|---|---|---|
| Vollständig öffentlich | Produktdokumentation für externe Zielgruppen, Open-Source-Projekte und alle Inhalte, die indexiert und geteilt werden sollen. | Standard. Keine Konfiguration erforderlich. |
| Passwort für die gesamte Website | Alles ist intern: Engineering-Runbooks, Dokumentation nur für Partner oder ein noch nicht veröffentlichtes Produkt. Ein gemeinsames Passwort schützt die gesamte Website. | auth.password.enabled: true in docs.json + Passwort im Dashboard festlegen. Siehe Passwortschutz. |
| Gemischt (einige Seiten privat) | Der Großteil der Dokumentation ist öffentlich. Einige Seiten sind intern, etwa ein Runbook, eine Beta-Funktion oder eine interne API-Referenz. | Fügen Sie private: true zum Frontmatter interner Seiten hinzu oder listen Sie sie unter auth.password.private[] auf. Siehe Passwortschutz. |
| Eigener Login (JWT) | Leser melden sich bereits bei Ihrem Produkt an. Ihr Backend signiert für jeden Leser ein kurzlebiges Token. Jamdesk wandelt es in eine Sitzung um. Seiten lassen sich auf Gruppen beschränken, die Sie im Token angeben. | auth.jwt.enabled: true und eine loginUrl in docs.json sowie ein Signaturschlüssel aus dem Dashboard. In allen Tarifen enthalten. Siehe JWT-Authentifizierung. |
| SSO (Enterprise) | Leser sollen sich bei Ihrem vorhandenen Identitätsanbieter anmelden: ohne gemeinsame Passwörter, mit Audit-Trail und der Möglichkeit, den Zugriff durch Entfernen eines Nutzers zu entziehen. | Enterprise-Tarif. Siehe SSO. |
Wechseln Sie jederzeit den Ansatz, indem Sie docs.json bearbeiten und die Änderungen pushen. Der Wechsel vom Schutz der gesamten Website zum gemischten Modus (oder umgekehrt) erfordert nur einen Build.
Häufige Muster
Interne und externe Dokumentation in einem Projekt
Sie benötigen keine zwei Projekte für interne Dokumentation hinter einem Login und eine öffentliche Website für Kunden. Verwenden Sie den gemischten Modus in einem Jamdesk-Projekt:
---
title: Incident Runbook
private: true
---Seiten mit private: true sind geschützt. Alle anderen bleiben öffentlich. Sie behalten ein Repository, einen Build und ein Dashboard. Der Entsperrbildschirm erscheint nur auf geschützten Seiten.
Für größere interne Bereiche können Sie die Pfade stattdessen in docs.json auflisten, anstatt jede Datei einzeln zu markieren. auth.password.private[] aktiviert automatisch den Modus für bestimmte Seiten. Fügen Sie nicht zusätzlich enabled: true hinzu. Damit würden Sie den Modus für die gesamte Website aktivieren – genau das Gegenteil dessen, was Sie hier benötigen.
{
"auth": {
"password": {
"hint": "Ask the on-call engineer",
"private": ["/internal/**", "/admin/runbook"]
}
}
}Zwei separate Projekte
Verwenden Sie zwei Projekte nur, wenn die Zielgruppen ein vollständig unterschiedliches Branding, separate benutzerdefinierte Domains, separate Analysen oder unterschiedliche Tarifstufen benötigen. Beispiele: eine öffentliche Dokumentationswebsite unter docs.acme.com und ein separates internes Wiki unter internal.acme.com. Der Wartungsaufwand ist höher: zwei Builds, zwei Dashboards und zwei Domains.
Benutzerzugriff über den eigenen Login
Ein gemeinsames Passwort ist ein Rückschritt, wenn Ihre Kunden bereits Konten bei Ihnen haben. Es wird weitergeleitet, läuft nie von selbst ab und kann Kunden nicht voneinander unterscheiden. Die JWT-Authentifizierung leitet angemeldete Leser, die Ihre Dokumentation aufrufen, zu einer URL auf Ihrer Seite weiter. Ihr Backend signiert ein Token. Jamdesk erstellt eine Sitzung für den jeweiligen Leser. Leser benötigen kein Jamdesk-Konto. Es gibt kein gemeinsames Geheimnis, das weitergeleitet werden könnte.
Das Token kann auch Gruppen enthalten. Fügen Sie groups: ["admin"] zum Frontmatter einer Seite hinzu. Nur Besucher, deren Token admin enthält, können die Seite öffnen oder in der Navigation sehen. Alle anderen erhalten einen 404-Fehler. Die Seite verrät nicht, dass sie existiert.
---
title: Enterprise audit log API
groups: ["enterprise"]
---Kombinieren Sie dies mit öffentlichen Pfaden für Bereiche der Website, die offen bleiben sollen, etwa ein Änderungsprotokoll oder eine Statusseite.
SSO für die Dokumentationswebsite
Leser mit Enterprise-Tarifen melden sich bei Ihrem Identitätsanbieter (Okta, Google Workspace, Azure AD usw.) an, statt ein gemeinsames Passwort einzugeben. Verwenden Sie SSO, wenn Sie einen Audit-Trail darüber benötigen, wer was gelesen hat, oder wenn beim Ausscheiden eines Mitarbeiters der Zugriff auf die Dokumentation sofort entzogen werden muss. Unter SSO finden Sie eine Übersicht und Informationen zur Kontaktaufnahme mit dem Vertrieb.
Editoren und Leser
Jamdesk unterscheidet drei separate Zugriffsrollen:
| Rolle | Aufgaben | Zugriffserteilung |
|---|---|---|
| Bearbeiter | MDX-Inhalte schreiben und aktualisieren. | Die Dokumentation wird bearbeitet, indem MDX in Ihr verbundenes GitHub-Repository committet wird. Die Berechtigungen Ihres GitHub-Repositorys bestimmen, wer committet darf. Ein Push löst nur dann einen Build aus, wenn die Person, die ihn ausgeführt hat, Mitglied des Jamdesk-Projekts ist (zugeordnet über das verknüpfte GitHub-Konto oder die E-Mail-Adresse) oder ein von Ihnen autorisiertes Automatisierungskonto verwendet. Ein Push von allen anderen wird als fehlgeschlagener Build angezeigt. Der Projektinhaber erhält eine E-Mail. Siehe GitHub. |
| Leser | Die veröffentlichte Dokumentationswebsite ansehen. | Alle (öffentlich), alle Personen mit dem Passwort (Passwortmodus), alle Personen, für die Ihr Login-Ablauf ein Token signiert (JWT), oder alle Personen, die sich über Ihren IdP authentifizieren (SSO). |
| Dashboard-Teammitglieder | Builds, Analysen und Projekteinstellungen im Jamdesk-Dashboard verwalten. | Werden über Project Settings → Members im Dashboard eingeladen. Die Mitgliedschaft ermöglicht außerdem, dass die Pushes einer Person Builds auslösen. Siehe Teammitglieder. |
Ein Teammitglied kann beliebige Kombinationen dieser Rollen innehaben. Eine Regel verbindet sie: Die Pushes eines Bearbeiters lösen nur dann einen Build aus, wenn der Bearbeiter auch Teammitglied ist.