Accesso Atmosphere

Il pacchetto @emdash-cms/auth-atproto aggiunge a EmDash un’opzione di accesso con account Atmosphere. Un account Atmosphere è un’identità portabile e di proprietà dell’utente, usata su Bluesky e altre app della rete AT Protocol. Gli utenti accedono con il proprio handle (es. alice.bsky.social) e si autenticano presso il proprio provider — EmDash non vede mai una password.

È adatto quando:

• I tuoi collaboratori hanno già un account Atmosphere.
• Vuoi limitare un dominio controllato dall’organizzazione (*.tuazienda.com) senza gestire app OAuth o inviti.
• Stai costruendo qualcosa nell’ecosistema Atmosphere e vuoi un’identità coerente con il resto del tuo stack.

Installazione

pnpm add @emdash-cms/auth-atproto

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { atproto } from "@emdash-cms/auth-atproto";

export default defineConfig({
	integrations: [
		emdash({
			authProviders: [atproto()],
			server: {
				host: "127.0.0.1", // obbligatorio in sviluppo locale — vedi «Sviluppo locale» sotto
			},
		}),
	],
});

È sufficiente per mostrare Accedi con Atmosphere nella pagina di login e nella procedura guidata di configurazione. Senza allowlist, il primo utente diventa Admin e l’autoregistrazione si chiude per tutti gli altri — vedi allowlist per aprirla.

Non servono variabili d’ambiente, client secret o registrazione di app OAuth. Il provider è un client OAuth pubblico e espone il proprio documento di metadati su /.well-known/atproto-client-metadata.json.

Configurazione

atproto({
	allowedDIDs: ["did:plc:abc123..."],
	allowedHandles: ["*.example.com", "alice.bsky.social"],
	defaultRole: 30, // Author
});

La scala completa dei ruoli è documentata nella guida principale sull’autenticazione.

Allowlist

Se non imposti né allowedDIDs né allowedHandles, solo il primo utente può registrarsi — chiunque altro riceve signup_not_allowed al tentativo di login. Gli utenti esistenti possono sempre rientrare a prescindere dall’allowlist (quindi toglierti dalla lista non ti blocca, ma non fa entrare nuove persone).

Con almeno un’allowlist configurata, un utente è ammesso se una delle condizioni è vera:

• Corrispondenza DID. Il DID dell’utente è in allowedDIDs. I DID sono identificatori crittografici non spostabili né impersonabili: è la forma più restrittiva di filtro.
• Corrispondenza handle. L’handle corrisponde a una voce in allowedHandles, in modo esatto o con pattern wildcard iniziale (*.example.com corrisponde a alice.example.com e bob.team.example.com).

Le allowlist sugli handle sono sicure anche se gli handle mutano. Prima di ammettere tramite handle, EmDash risolve in modo indipendente il record DNS/HTTP dell’handle e verifica che punti allo stesso DID dichiarato dal provider. Un provider scorretto non può semplicemente affermare di possedere [email protected].

Ruolo predefinito

Gli utenti ammessi ricevono il ruolo impostato in defaultRole. Solo il primo utente — quello che completa il setup — è forzato ad Admin. Non c’è mappatura gruppo/ruolo per gli account Atmosphere; per ruoli più granulari modifica il ruolo da Impostazioni → Utenti dopo almeno un accesso.

Setup del primo utente

Avviando un sito nuovo con il provider Atmosphere, la procedura guidata lo propone per creare l’account amministratore iniziale.

Lo stesso flusso vale per ogni accesso successivo: handle, redirect al provider, ritorno, sessione attiva.

Sviluppo locale

Il profilo OAuth dell’AT Protocol richiede che gli URI di reindirizzamento loopback usino un letterale IP (127.0.0.1 o [::1]), non localhost. EmDash riscrive in modo trasparente ://localhost in ://127.0.0.1 quando genera l’URI di reindirizzamento: la sessione di dev deve quindi partire anch’essa da 127.0.0.1, altrimenti il cookie di sessione impostato su localhost non sarà visibile dopo il redirect su 127.0.0.1.

Il server di sviluppo di Astro è quello di Vite, e Vite di default è in ascolto su localhost. Configuralo per ascoltare anche sull’IP di loopback:

export default defineConfig({
	server: {
		host: "127.0.0.1",
	},
	// ...
});

Poi apri http://127.0.0.1:4321/_emdash/admin per l’intero flusso.

Produzione

In produzione non c’è altro da configurare. Il provider espone i metadati client su:

https://tuo-sito.example.com/.well-known/atproto-client-metadata.json

I server di autorizzazione recuperano questo URL durante il flusso di login per verificare l’URI di reindirizzamento del client. Assicurati che l’URL pubblico del deployment sia raggiungibile su Internet via HTTPS — deployment solo interni dietro VPN non possono completare il login perché il server di autorizzazione dell’utente non può scaricare il documento di metadati.

Se EmDash è dietro un reverse proxy che termina il TLS, imposta siteUrl così che EmDash costruisca l’URI di reindirizzamento corretta. Senza, le richieste sembrano http://internal-host:4321 e i metadati non coincidono con ciò che vede il server di autenticazione.

Risoluzione dei problemi

«Account is not in the allowlist»

L’handle o il DID con cui hai effettuato l’accesso non è in allowedDIDs / allowedHandles. Controlla il pattern wildcard (deve iniziare con *.) e ricorda che la corrispondenza sull’handle è verificata via DNS/HTTP: se il record DID dell’handle non risolve attualmente sullo stesso DID restituito dal provider, la corrispondenza viene rifiutata.

«Self-signup is not allowed»

Il callback è andato a buon fine ma non c’è allowlist e non sei il primo utente. Aggiungiti a allowedDIDs/allowedHandles, oppure fatti invitare da un admin esistente in modo che l’utente esista già al login.

Il login reindirizza alla pagina di login senza errori

Quasi sempre è il problema del cookie loopback descritto in Sviluppo locale. Apri l’admin su http://127.0.0.1:4321 (dopo aver impostato server.host: "127.0.0.1") e riprova.

Risoluzione dell’handle fallita per handle self-hosted

Il provider verifica gli handle facendo gareggiare DNS-over-HTTPS (endpoint DoH di Cloudflare) e la richiesta HTTP a /.well-known/atproto-did. Gli handle self-hosted richiedono almeno uno tra:

• Un record TXT DNS _atproto.<handle> contenente did=<tuo-did>, oppure
• Un file https://<handle>/.well-known/atproto-did che contiene il DID.

Se entrambi i metodi falliscono, la corrispondenza sull’handle viene rifiutata anche se l’account sottostante è valido. I DID in allowedDIDs non sono interessati — vengono confrontati direttamente.