Atmosphere Login

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

Dies ist eine gute Lösung, wenn:

• Ihre Mitwirkenden bereits ein Atmosphere-Konto haben.
• Sie eine organisations-kontrollierte Domain (*.yourcompany.com) schützen möchten, ohne OAuth-Apps oder Einladungen zu verwalten.
• Sie etwas entwickeln, das Teil des breiteren Atmosphere ist und eine konsistente Identität mit dem Rest Ihres Stacks haben soll.

Installation

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({
	integrations: [
		emdash({
			authProviders: [atproto()],
			server: {
				host: "127.0.0.1", // required for local dev — see "Local development" below
			},
		}),
	],
});

Das reicht aus, um Mit Atmosphere anmelden auf der Login-Seite und im Einrichtungsassistenten anzuzeigen. Ohne konfigurierte Allowlist wird der erste Benutzer zum Admin und die Selbstregistrierung wird für alle anderen geschlossen — siehe Allowlists, um dies zu öffnen.

Der Provider ist ein öffentlicher OAuth-Client und stellt sein eigenes Metadaten-Dokument unter /.well-known/atproto-client-metadata.json bereit, sodass er allein mit der obigen Konfiguration funktioniert — keine Umgebungsvariablen, Client-Secrets oder OAuth-App-Registrierung erforderlich.

Konfiguration

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

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

Die vollständige Rollenhierarchie ist im Authentifizierungsleitfaden dokumentiert.

Allowlists

Wenn weder allowedDIDs noch allowedHandles gesetzt sind, kann sich nur der erste Benutzer registrieren — alle anderen, die sich anmelden möchten, werden mit signup_not_allowed abgelehnt. Bestehende Benutzer können sich unabhängig von der Allowlist immer wieder anmelden (wenn Sie sich also von der Liste entfernen, werden Sie nicht ausgesperrt, aber es werden auch keine neuen Benutzer zugelassen).

Wenn mindestens eine Allowlist konfiguriert ist, wird ein Benutzer zugelassen, wenn eine der beiden Listen übereinstimmt:

• DID-Übereinstimmung. Die DID des Benutzers ist in allowedDIDs. DIDs sind kryptografische Identifikatoren, die nicht verschoben oder nachgeahmt werden können, daher ist dies die strengste Form der Zugriffskontrolle.
• Handle-Übereinstimmung. Das Handle des Benutzers entspricht einem Eintrag in allowedHandles, entweder exakt oder über ein führendes Wildcard-Muster (*.example.com entspricht alice.example.com und bob.team.example.com).

Handle-Allowlists sind sicher, obwohl Handles veränderbar sind. Bevor ein Benutzer über eine Handle-Übereinstimmung zugelassen wird, löst EmDash unabhängig den DNS/HTTP-Eintrag des Handles auf und überprüft, dass er auf dieselbe DID verweist, die der Provider behauptet. Ein fehlerhafter Provider kann nicht einfach behaupten, dass er you@yourcompany.com besitzt.

Standardrolle

Zugelassene Benutzer landen auf der Rolle, die Sie in defaultRole festgelegt haben. Nur der erste Benutzer — derjenige, der die Einrichtung abschließt — wird zwingend zum Admin. Es gibt kein Gruppen-/Rollen-Mapping für Atmosphere-Konten; wenn Sie feinere Rollen benötigen, ändern Sie die Rolle des Benutzers unter Einstellungen → Benutzer, nachdem er sich einmal angemeldet hat.

Erstbenutzer-Einrichtung

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

Der gleiche Ablauf läuft bei jeder weiteren Anmeldung: Geben Sie Ihr Handle ein, authentifizieren Sie sich bei Ihrem Provider und kehren Sie angemeldet zu EmDash zurück.

Lokale Entwicklung

Das AT Protocol OAuth-Profil erfordert, dass Loopback-Redirect-URIs ein IP-Literal (127.0.0.1 oder [::1]) verwenden, nicht localhost. EmDash schreibt ://localhost transparent zu ://127.0.0.1 um, wenn die Redirect-URI generiert wird, aber das bedeutet, dass Ihre Entwicklungssitzung auch auf 127.0.0.1 starten muss — andernfalls ist das auf localhost gesetzte Session-Cookie nach der Weiterleitung auf 127.0.0.1 nicht sichtbar.

Der Dev-Server von Astro ist der Dev-Server von Vite, und Vite bindet standardmäßig an localhost. Weisen Sie ihn an, auch auf der Loopback-IP zu lauschen:

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

Die gleiche Konfiguration funktioniert in der Produktion. Der Provider stellt seine eigenen Client-Metadaten unter:

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

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

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

Fehlerbehebung

”Account is not in the allowlist”

Das Handle oder die DID, mit dem Sie sich angemeldet haben, ist nicht in allowedDIDs / allowedHandles. Überprüfen Sie das Wildcard-Muster (es muss mit *. beginnen) und denken Sie daran, dass die Handle-Übereinstimmung gegen DNS/HTTP überprüft wird — wenn der DID-Eintrag des Handles derzeit nicht auf dieselbe DID auflöst, die der Provider zurückgegeben hat, wird die Übereinstimmung 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 sich entweder selbst zu allowedDIDs/allowedHandles hinzu oder lassen Sie sich von einem bestehenden Admin einladen, sodass der Benutzer bereits existiert, wenn Sie sich anmelden.

Anmeldung leitet zur Login-Seite ohne Fehler um

Dies ist fast immer das Loopback-Cookie-Problem, das unter Lokale Entwicklung beschrieben wird. Öffnen Sie den 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 bei selbst-gehostetem Handle fehl

Der Provider überprüft Handles durch ein Race zwischen DNS-over-HTTPS (Cloudflares DoH-Endpunkt) und einem HTTP /.well-known/atproto-did-Lookup. Selbst-gehostete Handles benötigen mindestens eines von:

• Einen _atproto.<handle> DNS TXT-Eintrag mit did=<your-did>, oder
• Eine https://<handle>/.well-known/atproto-did-Datei mit der DID.

Wenn beide Methoden fehlschlagen, wird die Handle-Übereinstimmung abgelehnt, auch wenn das zugrunde liegende Konto gültig ist. DIDs in allowedDIDs sind nicht betroffen — sie werden direkt abgeglichen.