Autenticazione

EmDash usa l’autenticazione con passkey come metodo di accesso principale. Le passkey sono resistenti al phishing, non richiedono password e funzionano su tutti i dispositivi tramite il browser o il gestore di password.

Per i deploy su Cloudflare, puoi facoltativamente usare Cloudflare Access come provider di autenticazione alternativo.

Come funziona

Le passkey usano WebAuthn, uno standard web che crea credenziali a chiave pubblica memorizzate sul tuo dispositivo o sincronizzate tramite il gestore di password. Quando accedi, il dispositivo dimostra il possesso della credenziale senza mai inviare una password sulla rete.

Vantaggi dell’autenticazione con passkey:

• Niente password da ricordare o che possano essere sottratte
• Resistente al phishing — le credenziali sono legate al dominio del tuo sito
• Sincronizzazione tra dispositivi — funziona con Portachiavi iCloud, Google Password Manager, 1Password, ecc.
• Accesso rapido — un tocco con biometria o PIN

Configurazione del primo utente

La prima volta che accedi al pannello di amministrazione, la procedura guidata ti accompagna nella creazione dell’account amministratore.

Accesso

Dopo la configurazione, tornando al pannello admin si attiva l’autenticazione con passkey:

Fallback con magic link

Se non puoi usare la passkey (es.: dispositivo perso), i magic link offrono un’alternativa. Richiede la configurazione dell’email.

Accesso OAuth

EmDash supporta l’accesso OAuth con GitHub e Google se configurato. Gli utenti possono collegare i propri account dopo la configurazione iniziale della passkey.

Consulta la guida alla configurazione per le istruzioni.

Ruoli utente

EmDash usa il controllo degli accessi basato su ruoli con cinque livelli:

Ogni ruolo eredita i permessi di tutti i livelli inferiori. Il primo utente viene sempre creato come Admin.

Invitare utenti

Gli admin possono invitare nuovi utenti dal pannello admin:

Gli inviti sono validi per 7 giorni. Gli admin possono rinviare o revocare gli inviti dalla pagina Utenti.

Gestire le passkey

Gli utenti possono gestire le proprie passkey dalle impostazioni dell’account:

• Aggiungi passkey — Registra passkey aggiuntive per backup o altri dispositivi
• Rimuovi passkey — Elimina le passkey che non usi più
• Rinomina passkey — Dai nomi descrittivi alle passkey

Ogni utente può avere fino a 10 passkey registrate.

Registrazione autonoma

Per i siti di team, puoi abilitare la registrazione autonoma per domini email specifici:

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";

export default defineConfig({
	integrations: [
		emdash({
			auth: {
				selfSignup: {
					domains: ["example.com"],
					defaultRole: "contributor",
				},
			},
		}),
	],
});

Gli utenti con domini email corrispondenti possono registrarsi senza invito. Riceveranno un’email di verifica e registreranno una passkey per completare la registrazione.

Configurazione delle sessioni

Le sessioni usano cookie HttpOnly sicuri con impostazioni predefinite sensate:

emdash({
	auth: {
		session: {
			maxAge: 30 * 24 * 60 * 60, // 30 giorni (predefinito)
			sliding: true, // Reimposta la scadenza ad ogni attività
		},
	},
});

Note sulla sicurezza

• Le passkey sono memorizzate come chiavi pubbliche — la chiave privata non lascia mai il tuo dispositivo
• La verifica della challenge previene attacchi di tipo replay
• Il rate limiting protegge dai tentativi brute force (5 tentativi/minuto/IP)
• Le sessioni sono HttpOnly, Secure, SameSite=Lax per la sicurezza dei cookie
• I token magic link sono hashati con SHA-256 — i token grezzi non vengono mai memorizzati

Risoluzione dei problemi

”No passkeys registered”

Se vedi questo errore durante l’accesso, la tua passkey potrebbe essere stata eliminata dal gestore di password. Chiedi a un admin di inviarti un magic link o un nuovo invito.

”Passkey authentication failed”

Di solito significa che la passkey è stata creata per un dominio diverso. Le passkey sono legate al dominio — una passkey per localhost:4321 non funzionerà su example.com. Registra una nuova passkey per ogni dominio.

”Session expired”

Le sessioni durano 30 giorni per impostazione predefinita con scadenza scorrevole. Se vieni disconnesso inaspettatamente, cancella i cookie e accedi di nuovo.

Tutte le passkey perse

Se hai perso l’accesso a tutte le passkey registrate:

1. Chiedi a un altro admin di inviarti un magic link (richiede configurazione email)
2. Usa il magic link per accedere
3. Registra una nuova passkey nelle impostazioni dell’account

Se sei l’unico admin e l’email non è configurata, dovrai reimpostare l’autenticazione del sito tramite il database.

Cloudflare Access

Quando distribuisci su Cloudflare, puoi usare Cloudflare Access come provider di autenticazione al posto delle passkey. Access gestisce l’autenticazione al edge usando il tuo identity provider esistente.

Perché usare Cloudflare Access?

• Single Sign-On — Gli utenti si autenticano con l’IdP aziendale
• Controllo accessi centralizzato — Gestisci chi può accedere all’admin dalla dashboard Cloudflare
• Nessuna gestione passkey — Non serve registrare o gestire passkey
• Ruoli basati su gruppi — Mappa automaticamente i gruppi IdP ai ruoli EmDash

Configurazione

1. Crea un’applicazione Cloudflare Access per il tuo sito EmDash
2. Annota l’Application Audience (AUD) Tag dalle impostazioni dell’applicazione
3. Configura EmDash per usare Access:

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
import emdash from "emdash/astro";
import { d1, access } from "@emdash-cms/cloudflare";

export default defineConfig({
	output: "server",
	adapter: cloudflare(),
	integrations: [
		emdash({
			database: d1({ binding: "DB" }),
			auth: access({
				teamDomain: "myteam.cloudflareaccess.com",
				audience: "abc123def456...", // Dalle impostazioni dell'app Access
			}),
		}),
	],
});

Opzioni di configurazione

Mappatura dei ruoli

Mappa i gruppi IdP ai ruoli EmDash:

emdash({
	auth: access({
		teamDomain: "myteam.cloudflareaccess.com",
		audience: "abc123...",
		roleMapping: {
			Admins: 50, // Admin
			"Content Editors": 40, // Editor
			Writers: 30, // Author
		},
		defaultRole: 20, // Contributor per utenti non in nessun gruppo
	}),
});

Il primo gruppo corrispondente ha la priorità se un utente appartiene a più gruppi. Il primo utente ad accedere al sito diventa sempre Admin, indipendentemente dai gruppi.

Comportamento della sincronizzazione ruoli

Per impostazione predefinita (syncRoles: false), il ruolo di un utente viene impostato al primo accesso e non cambia successivamente. Questo permette agli admin di regolare manualmente i ruoli in EmDash.

Imposta syncRoles: true se vuoi che i gruppi IdP siano autoritativi — il ruolo dell’utente verrà aggiornato ad ogni accesso in base ai gruppi attuali.

Come funziona

1. L’utente visita /_emdash/admin
2. Cloudflare Access intercetta e reindirizza al tuo IdP
3. L’utente si autentica (SSO, MFA, ecc.)
4. Access imposta un JWT firmato nella richiesta
5. EmDash valida il JWT e crea/autentica l’utente

Funzionalità disabilitate

Quando Access è abilitato, queste funzionalità non sono disponibili:

• Pagina di accesso (/_emdash/admin/login)
• Registrazione e gestione passkey
• Accesso OAuth
• Accesso con magic link
• Registrazione autonoma
• Inviti utente

La gestione utenti viene fatta interamente tramite le policy di Cloudflare Access.

Risoluzione dei problemi

”No Access JWT present”

La richiesta ha raggiunto EmDash senza un JWT Access. Questo significa:

• Access non è configurato per proteggere la tua applicazione
• La policy Access non corrisponde alle rotte admin

Verifica che la tua applicazione Access copra /_emdash/admin/*.

”JWT audience mismatch”

L’audience nella tua configurazione non corrisponde al JWT. Ricontrolla l’Application Audience Tag nelle impostazioni dell’applicazione Access.

”User not authorized”

L’utente si è autenticato tramite Access ma autoProvision è false e non esiste in EmDash. Puoi:

• Impostare autoProvision: true, oppure
• Creare l’utente manualmente prima che acceda