Accesso Atmosphere

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

È una buona scelta quando:

• I tuoi collaboratori hanno già un account Atmosphere.
• Vuoi limitare l’accesso a un dominio controllato da un’organizzazione (*.yourcompany.com) senza gestire app OAuth o inviti.
• Stai realizzando qualcosa che fa parte dell’ecosistema Atmosphere più ampio 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 di 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", // required for local development; see below
	},
	integrations: [
		emdash({
			authProviders: [atproto()],
		}),
	],
});

È sufficiente per mostrare Sign in with Atmosphere nella pagina di accesso e nella procedura guidata di configurazione. Se non è configurata alcuna allowlist, il primo utente diventa Admin e l’iscrizione autonoma viene poi chiusa per tutti — vedi le allowlist per aprirla.

Il provider è un client OAuth pubblico e serve il proprio documento di metadati in /.well-known/atproto-client-metadata.json, quindi funziona con la sola configurazione qui sopra — non ci sono variabili d’ambiente, client secret o registrazioni di app OAuth da impostare.

Configurare l’accesso

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

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

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

Allowlist

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

Quando è configurata almeno una allowlist, ogni accesso deve corrispondervi, compresi quelli degli utenti esistenti. Rimuovere il DID e l’handle di un utente esistente dalle liste configurate impedisce a quell’account di accedere. Un utente viene ammesso se corrisponde una qualsiasi delle due liste:

• Corrispondenza del DID. L’identificatore stabile dell’account dell’utente corrisponde esattamente a un valore in allowedDIDs.
• Corrispondenza dell’handle. L’handle dell’utente corrisponde a una voce di allowedHandles, esattamente oppure tramite un pattern con carattere jolly iniziale (*.example.com corrisponde a alice.example.com e bob.team.example.com).

Le allowlist di handle sono sicure anche se gli handle sono modificabili. Prima di ammettere un utente tramite una corrispondenza di handle, EmDash risolve in modo indipendente il record DNS/HTTP dell’handle e verifica che punti allo stesso DID dichiarato dal provider. Un provider malfunzionante non può limitarsi ad affermare di possedere you.yourcompany.com.

Ruolo predefinito

Gli utenti consentiti ottengono il ruolo che imposti in defaultRole. Solo il primo utente — quello che completa la configurazione — viene forzato ad Admin. Non esiste una mappatura gruppo/ruolo per gli account Atmosphere; se ti servono ruoli più granulari, modifica il ruolo dell’utente nella pagina Users della barra laterale dell’amministrazione dopo che ha effettuato un primo accesso.

Configurare il primo utente

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

Gli accessi successivi iniziano con l’handle, proseguono presso il provider dell’account e ritornano con una sessione EmDash. Lo stato OAuth e i token del provider vengono memorizzati separatamente da quella sessione EmDash, in modo che il callback OAuth possa completarsi e il provider possa rinnovare la propria sessione.

Sviluppo locale

Il profilo OAuth di AT Protocol richiede che gli URI di redirect loopback usino un IP letterale (127.0.0.1 o [::1]), non localhost. EmDash riscrive in modo trasparente ://localhost in ://127.0.0.1 quando genera l’URI di redirect, ma questo significa che anche 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 per impostazione predefinita si associa a localhost. Imposta l’opzione server.host di primo livello 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 tutto il flusso.

Produzione

La stessa configurazione funziona in produzione. Il provider serve i propri metadati del client all’indirizzo:

https://your-site.example.com/.well-known/atproto-client-metadata.json

I server di autorizzazione recuperano questo URL durante l’accesso per verificare l’URI di redirect del client. Assicurati che l’URL del sito della tua distribuzione sia raggiungibile su internet pubblico tramite HTTPS — le distribuzioni solo interne dietro una VPN non potranno completare un accesso perché il server di autorizzazione dell’utente non riesce a recuperare il documento di metadati.

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

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 con carattere jolly (deve iniziare con *.) e ricorda che la corrispondenza dell’handle viene verificata tramite DNS/HTTP — se il record DID dell’handle non si risolve attualmente nello stesso DID restituito dal provider, la corrispondenza viene rifiutata.

”Self-signup is not allowed”

Hai raggiunto correttamente il callback, ma non è configurata alcuna allowlist e non sei il primo utente. Aggiungi il DID dell’account a allowedDIDs o il suo handle verificato a allowedHandles. Un invito via e-mail non collega un DID Atmosphere a un utente EmDash.

Il login reindirizza alla pagina di login senza errore

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 facendo competere DNS-over-HTTPS (l’endpoint DoH di Cloudflare) e una ricerca HTTP su /.well-known/atproto-did. Gli handle self-hosted richiedono almeno uno dei seguenti elementi:

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

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