---
title: Protezione con password
description: Proteggi l'intero sito di documentazione o alcune pagine con una password condivisa; i visitatori vedono una schermata di sblocco.
---
> **For AI agents:** the complete documentation index is at [llms.txt](https://jamdesk.com/docs/llms.txt). Append `.md` to any page URL for its markdown version.
A volte vuoi che la documentazione resti nel repository Git e online, ma non sia visibile a tutti. Tra gli esempi più comuni ci sono i runbook, le guide pre-release, la documentazione riservata ai partner e le funzionalità in accesso anticipato. La protezione con password ti permette di usare 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 utente? [L'autenticazione JWT](https://jamdesk.com/docs/it/setup/jwt-authentication) protegge la documentazione con il tuo sistema di accesso, anziché con una passphrase condivisa, e offre sessioni per utente e accesso alle pagine in base ai gruppi.
Prima di attivare la protezione con password, devi avere un progetto Jamdesk [collegato a un repository Git](https://jamdesk.com/docs/it/setup/connecting-github). La configurazione si trova in `docs.json`, quindi la protezione con password si integra nel normale flusso di build e deploy.
## Quale modalità scegliere?
Jamdesk offre due modalità di protezione con password. Scegli quella più adatta in base a ciò che vuoi rendere pubblico.
| | **Modalità intero sito** | **Modalità pagine specifiche** |
|---|---|---|
| **Da usare quando** | Tutto è privato: documentazione interna di engineering, una copia di staging del sito pubblico o un prodotto non ancora rilasciato. | La maggior parte della documentazione è pubblica. Vuoi solo nascondere alcune pagine, come un runbook, una funzionalità beta o 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ì: puoi rendere pubbliche singole pagine, gruppi di navigazione o corrispondenze glob. | N/D. Ogni pagina è pubblica, a meno che non la contrassegni come privata. |
Entrambe le modalità usano la stessa scheda nella dashboard, la stessa schermata di sblocco e gli stessi controlli per cambiare la password e revocare le sessioni. Puoi passare da una modalità all'altra in qualsiasi momento modificando `docs.json` e inviando le modifiche.
## Proteggere l'intero sito
### 1. Aggiungi auth.password.enabled a docs.json
Apri `docs.json` e dichiara la protezione dell'intero sito. Il campo `hint` è facoltativo, ma fortemente consigliato: è l'unico indizio visibile che spiega ai lettori 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"
}
}
}
```
I suggerimenti sono testo semplice, con un massimo di 200 caratteri, senza HTML.
Non inserire la password in `docs.json`. La imposti nella dashboard dopo la build. Il repository contiene solo il flag di attivazione e un suggerimento facoltativo.
### 2. Esegui commit e push
Invia la modifica al branch configurato. Jamdesk avvia una build e, durante il processo, 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 nella dashboard passa da **Off** a **Password not set** e il sito viene bloccato. Ogni pagina restituisce `401` e mostra la schermata della password; nessuna password funziona finché non ne imposti una. Le pagine che hai contrassegnato come pubbliche restano accessibili e le chiavi API del progetto continuano a funzionare per Search API e MCP. Per rendere di nuovo pubblico l'intero sito, imposta `auth.password.enabled` su `false` e invia la modifica.
### 3. Imposta la password nella dashboard
Apri **Project Settings** nella dashboard e scorri fino alla scheda **Password Protection**. Inserisci una passphrase robusta (almeno 8 caratteri), quindi fai clic su **Set password**.
La scheda passa allo stato **On**. Chiunque conosca la password può navigare nel sito; gli altri vedono la schermata di sblocco.
Jamdesk non memorizza mai la password in testo semplice. La password viene sottoposta ad hashing con scrypt nel database della 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. In tal caso, cambiala.
### 4. Verifica la protezione
Apri il sito della documentazione in una finestra privata del browser (o con `curl`) e verifica che venga mostrata la schermata di sblocco. Prova una password errata per controllare il messaggio di errore, poi inserisci 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 header `Set-Cookie: jd_auth_acme=...; HttpOnly; Secure; SameSite=Lax; Max-Age=2592000`. Salva il cookie per la richiesta successiva e potrai accedere.
### Eccezioni pubbliche
La modalità intero sito offre una via d'uscita: puoi lasciare pubbliche alcune pagine specifiche anche se il resto del sito è protetto. In questo modo puoi pubblicare una pagina di marketing o un modulo di iscrizione accanto alla documentazione privata.
Puoi contrassegnare una pagina come pubblica in tre modi; tutti confluiscono nella stessa lista di autorizzazione a ogni build.
**Frontmatter** è l'opzione più granulare. Aggiungi `public: true` a qualsiasi file `.mdx` per escludere dalla protezione solo quella pagina:
```yaml
---
title: Get started
public: true
---
```
**Gruppi di navigazione** consentono di rendere pubblica un'intera sezione. Imposta `public: true` su un `group` o `tab` nella navigazione di `docs.json` e tutte le pagine al suo interno saranno pubbliche. È utile, ad esempio, per una scheda "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 i casi che frontmatter e navigazione non possono coprire: pagine di destinazione al livello principale, percorsi generati 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à). Il percorso `/` da solo non supera la convalida: se Jamdesk lo accettasse, un semplice errore di battitura potrebbe sbloccare silenziosamente l'intero sito. Dopo ogni build, la scheda nella dashboard mostra la lista di autorizzazione risultante, così puoi verificare cosa è stato effettivamente rilevato dalla build.
## Proteggere solo alcune pagine
La modalità pagine specifiche funziona al contrario: tutto è pubblico per impostazione predefinita e scegli quali singole pagine proteggere.
### 1. Contrassegna una pagina come privata
Aggiungi `private: true` al frontmatter della pagina. È l'opzione più semplice quando la decisione spetta a chi gestisce la pagina.
```yaml
---
title: Incident Runbook
description: What to do when the deploys dashboard is on fire.
private: true
---
```
In alternativa, se preferisci tenere l'elenco dei percorsi protetti in un unico file, aggiungili in `auth.password.private[]` in `docs.json`. I due metodi si sommano, 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.
### 2. Esegui commit e push
Invia le modifiche. La build successiva rileva le pagine private, attiva la protezione in modalità pagine specifiche e mostra nella dashboard la richiesta di impostare una password, proprio come nella modalità intero sito.
```bash
git add content/runbook.mdx docs.json
git commit -m "Gate the incident runbook"
git push
```
### 3. Imposta la password
Apri **Project Settings**, individua la scheda **Password Protection** e imposta una passphrase. L'intestazione della scheda ora mostra **On** e **Specific pages** invece di **Whole site**; inoltre, elenca le pagine private rilevate dalla build, così puoi verificarle rapidamente.
### 4. Verifica la protezione
Naviga normalmente nel sito della documentazione. Le pagine pubbliche dovrebbero caricarsi come prima; quelle private dovrebbero reindirizzarti alla schermata di sblocco. Dopo aver inserito la password, resterai autenticato su quel dispositivo per 30 giorni e potrai leggere qualsiasi pagina privata senza inserirla di nuovo.
## Cosa vedono i visitatori
Quando un visitatore apre una pagina protetta, vede una scheda di sblocco centrata. La scheda mostra solo il nome del sito e un suggerimento facoltativo, senza barra laterale né navigazione.
La scheda usa il logo e il colore principale del sito definiti in `docs.json`. Il campo password include un controllo per mostrare il testo e ha il focus automatico.
Le password errate fanno apparire la stessa scheda con un messaggio di errore, un nuovo campo di immissione e un breve ritardo tra i tentativi. Una password errata e una richiesta senza password portano entrambe alla stessa schermata, quindi nulla distingue "password errata" da "password non ancora inserita".
Quando un visitatore inserisce la password corretta, 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 potrebbe essere necessario cambiare una password condivisa, ad esempio se è stata condivisa con troppe persone o se qualcuno lascia il team.
Apri la scheda **Password Protection**, inserisci una nuova passphrase nel campo **Rotate password** e fai clic su **Save new password**. Chi usa la vecchia password non potrà più accedere alla richiesta successiva; chi usa quella nuova potrà farlo. La modifica ha effetto immediato e non richiede una nuova build.
Se vuoi solo forzare la disconnessione di tutte le sessioni attive senza cambiare la passphrase (ad esempio, se è stato smarrito il portatile di qualcuno), fai clic su **Revoke all sessions**. Il contatore di versione lato server viene incrementato e tutti i cookie emessi prima dell'incremento vengono invalidati. I visitatori dovranno inserire di nuovo la password corrente per accedere.
## Disattivare la protezione
La protezione è gestita da `docs.json`, quindi per disattivarla devi modificare il file e inviare la modifica.
- **Intero sito:** rimuovi `auth.password.enabled` (o impostalo su `false`).
- **Pagine specifiche:** rimuovi tutti i marker `private: true` e svuota `auth.password.private`.
Con la 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 limita l'accesso al sito di documentazione ospitato su `*.jamdesk.app` (o sul tuo dominio personalizzato). Se il repository GitHub è pubblico, i contenuti MDX restano leggibili. Rendi privato il repository se hai bisogno di proteggere tutti i contenuti.
## Regole di precedenza
Una pagina può essere interessata da più impostazioni contemporaneamente. Ecco l'ordine di risoluzione, dalla più specifica alla meno specifica:
- Se `auth.password.enabled` è `true`, l'intero sito è protetto. `private: true` sulle singole pagine diventa superfluo.
- Se una pagina è contrassegnata sia con `public: true` sia con `private: true`, **prevale public**. L'impostazione più sicura è quella che evita di esporre accidentalmente una pagina.
- `public: true` nel frontmatter, `public: true` in un gruppo di navigazione e i glob `auth.password.public[]` confluiscono in un'unica lista di autorizzazione. Non si applica la regola "prevale l'impostazione più specifica": se una qualsiasi impostazione dichiara pubblica una pagina, quella 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 alle richieste e la memorizzazione della password.
**Il cookie di sessione.** Dopo uno sblocco riuscito, Jamdesk imposta un cookie chiamato `jd_auth_` (ad esempio, `jd_auth_acme`). È `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; qualsiasi manomissione non supera la convalida. La durata predefinita è di **30 giorni** e si rinnova dopo ogni sblocco riuscito.
**Limitazione delle richieste.** L'endpoint di sblocco applica due contatori orari: **10 tentativi per IP** e **100 tentativi per progetto**. Entrambi vengono applicati prima della verifica dell'hash scrypt, così un attacco 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 header `Retry-After`.
**Memorizzazione.** La password viene sottoposta ad hashing con scrypt e memorizzata in Firestore della dashboard. Non finisce mai nel repository, in `docs.json` o in un artefatto di build. Se la perdi, cambiala: non esiste una procedura di recupero.
## Test durante lo sviluppo locale
`jamdesk dev` esegue la documentazione usando i contenuti R2 e la configurazione attivi. La protezione con password **non viene applicata** sul server di sviluppo locale, quindi puoi visualizzare in anteprima le pagine protette senza conoscere la password. È una scelta intenzionale: sei l'autore, hai già accesso al repository e bloccare l'anteprima locale con una richiesta di password sarebbe un ostacolo senza vantaggi per la sicurezza.
Per verificare la protezione effettiva, apri il sito distribuito su `.jamdesk.app` (o sul tuo dominio personalizzato) in una finestra del browser che non abbia ancora il cookie.
## Risoluzione dei problemi
### La build è terminata, ma la schermata di sblocco non appare
Probabilmente la scheda nella dashboard mostra **Password not set**. La protezione si attiva solo dopo che hai (1) inviato la configurazione in `docs.json` e (2) impostato una password in **Project Settings**. Fino al completamento del secondo passaggio, ogni richiesta restituisce `401` con la schermata di sblocco nel corpo della risposta; se ti aspettavi una destinazione specifica, potresti avere l'impressione che la schermata "non appaia".
### Ho impostato la password, ma il mio collega vede ancora la schermata di sblocco
Il browser del collega contiene un vecchio cookie `jd_auth_`, emesso prima che cambiassi la password. Puoi aspettare 30 giorni che scada, fare clic su **Revoke all sessions** nella dashboard oppure chiedergli di eliminare i cookie del dominio della documentazione. Alla visita successiva gli verrà chiesto di inserire la password corrente.
### Posso condividere password diverse con gruppi diversi?
Non direttamente. Jamdesk usa un'unica password condivisa per sito. Se hai bisogno di accessi distinti per gruppo, suddividi la documentazione in più progetti (ciascuno con la propria password) oppure usa la modalità pagine specifiche, definendo confini pubblici e privati separati per ogni pubblico.
### La protezione con password funziona con domini personalizzati e proxy con percorsi secondari?
Sì, in entrambi i casi. Il cookie di sblocco è associato all'host, quindi ogni host (il sottodominio `*.jamdesk.app` e il tuo dominio personalizzato) viene autenticato in modo indipendente. Chi sblocca un host non risulta già autenticato sull'altro.
Le configurazioni con percorso secondario (documentazione su `yoursite.com/docs` dietro un proxy personalizzato) funzionano subito: il modulo di sblocco invia i dati con il prefisso di percorso `/_jd/`, che tutte le configurazioni proxy documentate già inoltrano. Non servono modifiche al proxy quando attivi o disattivi la protezione con password.
Se hai configurato il proxy prima che l'inoltro di `/_jd/` fosse incluso nella guida di configurazione, aggiungi `/_jd/*` ai percorsi inoltrati.
### Un sito protetto compare comunque nei motori di ricerca?
No. I siti protetti impostano `noindex, nofollow` nella schermata di sblocco e restituiscono `401` per ogni pagina protetta, quindi i crawler dei motori di ricerca non possono indicizzare i contenuti dietro la protezione. Le pagine pubbliche di un sito protetto restano normalmente indicizzabili.
## Qual è il prossimo passo?
Confronta la protezione con password con SSO e con l'approccio multi-progetto.
Sostituisci la passphrase condivisa con sessioni per utente gestite 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 ai campi `enabled`, `hint`, `public` e `private`.