---
title: Protezione con password
description: Proteggi l'intero sito di documentazione o solo alcune pagine con una password condivisa, mostrando ai visitatori una schermata di sblocco.
---
> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.
A volte vuoi che la documentazione rimanga in Git e online, ma non sia visibile a tutti. Tra gli esempi più comuni ci sono runbook, guide pre-release, documentazione riservata ai partner e funzionalità in accesso anticipato. La protezione con password ti offre un'unica passphrase condivisa per proteggere l'intero sito o un insieme specifico di pagine, senza spostare nulla dal repository esistente.
Gli screenshot mostrano l'interfaccia in inglese.
Ti serve l'autenticazione per singolo utente? [L'autenticazione JWT](/it/setup/jwt-authentication) protegge la documentazione tramite il tuo sistema di accesso anziché una passphrase condivisa, con sessioni per utente e accesso alle pagine basato sui gruppi.
Prima di poter attivare la protezione con password, ti servirà un progetto Jamdesk [connesso a un repository Git](/it/setup/connecting-github). La configurazione risiede in `docs.json`, quindi la protezione con password si integra nel normale flusso di build e deploy.
## Quale modalità scegliere?
Jamdesk dispone di due modalità per la protezione con password. Scegline una in base a ciò che è pubblico e ciò che non lo è.
| | **Modalità intero sito** | **Modalità pagine specifiche** |
|---|---|---|
| **Quando usarla** | Tutto è privato: documentazione tecnica interna, una copia di staging del sito pubblico, un prodotto non ancora rilasciato. | La maggior parte della documentazione è pubblica. Devi solo nascondere alcune pagine (un runbook, una funzionalità beta, un riferimento API interno). |
| **Come attivarla** | Imposta `auth.password.enabled: true` in `docs.json`. | Contrassegna le pagine come private con `private: true` nel frontmatter oppure elenca i percorsi in `auth.password.private[]`. |
| **Eccezioni pubbliche** | Sì: contrassegna come pubbliche singole pagine, gruppi di navigazione o pattern glob. | N/D. Ogni pagina è pubblica, a meno che non venga contrassegnata come privata. |
Entrambe le modalità condividono la stessa scheda nel dashboard, la stessa schermata di sblocco e gli stessi controlli per la rotazione e la revoca. Puoi passare dall'una all'altra in qualsiasi momento modificando `docs.json` ed eseguendo il push.
## Proteggere l'intero sito
Apri `docs.json` e dichiara la protezione dell'intero sito. Il campo `hint` è facoltativo ma fortemente consigliato, perché è l'unico indizio visualizzato sullo schermo che i lettori ricevono su come ottenere la password.
```json docs.json
{
"$schema": "https://jamdesk.com/docs.json",
"name": "Acme Docs",
"theme": "jam",
"auth": {
"password": {
"enabled": true,
"hint": "Ask #docs-access on Slack"
}
}
}
```
Gli hint sono testo semplice, con un massimo di 200 caratteri e senza HTML.
Non inserire la password stessa in `docs.json`. Imposti la password nel dashboard dopo la build. Il repository contiene solo il flag di attivazione e un hint facoltativo.
Esegui il push della modifica sul branch configurato. Jamdesk esegue una build e, durante la build, attiva la protezione con password in modalità intero sito.
```bash
git add docs.json
git commit -m "Turn on password protection"
git push
```
Al termine della build, la scheda del dashboard passa da **Off** a **Password not set** e il sito restituisce `401` per ogni pagina. Finché non imposti una password, ogni richiesta viene rifiutata.
Apri **Project Settings** nel dashboard e scorri fino alla scheda **Password Protection**. Digita una passphrase sicura (minimo 8 caratteri), quindi fai clic su **Set password**.
La scheda passa allo stato **On**. Chiunque disponga della password può ora consultare il sito; tutti gli altri visualizzano la schermata di sblocco.
Jamdesk non memorizza mai la password in testo normale. La password viene sottoposta a hashing con scrypt nel database del dashboard e non viene mai scritta nel repository o in `docs.json`. Questo significa anche che Jamdesk non può inviartela via email se la dimentichi. Esegui invece la rotazione.
Apri il sito della documentazione in una finestra del browser privato (oppure usa `curl`) e verifica di ricevere la schermata di sblocco. Prova una password errata per controllare lo stato di errore, quindi quella corretta per accedere.
```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=/"
```
Uno sblocco riuscito restituisce un reindirizzamento `303` con un'intestazione `Set-Cookie: jd_auth_acme=...; HttpOnly; Secure; SameSite=Lax; Max-Age=2592000`. Salva quel cookie per la richiesta successiva e avrai effettuato l'accesso.
### Eccezioni pubbliche
La modalità intero sito offre una via di fuga: puoi mantenere pubbliche pagine specifiche anche mentre il resto del sito è protetto. In questo modo puoi pubblicare una landing page di marketing o un modulo di registrazione insieme alla documentazione privata.
Hai tre modi per contrassegnare una pagina come pubblica e tutti confluiscono nella stessa lista di autorizzazioni a ogni build.
**Il frontmatter** è l'opzione più granulare. Aggiungi `public: true` a qualsiasi file `.mdx` e solo quella pagina non sarà soggetta alla protezione:
```yaml
---
title: Get started
public: true
---
```
**I gruppi di navigazione** coprono un'intera sezione in una volta sola. Imposta `public: true` su un `group` o una `tab` nella navigazione di `docs.json` e ogni pagina al loro interno sarà pubblica. È utile per una tab "Marketing" accanto alla documentazione tecnica privata:
```json docs.json
{
"navigation": {
"tabs": [
{
"tab": "Marketing",
"public": true,
"groups": [
{
"group": "Overview",
"pages": ["landing", "pricing", "changelog"]
}
]
},
{
"tab": "Internal",
"groups": [
{ "group": "Runbooks", "pages": ["deploys", "oncall"] }
]
}
]
}
}
```
**I glob espliciti** in `auth.password.public[]` gestiscono tutto ciò che il frontmatter e la navigazione non possono gestire: landing page di primo livello, route generate dinamicamente o un intero sottoalbero che preferisci non riscrivere.
```json docs.json
{
"auth": {
"password": {
"enabled": true,
"hint": "Ask #docs-access on Slack",
"public": [
"/landing",
"/pricing",
"/marketing/**",
"/blog/*"
]
}
}
}
```
I glob supportano `*` (un segmento del percorso) e `**` (qualsiasi profondità). Un `/` isolato viene rifiutato durante la validazione: se Jamdesk lo accettasse, un singolo errore di battitura potrebbe sbloccare silenziosamente l'intero sito. Dopo ogni build, la scheda del dashboard mostra la lista di autorizzazioni risultante, così puoi verificare quali percorsi la build ha effettivamente incluso.
## Proteggere solo alcune pagine
La modalità pagine specifiche segue il flusso opposto: tutto è pubblico per impostazione predefinita e scegli quali singole pagine sottoporre alla protezione.
Aggiungi `private: true` al frontmatter della pagina. È l'opzione più semplice quando la decisione spetta al responsabile della pagina.
```yaml
---
title: Incident Runbook
description: What to do when the deploys dashboard is on fire.
private: true
---
```
In alternativa, se preferisci mantenere l'elenco dei percorsi protetti in un unico file, aggiungili in `auth.password.private[]` in `docs.json`. Entrambi gli approcci sono cumulativi, quindi puoi combinarli.
```json docs.json
{
"auth": {
"password": {
"hint": "Ask the on-call engineer",
"private": ["/admin/runbook", "/internal/api-keys"]
}
}
}
```
Nota che non è presente `enabled: true`. Impostare `auth.password.private[]` senza `enabled` attiva automaticamente la modalità pagine specifiche.
Esegui il push delle modifiche. La build successiva rileva le pagine private, attiva la protezione in modalità pagine specifiche e mostra nel dashboard la richiesta di impostare una password, esattamente come nella modalità intero sito.
```bash
git add content/runbook.mdx docs.json
git commit -m "Gate the incident runbook"
git push
```
Apri **Project Settings**, trova la scheda **Password Protection** e imposta una passphrase. L'intestazione della scheda ora mostra **On** con **Specific pages** anziché **Whole site** e visualizza l'elenco delle pagine private rilevate dalla build, così puoi verificarlo a colpo d'occhio.
Consulta normalmente il sito della documentazione. Le pagine pubbliche dovrebbero caricarsi come prima; le pagine private dovrebbero reindirizzarti alla schermata di sblocco. Dopo aver inserito la password, l'accesso sul dispositivo rimane attivo per 30 giorni e puoi leggere qualsiasi pagina privata senza reinserirla.
## Cosa vedono i visitatori
Quando qualcuno raggiunge una pagina protetta, visualizza una scheda di sblocco centrata. La scheda mostra solo il nome del sito e un hint facoltativo, senza barra laterale né navigazione.
La scheda utilizza il logo e il colore principale del sito definiti in `docs.json`. Il campo della password dispone di un controllo per mostrarla e dell'autofocus.
Le password errate mostrano la stessa scheda con un messaggio di errore, un campo vuoto e un breve ritardo tra i tentativi. Una password errata e una richiesta senza password portano entrambe alla stessa schermata, quindi nulla nella pagina distingue una "password errata" da una "password non ancora inserita".
Dopo aver inserito la password corretta, il visitatore riceve un cookie firmato e può navigare normalmente fino alla scadenza della sessione o alla sua revoca.
## Ruotare e revocare le sessioni
Prima o poi una password condivisa deve essere modificata, ad esempio dopo essere stata condivisa con troppe persone o quando qualcuno lascia il team.
Apri la scheda **Password Protection**, digita una nuova passphrase nel campo **Rotate password** e fai clic su **Save new password**. Chiunque disponga della vecchia password verrà escluso alla richiesta successiva; chiunque disponga di quella nuova potrà accedere. La rotazione ha effetto immediato e non richiede una nuova build.
Se vuoi solo disconnettere forzatamente tutte le sessioni attive senza modificare la passphrase (ad esempio, se è scomparso il laptop di qualcuno), fai clic su **Revoke all sessions**. Questa operazione incrementa un contatore di versione lato server e invalida ogni cookie emesso prima dell'incremento. I visitatori reinseriscono la password corrente e possono accedere nuovamente.
## Disattivare la protezione
La protezione è gestita da `docs.json`, quindi per disattivarla devi modificare il file ed eseguire il push.
- **Intero sito:** rimuovi `auth.password.enabled` (oppure impostalo su `false`).
- **Pagine specifiche:** rimuovi ogni indicatore `private: true` e svuota `auth.password.private`.
Alla build successiva, Jamdesk elimina l'hash della password memorizzato e riporta la scheda allo stato **Off**. Non rimane alcuno stato "inattivo". Se riattivi la protezione in seguito, dovrai scegliere una nuova password.
Il repository sorgente non è protetto da password. La protezione con password protegge il sito di documentazione ospitato su `*.jamdesk.app` (o sul tuo dominio personalizzato). Se il repository GitHub è pubblico, il contenuto MDX rimane leggibile. Rendi privato il repository se ti serve una protezione completa dei contenuti.
## Regole di precedenza
Una singola pagina può essere interessata contemporaneamente da più segnali. L'ordine di risoluzione, dal più al meno specifico, è il seguente:
- Se `auth.password.enabled` è `true`, l'intero sito è protetto. `private: true` sulle singole pagine diventa ridondante.
- Se una pagina è contrassegnata sia come `public: true` sia come `private: true`, **public wins**. L'impostazione predefinita più sicura è quella che non rischia di esporre accidentalmente una pagina.
- `public: true` nel frontmatter, `public: true` in un gruppo di navigazione e i glob `auth.password.public[]` confluiscono tutti in un'unica lista di autorizzazioni. Non esiste una regola "vince il più specifico". Se un segnale indica che una pagina è pubblica, la pagina è pubblica.
- Se `auth.password.private[]` è impostato ma `auth.password.enabled` non lo è, Jamdesk attiva automaticamente la modalità pagine specifiche. Non devi fare altro.
## Come funzionano le sessioni e la limitazione della frequenza
Questa sezione descrive il cookie di sessione, i limiti di frequenza e la memorizzazione della password.
**Il cookie di sessione.** Dopo uno sblocco riuscito, Jamdesk imposta un cookie denominato `jd_auth_` (ad esempio, `jd_auth_acme`). Il cookie è `HttpOnly`, `Secure`, `SameSite=Lax`, limitato all'host e firmato con HMAC-SHA256. Il payload include lo slug del progetto, il contatore di versione corrente e un timestamp di scadenza, quindi qualsiasi manomissione non supera la validazione. La durata predefinita è di **30 giorni** e viene rinnovata a ogni sblocco riuscito.
**Limitazione della frequenza.** L'endpoint di sblocco applica due contatori orari: **10 tentativi per IP** e **100 tentativi per progetto**. Entrambi vengono applicati prima del controllo dell'hash scrypt, così un tentativo di forza bruta non può consumare CPU né rivelare informazioni sui tempi di risposta. Il superamento di uno dei due limiti restituisce `429 Too Many Requests` con un'intestazione `Retry-After`.
**Memorizzazione.** La password viene sottoposta a hashing con scrypt e memorizzata nel Firestore del dashboard. Non finisce mai nel repository, in `docs.json` o in un artefatto di build. Se la perdi, esegui la rotazione. Non esiste un percorso di recupero.
## Test durante lo sviluppo locale
`jamdesk dev` esegue la documentazione utilizzando il contenuto R2 e la configurazione attivi. La protezione con password **non viene applicata** dal server di sviluppo locale, quindi puoi visualizzare in anteprima le pagine protette senza conoscere la password. È una scelta intenzionale: sei l'autore, disponi già delle chiavi del repository e bloccare l'anteprima locale con una schermata di password creerebbe attrito senza alcun vantaggio in termini di sicurezza.
Se vuoi verificare la protezione effettiva, raggiungi il sito distribuito all'indirizzo `.jamdesk.app` (o al tuo dominio personalizzato) da una finestra del browser che non contiene ancora il cookie.
## Risoluzione dei problemi
Probabilmente la scheda del dashboard mostra **Password not set**. La protezione non si attiva finché non hai completato entrambe le operazioni: (1) eseguire il push della configurazione in `docs.json` e (2) impostare una password in **Project Settings**. Fino al completamento del secondo passaggio, ogni richiesta restituisce `401` con la schermata di sblocco nel corpo della risposta, cosa che può far sembrare che la schermata "non appaia" se ti aspettavi una destinazione specifica.
Il suo browser contiene un vecchio cookie `jd_auth_` risalente a prima della rotazione. Attendi 30 giorni perché il cookie scada, fai clic su **Revoke all sessions** nel dashboard oppure chiedigli di cancellare i cookie per il dominio della documentazione. Alla visita successiva gli verrà richiesta la password corrente.
Non direttamente. Jamdesk usa un'unica password condivisa per sito. Se ti serve l'accesso per gruppi, suddividi la documentazione in più progetti, ciascuno con la propria password, oppure usa la modalità pagine specifiche con confini pubblico/privato distinti per ogni gruppo di destinatari.
Sì, in entrambi i casi. Il cookie di sblocco è associato all'host, quindi ogni host (il sottodominio `*.jamdesk.app` e il tuo dominio personalizzato) esegue l'autenticazione in modo indipendente. I lettori che sbloccano un host non risultano preautenticati sull'altro.
Le configurazioni con sottopercorso (documentazione disponibile su `yoursite.com/docs` dietro il tuo proxy) funzionano immediatamente: il modulo di sblocco invia la richiesta usando il prefisso del percorso `/_jd/`, che ogni configurazione proxy documentata inoltra già. Quando attivi o disattivi la protezione con password non sono necessarie modifiche al proxy.
Se il proxy è stato configurato prima che l'inoltro di `/_jd/` fosse incluso nella guida alla configurazione, aggiungi `/_jd/*` ai percorsi inoltrati.
No. I siti protetti impostano `noindex, nofollow` sulla schermata di sblocco e restituiscono `401` per ogni pagina protetta, quindi i crawler dei motori di ricerca non possono indicizzare nulla dietro la protezione. Le pagine pubbliche all'interno di un sito protetto rimangono normalmente indicizzabili.
## Qual è il prossimo passo?
Confronta la protezione con password con SSO e il modello multi-progetto.
Sostituisci la passphrase condivisa con sessioni per utente provenienti dal tuo sistema di accesso.
Sostituisci le passphrase condivise con l'accesso per utente tramite il tuo provider di identità.
Pubblica la documentazione sul tuo dominio prima di condividere il link.
Riferimento completo dei campi `enabled`, `hint`, `public` e `private`.