Accesso Atmosphere

Il pacchetto @emdash-cms/auth-atproto aggiunge un’opzione di accesso con account Atmosphere a EmDash. Un account Atmosphere è un’identità portatile di proprietà dell’utente usata su Bluesky e altre app nella rete AT Protocol. Gli utenti accedono con il loro 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 controllare l’accesso con un dominio dell’organizzazione (*.tuaazienda.com) senza gestire app OAuth o inviti.
Stai costruendo qualcosa che fa parte dell’Atmosphere più ampia e vuoi un’identità coerente con il resto del tuo stack.

Installare

Installa il pacchetto del provider:

pnpm add @emdash-cms/auth-atproto

Aggiungi il provider all’integrazione EmDash:

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

export default defineConfig({
	server: {
		host: "127.0.0.1", // richiesto per lo sviluppo locale; vedi sotto
	},
	integrations: [
		emdash({
			authProviders: [atproto()],
		}),
	],
});

Questo è sufficiente per mettere Sign in with Atmosphere sulla pagina di login e la procedura guidata di setup. Senza allowlist configurata, il primo utente diventa Admin e la registrazione automatica viene chiusa per tutti dopo — vedi allowlist per aprirla.

Il provider è un client OAuth pubblico e serve il proprio documento di metadati su /.well-known/atproto-client-metadata.json, quindi funziona con la sola configurazione sopra — nessuna variabile d’ambiente, client secret o registrazione app OAuth da configurare.

Configurare l’accesso

Il provider atproto() accetta un’allowlist e un ruolo predefinito:

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

Opzione	Tipo	Predefinito	Descrizione
`allowedDIDs`	`string[]`	nessuno	Allowlist esatta di DID.
`allowedHandles`	`string[]`	nessuno	Allowlist di handle. Supporta wildcard iniziali (`*.example.com`).
`defaultRole`	`number`	`10` (Subscriber)	Ruolo assegnato agli utenti consentiti dopo il primo. Il primo è sempre Admin.

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

Allowlist

Se né allowedDIDs né allowedHandles sono impostati, solo il primo utente può registrarsi. Gli account già collegati a un utente EmDash possono continuare ad accedere, mentre un nuovo account viene rifiutato con signup_not_allowed.

Quando almeno un’allowlist è configurata, ogni login deve corrispondere, inclusi i login per utenti esistenti. Rimuovere la DID e l’handle di un utente esistente dalle liste configurate impedisce a quell’account di accedere. Un utente viene ammesso se una delle liste corrisponde:

Corrispondenza DID. L’identificatore stabile dell’account dell’utente corrisponde esattamente a un valore in allowedDIDs.
Corrispondenza handle. L’handle dell’utente corrisponde a una voce in allowedHandles, esattamente o tramite un pattern wildcard iniziale (*.example.com corrisponde a alice.example.com e bob.team.example.com).

Le allowlist di handle sono sicure anche se gli handle sono mutabili. Prima di ammettere un utente tramite corrispondenza handle, EmDash risolve indipendentemente il record DNS/HTTP dell’handle e verifica che punti alla stessa DID che il provider dichiara. Un provider che si comporta male non può semplicemente affermare di possedere te.tuaazienda.com.

Ruolo predefinito

Gli utenti consentiti arrivano con il ruolo impostato in defaultRole. Solo il primo utente — quello che completa il setup — viene forzato ad Admin. Non c’è mappatura gruppo/ruolo per gli account Atmosphere; se hai bisogno di ruoli più granulari, cambia il ruolo dell’utente da Impostazioni → Utenti dopo che ha effettuato l’accesso una volta.

Configurare il primo utente

Quando avvii un nuovo sito con il provider Atmosphere configurato, la procedura guidata di setup lo offre come opzione per creare l’account admin iniziale.

Visita /_emdash/admin. In Set up your site, inserisci il titolo del sito e il sottotitolo opzionale, poi continua.
In Create your account, inserisci l’indirizzo email e il nome opzionale da memorizzare sull’utente EmDash.
In Secure your account, scegli Atmosphere, inserisci il tuo handle (ad esempio, alice.bsky.social) e continua.
Il tuo provider dell’account apre la sua pagina di autorizzazione. Accedi usando il metodo supportato dal provider e approva la richiesta.
Il provider ti reindirizza a EmDash. EmDash crea il primo utente come Admin, memorizza l’email del passaggio 2, stabilisce una sessione EmDash e apre la dashboard.

I login successivi iniziano con l’handle, continuano presso il provider dell’account e tornano con una sessione EmDash. Lo stato OAuth e i token del provider sono memorizzati separatamente dalla sessione EmDash così che il callback OAuth possa completarsi e il provider possa aggiornare la propria sessione.

Sviluppo locale

Il profilo OAuth dell’AT Protocol richiede che gli URI di redirect loopback usino un letterale IP (127.0.0.1 o [::1]), non localhost. EmDash riscrive trasparentemente ://localhost in ://127.0.0.1 quando genera l’URI di redirect, ma ciò significa che la tua sessione di sviluppo deve iniziare su 127.0.0.1 — altrimenti il cookie di sessione impostato su localhost non sarà visibile dopo che il redirect ti porta su 127.0.0.1.

Il server di sviluppo di Astro usa Vite, che si lega a localhost per default. Imposta l’opzione server.host di Astro 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

La stessa configurazione funziona in produzione. Il provider serve i propri metadati client su:

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

I server di autorizzazione recuperano questo URL durante il login per verificare l’URI di redirect del client. Assicurati che l’URL del sito del tuo deployment sia raggiungibile sull’internet pubblico via HTTPS — i deployment solo interni dietro una VPN non potranno completare un login perché il server di autorizzazione dell’utente non può recuperare il documento di metadati.

Se esegui EmDash dietro un reverse proxy che termina TLS, imposta siteUrl così EmDash costruisce l’URI di redirect corretta. Senza di esso, le richieste appaiono come http://host-interno:4321 e i metadati non corrisponderanno a ciò che il server di autenticazione vede.

Risoluzione dei problemi

”Account is not in the allowlist”

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

Hai raggiunto il callback con successo, ma nessuna allowlist è configurata e non sei il primo utente. Aggiungi la DID dell’account a allowedDIDs o il suo handle verificato a allowedHandles. Un invito email non collega una DID Atmosphere a un utente EmDash.

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

La risoluzione handle fallisce per un handle self-hosted

Il provider verifica gli handle testando in parallelo DNS-over-HTTPS (endpoint DoH di Cloudflare) e una ricerca HTTP /.well-known/atproto-did. Gli handle self-hosted hanno bisogno di almeno uno tra:

Un record DNS TXT _atproto.<handle> contenente did=<tua-did>, oppure
Un file https://<handle>/.well-known/atproto-did contenente la DID.

Se entrambi i metodi falliscono, la corrispondenza handle viene rifiutata anche quando l’account sottostante è valido. Le DID in allowedDIDs non sono interessate — sono confrontate direttamente.