Autenticazione JWT

Se il tuo prodotto dispone già di un proprio sistema di accesso, l'autenticazione JWT ti consente di proteggere la documentazione tramite questo sistema invece di distribuire una passphrase condivisa. Il tuo backend firma un token a breve durata quando un utente autenticato accede alla documentazione. Jamdesk lo verifica una volta, crea una sessione e da quel momento il visitatore può navigare normalmente. I visitatori non hanno mai bisogno di un account Jamdesk o di una password condivisa.

Differenze rispetto alla protezione con password

La protezione con password assegna a ogni visitatore la stessa passphrase condivisa, una soluzione adatta alla documentazione interna, alle anteprime di staging o a un singolo gruppo di partner. L'autenticazione JWT è specifica per utente: identità, durata della sessione e accesso alle pagine di ogni visitatore provengono da un token firmato dal tuo backend. L'accesso alla documentazione può seguire gli account cliente, i piani o i ruoli esistenti, invece di usare un unico segreto condiviso.

Le due modalità si escludono a vicenda: auth.password e auth.jwt non possono essere abilitate contemporaneamente. Se stai passando da una modalità all'altra, consulta Migrazione dalla protezione con password.

Procedura di configurazione

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "Acme Docs",
  "theme": "jam",
  "auth": {
    "jwt": {
      "enabled": true,
      "loginUrl": "https://app.example.com/docs-login",
      "public": ["/changelog/*"]
    }
  }
}

git add docs.json
git commit -m "Turn on JWT authentication"
git push

Integra il flusso di accesso

Quando un utente autenticato accede alla documentazione, il tuo backend firma un JWT e reindirizza il browser all'URL di callback del sito della documentazione, inserendo il token nel frammento dell'URL (dopo #). I frammenti non arrivano mai nei log del server o a un proxy inverso, perché i browser non li inviano con la richiesta.

Il token deve essere firmato con EdDSA (Ed25519, in corrispondenza con la chiave generata nel dashboard) e il suo claim exp dovrebbe essere impostato a non più di circa 10 secondi nel futuro. Si tratta di una finestra di handshake, non della durata della sessione. La durata effettiva della sessione è controllata separatamente dal campo expiresAt nel payload (consulta il riferimento del payload di seguito).

import { SignJWT, importPKCS8 } from "jose";

// Store this in your secret manager. It's the private key Jamdesk showed
// you once when you generated it in Project Settings.
const privateKey = await importPKCS8(process.env.JAMDESK_JWT_PRIVATE_KEY!, "EdDSA");

async function signDocsToken(user: { groups: string[] }) {
  return new SignJWT({
    host: "acme.jamdesk.app", // or your custom domain, e.g. "docs.example.com"
    expiresAt: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 7, // 7-day session
    groups: user.groups,
    apiPlaygroundInputs: {
      header: { Authorization: `Bearer ${user.apiToken}` },
    },
  })
    .setProtectedHeader({ alg: "EdDSA" })
    .setExpirationTime("10s") // handshake window, not session length
    .sign(privateKey);
}

// In your "open docs" route/button handler:
app.get("/docs-login", requireAuth, async (req, res) => {
  const token = await signDocsToken(req.user);
  const redirect = req.query.redirect ?? "/";
  res.redirect(
    `https://acme.jamdesk.app/_jd/auth/callback?redirect=${encodeURIComponent(
      String(redirect)
    )}#${token}`
  );
});

import time
import jwt  # PyJWT >= 2.4, with the cryptography extra installed

with open("jamdesk_jwt_private_key.pem", "rb") as f:
    PRIVATE_KEY = f.read()

def sign_docs_token(user):
    payload = {
        "host": "acme.jamdesk.app",  # or your custom domain
        "exp": int(time.time()) + 10,  # handshake window, not session length
        "expiresAt": int(time.time()) + 60 * 60 * 24 * 7,  # 7-day session
        "groups": user.groups,
        "apiPlaygroundInputs": {
            "header": {"Authorization": f"Bearer {user.api_token}"},
        },
    }
    return jwt.encode(payload, PRIVATE_KEY, algorithm="EdDSA")

@app.route("/docs-login")
def docs_login():
    token = sign_docs_token(current_user)
    redirect_path = request.args.get("redirect", "/")
    return redirect(
        f"https://acme.jamdesk.app/_jd/auth/callback"
        f"?redirect={quote(redirect_path)}#{token}"
    )

Flusso di reindirizzamento

1. Un visitatore richiede una pagina protetta (ad esempio /quickstart) senza una sessione valida. Jamdesk risponde reindirizzandolo a {loginUrl}?redirect=%2Fquickstart.
2. Il tuo flusso di accesso autentica il visitatore (secondo la procedura abituale), firma un JWT e lo reindirizza a https://<your-docs-host>/_jd/auth/callback?redirect=%2Fquickstart#<jwt>.
3. La pagina di callback legge il token dal frammento lato client e lo invia all'endpoint di scambio del token di Jamdesk. Jamdesk verifica la firma e i claim e, in caso di esito positivo, imposta un cookie di sessione firmato.
4. Il browser viene reindirizzato alla destinazione originale, /quickstart, ora con una sessione valida. Il valore redirect viene conservato dall'inizio alla fine, così i visitatori arrivano esattamente alla pagina da cui erano partiti.

Se il tuo backend non riesce a determinare un valore redirect (ad esempio perché qualcuno ha aggiunto direttamente ai segnalibri la pagina di accesso), omettilo e Jamdesk userà /.

Pagine pubbliche

Alcune pagine, come una pagina di stato o un changelog pubblico, dovrebbero restare accessibili senza effettuare l'accesso. Esistono tre modi per contrassegnare una pagina come pubblica e tutti confluiscono in un unico elenco di autorizzazione:

Frontmatter, per una pagina alla volta:

---
title: Changelog
public: true
---

Gruppi di navigazione, per un'intera sezione:

{
  "navigation": {
    "groups": [
      { "group": "Changelog", "public": true, "pages": ["changelog"] }
    ]
  }
}

Glob espliciti, in auth.jwt.public[]:

{
  "auth": {
    "jwt": {
      "enabled": true,
      "loginUrl": "https://app.example.com/docs-login",
      "public": ["/changelog/*", "/status"]
    }
  }
}

Accesso basato sui gruppi

Alcune pagine dovrebbero essere visibili solo a determinati utenti autenticati, ad esempio una guida operativa per amministratori o un riferimento riservato ai clienti enterprise. Aggiungi groups al frontmatter della pagina:

---
title: Admin API Keys
groups: ["admin"]
---

La sessione del visitatore contiene l'array groups inserito dal tuo backend nel payload JWT. Se una pagina dichiara groups e la sessione del visitatore non contiene alcun gruppo corrispondente, il visitatore riceve un 404 anziché un 401 o una schermata di sblocco. È intenzionale: una pagina con restrizioni di gruppo non rivela la propria esistenza agli utenti esterni al gruppo.

Dettagli che influiscono sull'utilizzo di groups:

• Le pagine di gruppo vengono escluse dalla sitemap, dalla ricerca, dalla chat AI e da MCP, anche per gli utenti appartenenti al gruppo. L'esclusione da queste superfici di scoperta è una decisione presa al momento della build, non per singolo visitatore. Un membro del gruppo admin può comunque aprire direttamente /admin/api-keys (tramite URL o link interno), ma la pagina non comparirà nei risultati di ricerca, nelle risposte della chat o in llms.txt. Se vuoi che una pagina riservata sia trovabile dal proprio pubblico, collegala da un'altra pagina già accessibile a quel pubblico.
• Un groups: [] vuoto non applica alcuna restrizione, non significa «nessuno può vedere questa pagina». Per rimuovere la restrizione di gruppo, elimina completamente il campo groups anziché impostarlo su un array vuoto.
• Per impedire l'accesso a tutti, annulla la pubblicazione della pagina. Non esiste un valore di groups che significhi «nessuno»: l'appartenenza ai gruppi è additiva e qualsiasi corrispondenza concede l'accesso.
• Le copie localizzate ereditano automaticamente i groups della pagina di base, a meno che la traduzione non dichiari i propri groups nel frontmatter. La traduzione di una pagina riservata non la rende accidentalmente pubblica.
• Mantieni brevi i nomi dei gruppi. I gruppi vengono trasmessi nel cookie di sessione: fino a 32 gruppi per sessione, con 64 caratteri ciascuno. Il superamento di uno dei due limiti non accorcia l'elenco: Jamdesk rifiuta l'intero token con un 401 e non concede alcuna sessione.

Precompilazione dell'API playground

Se la documentazione include un API playground, puoi precompilarlo per i visitatori autenticati, evitando che debbano incollare la propria chiave API. Includi apiPlaygroundInputs nel payload JWT:

{
  "host": "acme.jamdesk.app",
  "apiPlaygroundInputs": {
    "header": { "Authorization": "Bearer sk_live_user_specific_token" },
    "query": { "org_id": "acme-corp" },
    "path": { "workspace_id": "ws_123" }
  }
}

• header.Authorization precompila il campo di autenticazione del playground. Se presente, il prefisso Bearer viene rimosso automaticamente.
• query e path precompilano i nomi dei parametri corrispondenti sull'endpoint corrente.
• Le sezioni server e cookie non sono supportate. Vengono applicate solo header, query e path.
• La precompilazione non sovrascrive mai un valore già inserito dal visitatore nel playground.

Riferimento del payload

Disconnessione

I visitatori autenticati visualizzano un link Log out nell'intestazione della documentazione. Il link li porta a /_jd/auth/logout, che cancella il cookie di sessione e li reindirizza al tuo loginUrl. Puoi anche collegarlo direttamente dalla tua app se vuoi offrire altrove un link per «uscire dalla documentazione». È una semplice richiesta GET che non richiede body o intestazioni.

Comportamento delle funzionalità con autenticazione

Risoluzione dei problemi

Nota sulla sicurezza

apiPlaygroundInputs, incluso qualsiasi valore Authorization inserito al suo interno, è leggibile dal codice JavaScript eseguito sul sito della documentazione tramite l'endpoint delle informazioni di sessione che alimenta la precompilazione del playground. La precompilazione è comoda, ma non è adatta a segreti con privilegi elevati.

Invia credenziali specifiche per utente e con il minimo privilegio, limitate alle operazioni consentite a quel visitatore; non usare mai una chiave amministrativa valida per l'intera organizzazione. Considera visibile alla persona che consulta la documentazione qualsiasi elemento inserito in apiPlaygroundInputs, perché lo è.

Migrazione dalla protezione con password

Il passaggio da una password condivisa all'autenticazione JWT non richiede downtime e il sito resta protetto per tutta la durata dell'operazione. Eseguilo in quest'ordine:

{
  "auth": {
    "password": { "enabled": false },
    "jwt": { "enabled": true, "loginUrl": "https://app.example.com/docs-login" }
  }
}

Prossimi passi