IllusionCMS
IT
Manuale · 15

Account, sicurezza e token API

Utenti

In Impostazioni → Utenti crei altri account. Tutti gli account sono amministratori con accesso completo; una gestione dei permessi volutamente non esiste.

  • Crea account: nome utente e password (almeno 8 caratteri) – le credenziali le trasmetti alla persona in modo sicuro.
  • Imposta password: per le password dimenticate. L’account viene disconnesso su tutti i dispositivi.
  • Elimina: disconnette subito l’account; i contenuti restano. Il proprio account e l’ultimo account non si possono eliminare.
  • L’elenco mostra quando qualcuno ha effettuato l’ultimo accesso.

Aspetto e lingua

In fondo al menu principale – e in alto a destra nella pagina di accesso:

  • Aspetto (i tre simboli sole, luna, schermo): Chiaro, Scuro o Sistema (predefinito – segue l’impostazione chiaro/scuro del sistema operativo e cambia con essa), Chiaro o Scuro. Editor dei Workflows, statistiche e mappa del mondo si adattano. Gli editor di codice restano scuri in entrambe le varianti, come si è abituati negli ambienti di sviluppo – così l’evidenziazione della sintassi resta ben leggibile. L’anteprima del tuo sito resta com’è il sito stesso.
  • Lingua dell’interfaccia (clic sulla bandiera): Lingua del browser (predefinito) oppure fissa inglese, tedesco, francese, italiano o spagnolo. Se la lingua del browser non è supportata, compare l’inglese.

Entrambe le impostazioni valgono per questo browser (salvate nel browser, non nell’account) – su un altro computer le imposti lì. La lingua dell’interfaccia non ha nulla a che fare con la lingua dei contenuti del tuo sito.

Accesso

  • Cambia password: Impostazioni → Il mio account.
  • Protezione del login: dopo 10 tentativi falliti dallo stesso indirizzo IP i login vengono bloccati per 15 minuti.
  • Le sessioni valgono 14 giorni.

Token API

Per programmi esterni (script di sincronizzazione, frontend headless, automazioni) crei un token in Impostazioni → Token API:

  • Solo lettura – può recuperare contenuti.
  • Lettura + scrittura – può creare e modificare contenuti, ma non gestire token o password.

Il token viene mostrato una sola volta. Uso: header Authorization: Bearer <token>, per semplici richieste GET anche come parametro URL ?token=<token> (finisce però nella cronologia e nei log del server – meglio usare un token di sola lettura). Revoca lo blocca immediatamente. Tutti gli endpoint si trovano nella documentazione API.

Integrazioni e modifiche atomiche

I programmi che gestiscono IllusionCMS tramite l’API (ad es. IllusionPublish, n8n o i tuoi script) salvano più modifiche a pagine, voci, blocchi globali, snippet e file in una volta sola con POST /batch: o va tutto a buon fine o non cambia nulla – anche se nel frattempo qualcuno ha modificato una delle pagine coinvolte. Con una chiave di idempotenza puoi ripetere un batch senza rischi, senza creare nulla due volte. Se un token scrive per conto di una persona (header X-IC-On-Behalf-Of), la cronologia delle versioni mostra ad es. Token „Publish“ – im Auftrag von Maria Muster. GET /schema restituisce collection, blocchi, lingue e siti in un’unica risposta. I dettagli sono nella documentazione API. Questi programmi vengono informati delle modifiche tramite i webhook.

Webhook

I webhook avvisano altri programmi non appena qualcosa cambia: IllusionCMS invia allora un POST con una descrizione JSON della modifica a un indirizzo – ad esempio a n8n, a un servizio che ricostruisce un sito statico, a IllusionPublish o a un ingresso HTTP di un tuo workflow.

Configurare un webhook

In Impostazioni → Webhook fai clic su + Webhook e indica un nome (facoltativo), l’indirizzo (http:// o https://), gli eventi desiderati e Attivo. Lascia vuoto il campo del secret – IllusionCMS ne genera uno e lo mostra una sola volta. Copialo e salvalo presso il destinatario. In seguito, in Modifica, puoi generare un Nuovo secret (quello vecchio smette subito di funzionare) o inserirne uno tuo (almeno 16 caratteri).

  • Il secret è salvato nel database solo in forma cifrata – come il secret S3. Se sposti il database su un altro server, porta con te IC_ENCRYPTION_KEY o data/secret.key (vedi Salvare i media in S3).
  • I webhook appartengono all’istanza, non ai contenuti: non fanno parte del bundle. In modalità remota modifichi i webhook del server.
  • Al massimo 20 webhook; quelli inattivi non ricevono nulla (tranne Invia test).

Eventi dei webhook

  • content.changed – pagine, voci, blocchi globali, file, snippets o CSS/JS sono stati creati, modificati, spostati o eliminati, anche tramite import, bundle, import CSV o batch. Le modifiche entro circa 2 secondi arrivano come un’unica consegna – salvare dieci voci non avvia dieci build.
  • schema.changed – una collection è stata creata, modificata o eliminata, oppure è cambiato lo schema di un tipo di blocco. Include la schema_version attuale di GET /schema.
  • batch.applied – è stato applicato un POST /batch, con i suoi risultati.

Ecco come appare una consegna:

{ "event": "content.changed", "at": 1791572100,
  "changes": [ { "kind": "page", "action": "updated", "id": 12 },
               { "kind": "item", "action": "created", "id": 31, "collection": "blog" } ] }

Tutti i formati sono descritti nella documentazione API.

Verificare la firma

Ogni consegna porta l’header X-IC-Signature: sha256=… – un HMAC-SHA256 del body con il tuo secret. Il destinatario lo ricalcola e scarta tutto ciò che non corrisponde; così nessuno può introdurre eventi falsi. Importante: calcolalo sul body non modificato, non su JSON rigenerato. In Node.js: Inviamo anche X-IC-Timestamp e X-IC-Signature-V2 (HMAC su timestamp.body); se vuoi, rifiuta le consegne con un timestamp più vecchio di 5 minuti (protezione dal replay). La risposta del destinatario non compare nel registro delle consegne, solo il codice di stato.

const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
const ok = expected.length === header.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header))

Un esempio completo in JavaScript e Go si trova nella documentazione API. Altri header: X-IC-Event (evento) e X-IC-Delivery (ID univoco, uguale nei tentativi successivi – serve a riconoscere le consegne doppie). I workflow di questa istanza non possono verificare la firma (il nodo Function non conosce HMAC).

Test e consegne

  • Invia test invia subito un evento ping e mostra il risultato – stato HTTP e durata, oppure l’errore.
  • Consegne mostra le ultime 50 consegne dall’avvio del server: ora, evento, stato (consegnato, non riuscito, in corso, saltato), stato HTTP, durata, tentativi ed errore con l’inizio della risposta. Dopo un riavvio l’elenco è vuoto.
  • Se il destinatario non risponde entro 10 secondi, oppure risponde 408, 429 o 5xx, IllusionCMS riprova fino a tre volte (dopo 2, 10 e 30 secondi). Altre risposte come 404 non vengono ripetute; qualsiasi risposta 2xx conta come consegnata.
  • Protezione dai cicli: se un webhook chiama un tuo workflow che modifica di nuovo i contenuti, questo si ripeterebbe all’infinito. Per questo ci si ferma dopo tre consegne consecutive – le successive compaiono come saltato nel registro.
  • Per provare senza un servizio esterno: un workflow con un ingresso HTTP pubblico (POST) che salva msg.payload con store.set(…) e un webhook verso il suo indirizzo – è ciò che fa anche il seed di test.

Header di sicurezza

In Impostazioni → Sicurezza stabilisci quali header di protezione IllusionCMS invia. Le impostazioni valgono solo per questa istanza e non sono nel bundle, quindi in locale e sul server live le imposti separatamente. La tabella Header inviati mostra il risultato.

Impostazione Predefinito Effetto
X-Content-Type-Options: nosniff sempre attivo I browser non indovinano il tipo di file, un’immagine caricata ad es. non viene mai eseguita come script
Referrer Standard I siti esterni, al clic su un link, vedono solo il tuo dominio, non la pagina esatta
Incorporamento (iframe) Solo le proprie pagine Protegge dal clickjacking: le pagine esterne non possono incorporare le tue in modo invisibile. Proprie pagine e domini specifici lo consente ad es. a un partner (https://partner.de, *.partner.de), Consentito ovunque disattiva la protezione
Blocca funzioni del browser disattivato Blocca fotocamera, microfono, posizione, pagamenti, USB/Bluetooth e altro. Lascialo disattivato se una pagina usa ad es. “La mia posizione” in una mappa
HSTS disattivato I browser richiamano il sito solo tramite HTTPS. Viene inviato solo tramite HTTPS, anche dietro un proxy che imposta X-Forwarded-Proto: https. Attenzione: i browser lo ricordano per la durata impostata, anche se disattivi di nuovo HSTS. Attivalo solo quando HTTPS funziona stabilmente, e per provare inizia con 5 minuti
Content-Security-Policy vuoto Regole proprie su da dove si possono caricare script, immagini, font … Con Solo segnalare, non bloccare il browser non blocca nulla, ma segnala le violazioni nella console. Così provi una regola prima di renderla operativa
Nascondi la versione in /healthz disattivato I visitatori vedono solo {"status":"ok"}. Gli utenti connessi e i token API continuano a vedere la versione (l’indicazione della versione nell’admin funziona quindi)

Incorporamento, funzioni del browser e CSP valgono per le pagine del sito (pagine, 404, sitemap, robots.txt), non per l’admin, l’API, i file e CSS/JS. L’anteprima dell’admin non ne è interessata.

Cosa dovresti sapere

  • HTML, CSS e JS sono considerati affidabili. Chi lavora nell’admin può portare qualsiasi codice sul sito – assegna gli accessi e i token di scrittura di conseguenza.
  • I campi Markdown non emettono HTML incorporato; le voci di Collection che arrivano dall’esterno tramite API non possono così iniettare codice.
  • Gli SVG caricati vengono serviti con una policy di sicurezza che blocca gli script incorporati. I file HTML, XML e con estensione sconosciuta caricati vengono serviti senza esecuzione di script e come download (policy sandbox, nessun rilevamento del tipo) – si possono ancora caricare e collegare, ma non vengono eseguiti come pagina nell’origine dell’admin.