Controllo degli accessi
Scegli come i lettori accedono alla documentazione: completamente pubblica, protetta da password, mista pubblica/privata, con il tuo login tramite JWT o SSO. Scegli quella più adatta al tuo pubblico.
Jamdesk ti offre cinque modi per controllare chi può leggere la tua documentazione.
Scegli l'approccio giusto
| Approccio | Quando usarlo | Configurazione |
|---|---|---|
| Completamente pubblica | Documentazione di prodotto rivolta all'esterno, progetti open source, tutto ciò che vuoi indicizzare e condividere. | Predefinita. Nessuna configurazione necessaria. |
| Password per l'intero sito | Tutto è interno: runbook di ingegneria, documentazione riservata ai partner, un prodotto non ancora rilasciato. Una sola passphrase condivisa protegge l'intero sito. | auth.password.enabled: true in docs.json + impostazione della password nella dashboard. Vedi Protezione con password. |
| Mista (alcune pagine private) | La maggior parte della documentazione è pubblica. Alcune pagine sono interne (un runbook, una funzionalità beta, un riferimento API interno). | Aggiungi private: true al frontmatter delle pagine interne, oppure elencale in auth.password.private[]. Vedi Protezione con password. |
| Il tuo login (JWT) | I lettori accedono già al tuo prodotto. Il tuo backend firma un token di breve durata per ogni lettore e Jamdesk lo trasforma in una sessione. Le pagine possono essere limitate ai gruppi che indichi nel token. | auth.jwt.enabled: true più un loginUrl in docs.json e una chiave di firma dalla dashboard. Incluso in ogni piano. Vedi Autenticazione JWT. |
| SSO (Enterprise) | I lettori devono accedere con il tuo identity provider esistente: nessuna password condivisa, un registro delle attività e la revoca dell'accesso rimuovendo l'utente. | Piano Enterprise. Vedi SSO. |
Puoi cambiare approccio in qualsiasi momento modificando docs.json e facendo un push. Passare da intero sito a misto (o viceversa) richiede una sola build.
Modelli comuni
Documentazione interna ed esterna in un unico progetto
Non ti servono due progetti per avere documentazione interna dietro un login e un sito pubblico per i clienti. Usa la modalità mista in un unico progetto Jamdesk:
---
title: Incident Runbook
private: true
---Le pagine con private: true sono protette. Tutto il resto resta pubblico. Mantieni un solo repository, una sola build e una sola dashboard. La schermata di sblocco compare solo su una pagina protetta.
Per sezioni interne più ampie, elenca i percorsi in docs.json invece di contrassegnare ogni file. auth.password.private[] attiva automaticamente la modalità pagine specifiche. Non aggiungere enabled: true insieme: attiverebbe la modalità intero sito, l'opposto di ciò che vuoi qui.
{
"auth": {
"password": {
"hint": "Ask the on-call engineer",
"private": ["/internal/**", "/admin/runbook"]
}
}
}Due progetti separati
Usa due progetti solo quando i pubblici richiedono branding completamente diversi, domini personalizzati separati, analisi separate o piani tariffari differenti. Esempi: un sito di documentazione pubblico su docs.acme.com e un wiki interno separato su internal.acme.com. Il costo di manutenzione è più alto: due build, due dashboard, due domini.
Accesso per utente tramite il tuo login
Una password condivisa è un passo indietro quando i tuoi clienti hanno già un account presso di te. Può essere inoltrata, non scade da sola e non riesce a distinguere un cliente dall'altro. L'autenticazione JWT invia un lettore già autenticato che apre la tua documentazione a un URL sul tuo lato. Il tuo backend firma un token e Jamdesk crea una sessione per quel lettore. I lettori non hanno bisogno di un account Jamdesk. Non c'è alcun segreto condiviso da inoltrare.
Il token può anche contenere gruppi. Aggiungi groups: ["admin"] al frontmatter di una pagina. Solo i visitatori il cui token elenca admin possono aprirla o vederla nella navigazione. Tutti gli altri ricevono un 404. La pagina non rivela che esiste.
---
title: Enterprise audit log API
groups: ["enterprise"]
---Abbinala a percorsi public per le parti del sito che devono restare aperte, come un changelog o una pagina di stato.
SSO per il sito di documentazione
I lettori dei piani Enterprise accedono con il tuo identity provider (Okta, Google Workspace, Azure AD, ecc.) invece di digitare una password condivisa. Usalo quando ti serve un registro di chi ha letto cosa, o quando la disattivazione di un utente deve revocare immediatamente l'accesso alla documentazione. Vedi SSO per una panoramica e per sapere come contattare le vendite.
Editor e lettori
Jamdesk prevede tre ruoli di accesso distinti:
| Ruolo | Cosa fanno | Come viene concesso l'accesso |
|---|---|---|
| Editor | Scrivono e aggiornano i contenuti MDX. | La documentazione si modifica eseguendo il commit di MDX nel repository GitHub collegato. I permessi del tuo repository GitHub decidono chi può fare commit. Un push genera una build solo se chi lo esegue è membro del progetto Jamdesk (abbinato tramite l'account GitHub collegato o l'email) o un account di automazione che hai autorizzato. Un push da chiunque altro compare come build fallita. Il proprietario del progetto riceve un'email. Vedi GitHub. |
| Lettori | Visualizzano il sito di documentazione pubblicato. | Tutti (pubblico), chiunque abbia la password (modalità password), chiunque il tuo flusso di login firmi un token (JWT), o chiunque sia autenticato tramite il tuo IdP (SSO). |
| Membri del team in dashboard | Gestiscono build, analisi e impostazioni del progetto nella dashboard Jamdesk. | Invitati tramite Impostazioni progetto → Membri nella dashboard. L'appartenenza è anche ciò che permette ai push di una persona di generare build. Vedi Membri del team. |
Un membro del team può ricoprire una qualsiasi combinazione di questi ruoli. Una regola li collega: i push di un editor generano una build solo se l'editor è anche membro del team.