Atmosphere-Anmeldung

Das Paket @emdash-cms/auth-atproto fügt EmDash eine Anmeldeoption mit einem Atmosphere-Konto hinzu. Ein Atmosphere-Konto ist eine portable, benutzereigene Identität, die über Bluesky und andere Apps im AT-Protocol-Netzwerk hinweg verwendet wird. Benutzer melden sich mit ihrem Handle an (z. B. alice.bsky.social) und authentifizieren sich bei ihrem eigenen Provider — EmDash sieht nie ein Passwort.

Das passt gut, wenn:

• Ihre Mitwirkenden bereits ein Atmosphere-Konto haben.
• Sie eine von einer Organisation kontrollierte Domain (*.yourcompany.com) absichern möchten, ohne OAuth-Apps oder Einladungen zu verwalten.
• Sie etwas entwickeln, das Teil der breiteren Atmosphere ist, und eine einheitliche Identität mit dem Rest Ihres Stacks wünschen.

Installieren

Installieren Sie das Provider-Paket:

pnpm add @emdash-cms/auth-atproto

Fügen Sie den Provider zur EmDash-Integration hinzu:

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()],
		}),
	],
});

Das genügt, um Sign in with Atmosphere auf der Anmeldeseite und im Einrichtungsassistenten anzuzeigen. Ist keine Allowlist konfiguriert, wird der erste Benutzer zum Admin, und die Selbstregistrierung ist danach für alle geschlossen — siehe Allowlists, um sie zu öffnen.

Der Provider ist ein öffentlicher OAuth-Client und liefert sein eigenes Metadatendokument unter /.well-known/atproto-client-metadata.json aus. Er funktioniert daher allein mit der obigen Konfiguration — es müssen keine Umgebungsvariablen, kein Client-Secret und keine OAuth-App-Registrierung eingerichtet werden.

Zugang konfigurieren

Der Provider atproto() akzeptiert eine Allowlist und eine Standardrolle:

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

Die vollständige Rollenleiter ist im Haupt-Authentifizierungsleitfaden dokumentiert.

Allowlists

Ist weder allowedDIDs noch allowedHandles gesetzt, kann sich nur der erste Benutzer registrieren. Konten, die bereits mit einem EmDash-Benutzer verknüpft sind, können sich weiterhin anmelden, während ein neues Konto mit signup_not_allowed abgelehnt wird.

Ist mindestens eine Allowlist konfiguriert, muss jede Anmeldung ihr entsprechen, auch Anmeldungen bestehender Benutzer. Wenn Sie die DID und den Handle eines bestehenden Benutzers aus den konfigurierten Listen entfernen, kann sich dieses Konto nicht mehr anmelden. Ein Benutzer wird zugelassen, wenn eine der beiden Listen passt:

• DID-Treffer. Die stabile Kontokennung des Benutzers stimmt exakt mit einem Wert in allowedDIDs überein.
• Handle-Treffer. Der Handle des Benutzers stimmt mit einem Eintrag in allowedHandles überein, exakt oder über ein Muster mit führendem Platzhalter (*.example.com passt auf alice.example.com und bob.team.example.com).

Handle-Allowlists sind sicher, obwohl Handles veränderlich sind. Bevor EmDash einen Benutzer über einen Handle-Treffer zulässt, löst es den DNS-/HTTP-Eintrag des Handles unabhängig auf und prüft, ob er auf dieselbe DID zeigt, die der Provider angibt. Ein sich fehlerhaft verhaltender Provider kann nicht einfach behaupten, ihm gehöre you.yourcompany.com.

Standard-Rolle

Zugelassene Benutzer erhalten die Rolle, die Sie in defaultRole festlegen. Nur der erste Benutzer — derjenige, der die Einrichtung abschließt — wird zwangsweise zum Admin. Für Atmosphere-Konten gibt es keine Gruppen-/Rollenzuordnung; wenn Sie feiner abgestufte Rollen benötigen, ändern Sie die Rolle des Benutzers auf der Seite Users in der Admin-Seitenleiste, nachdem er sich einmal angemeldet hat.

Ersten Benutzer einrichten

Wenn Sie eine neue Website mit konfiguriertem Atmosphere-Provider starten, bietet der Einrichtungsassistent ihn als Option zum Erstellen des ersten Admin-Kontos an.

Spätere Anmeldungen beginnen mit dem Handle, werden beim Kontoanbieter fortgesetzt und kehren mit einer EmDash-Sitzung zurück. Der OAuth-Status und die Tokens des Providers werden getrennt von dieser EmDash-Sitzung gespeichert, damit der OAuth-Callback abgeschlossen werden kann und der Provider seine eigene Sitzung erneuern kann.

Lokale Entwicklung

Das OAuth-Profil des AT Protocol verlangt, dass Loopback-Redirect-URIs ein IP-Literal (127.0.0.1 oder [::1]) verwenden, nicht localhost. EmDash schreibt beim Erzeugen der Redirect-URI ://localhost transparent in ://127.0.0.1 um. Das bedeutet jedoch, dass Ihre Entwicklungssitzung ebenfalls auf 127.0.0.1 beginnen muss — andernfalls ist das auf localhost gesetzte Sitzungs-Cookie nach der Weiterleitung auf 127.0.0.1 nicht sichtbar.

Der Entwicklungsserver von Astro verwendet Vite, das standardmäßig an localhost bindet. Setzen Sie die Astro-Option server.host auf oberster Ebene auf die Loopback-IP:

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

Öffnen Sie dann http://127.0.0.1:4321/_emdash/admin für den gesamten Ablauf.

Produktion

Dieselbe Konfiguration funktioniert in der Produktion. Der Provider liefert seine eigenen Client-Metadaten unter folgender Adresse aus:

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

Autorisierungsserver rufen diese URL bei der Anmeldung ab, um die Redirect-URI des Clients zu überprüfen. Stellen Sie sicher, dass die Website-URL Ihrer Bereitstellung über HTTPS im öffentlichen Internet erreichbar ist — rein interne Bereitstellungen hinter einem VPN können keine Anmeldung abschließen, weil der Autorisierungsserver des Benutzers das Metadatendokument nicht abrufen kann.

Wenn Sie EmDash hinter einem Reverse-Proxy betreiben, der TLS terminiert, setzen Sie siteUrl, damit EmDash die richtige Redirect-URI erstellt. Ohne diese Einstellung sehen Anfragen wie http://internal-host:4321 aus, und die Metadaten stimmen nicht mit dem überein, was der Autorisierungsserver sieht.

Fehlerbehebung

”Account is not in the allowlist”

Der Handle oder die DID, mit der Sie sich angemeldet haben, steht nicht in allowedDIDs / allowedHandles. Prüfen Sie das Platzhaltermuster (es muss mit *. beginnen) und denken Sie daran, dass der Handle-Treffer gegen DNS/HTTP verifiziert wird — wenn der DID-Eintrag des Handles aktuell nicht auf dieselbe DID aufgelöst wird, die der Provider zurückgegeben hat, wird der Treffer abgelehnt.

”Self-signup is not allowed”

Sie haben den Callback erfolgreich erreicht, aber es ist keine Allowlist konfiguriert, und Sie sind nicht der erste Benutzer. Fügen Sie die DID des Kontos zu allowedDIDs oder seinen verifizierten Handle zu allowedHandles hinzu. Eine Einladung per E-Mail verknüpft keine Atmosphere-DID mit einem EmDash-Benutzer.

Anmeldung leitet zur Anmeldeseite ohne Fehler weiter

Das ist fast immer das Loopback-Cookie-Problem, das unter Lokale Entwicklung beschrieben wird. Öffnen Sie das Admin unter http://127.0.0.1:4321 (nachdem Sie server.host: "127.0.0.1" gesetzt haben) und versuchen Sie es erneut.

Handle-Auflösung schlägt für einen selbst-gehosteten Handle fehl

Der Provider verifiziert Handles, indem er DNS-over-HTTPS (den DoH-Endpunkt von Cloudflare) und eine HTTP-Abfrage von /.well-known/atproto-did gegeneinander antreten lässt. Selbst gehostete Handles benötigen mindestens eines von beiden:

• Einen DNS-TXT-Eintrag _atproto.<handle> mit dem Inhalt did=<your-did>, oder
• Eine Datei https://<handle>/.well-known/atproto-did, die die DID enthält.

Schlagen beide Methoden fehl, wird der Handle-Treffer abgelehnt, selbst wenn das zugrunde liegende Konto gültig ist. DIDs in allowedDIDs sind davon nicht betroffen — sie werden direkt abgeglichen.