Protezione con password

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.

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 è.

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

{
  "$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=/"

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:

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

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

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

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

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.

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_<slug> (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 <slug>.jamdesk.app (o al tuo dominio personalizzato) da una finestra del browser che non contiene ancora il cookie.

Risoluzione dei problemi

Qual è il prossimo passo?