Atmosphere-Anmeldung

Das Paket @emdash-cms/auth-atproto fügt EmDash eine Anmeldeoption mit einem Atmosphere-Konto hinzu. Ein Atmosphere-Konto ist eine portable, nutzereigene Identität für Bluesky und andere Apps im AT-Protocol-Netzwerk. Nutzer melden sich mit ihrem Handle (z. B. alice.bsky.social) an 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 organisationskontrollierte Domain (*.ihrefirma.com) absichern möchten, ohne OAuth-Apps oder Einladungen zu verwalten.
• Sie etwas im weiteren Atmosphere-Ökosystem bauen und eine konsistente Identität zum Rest Ihres Stacks wollen.

Installation

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", // für lokale Entwicklung erforderlich — siehe unten „Lokale Entwicklung“
			},
		}),
	],
});

Damit erscheint Mit Atmosphere anmelden auf der Login-Seite und im Setup-Assistenten. Ohne konfigurierte Allowlist wird der erste Nutzer Admin und die Selbstregistrierung ist danach für alle geschlossen — siehe Allowlists, um sie zu öffnen.

Es sind keine Umgebungsvariablen, kein Client-Secret und keine OAuth-App-Registrierung nötig. Der Provider ist ein öffentlicher OAuth-Client und stellt sein eigenes Metadaten-Dokument unter /.well-known/atproto-client-metadata.json bereit.

Konfiguration

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

Die vollständige Rollenleiter ist im zentralen Authentifizierungsleitfaden dokumentiert.

Allowlists

Wenn weder allowedDIDs noch allowedHandles gesetzt sind, kann sich nur der erste Nutzer registrieren — jeder andere Login-Versuch wird mit signup_not_allowed abgelehnt. Bestehende Nutzer können sich jederzeit wieder anmelden, unabhängig von der Allowlist (Sie sperren sich also nicht aus, wenn Sie sich aus der Liste nehmen, aber neue Personen kommen dadurch auch nicht rein).

Ist mindestens eine Allowlist konfiguriert, wird ein Nutzer zugelassen, wenn eine der Listen passt:

• DID-Treffer. Die DID des Nutzers steht in allowedDIDs. DIDs sind kryptografische Identifikatoren, die nicht verschoben oder nachgeahmt werden können — das ist die strengste Form der Zugangsbeschränkung.
• Handle-Treffer. Das Handle des Nutzers passt zu einem Eintrag in allowedHandles, exakt oder über ein führendes Wildcard-Muster (*.example.com passt zu alice.example.com und bob.team.example.com).

Handle-Allowlists sind sicher, obwohl Handles änderbar sind. Bevor EmDash einen Nutzer per Handle zulässt, löst es den DNS-/HTTP-Eintrag des Handles eigenständig auf und prüft, dass er auf dieselbe DID zeigt, die der Provider angibt. Ein missbräuchlicher Provider kann nicht einfach behaupten, er besitze [email protected].

Standardrolle

Zugelassene Nutzer erhalten die in defaultRole gesetzte Rolle. Nur der erste Nutzer — der das Setup abschließt — wird zwangweise Admin. Es gibt keine Gruppen-/Rollenzuordnung für Atmosphere-Konten; für feinere Rollen ändern Sie die Rolle unter Einstellungen → Nutzer, nachdem sich der Nutzer einmal angemeldet hat.

Erster Nutzer (Setup)

Starten Sie eine neue Site mit konfiguriertem Atmosphere-Provider, bietet der Setup-Assistent ihn als Option für das erste Admin-Konto an.

Derselbe Ablauf gilt für jeden weiteren Login — Handle eingeben, Weiterleitung zum Provider, zurück, angemeldet.

Lokale Entwicklung

Das AT-Protocol-OAuth-Profil verlangt, dass Loopback-Redirect-URIs ein IP-Literal (127.0.0.1 oder [::1]) verwenden, nicht localhost. EmDash schreibt ://localhost beim Erzeugen der Redirect-URI transparent zu ://127.0.0.1 um — Ihre Dev-Sitzung muss daher ebenfalls auf 127.0.0.1 starten, sonst ist das auf localhost gesetzte Session-Cookie nach der Weiterleitung auf 127.0.0.1 nicht sichtbar.

Der Dev-Server von Astro ist der von Vite, und Vite bindet standardmäßig an localhost. Konfigurieren Sie zusätzlich das Abhören auf der 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

Für die Produktion ist nichts weiter nötig. Der Provider liefert die Client-Metadaten unter:

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

Authorization-Server rufen diese URL während des Login-Vorgangs ab, um die Redirect-URI des Clients zu prüfen. Stellen Sie sicher, dass die öffentliche Site-URL Ihres Deployments per HTTPS aus dem Internet erreichbar ist — reine interne Deployments hinter einem VPN können keinen Login abschließen, weil der Authorization-Server des Nutzers das Metadaten-Dokument nicht abrufen kann.

Läuft EmDash hinter einem TLS terminierenden Reverse-Proxy, setzen Sie siteUrl, damit EmDash die richtige Redirect-URI erzeugt. Ohne das 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 der Sie angemeldet sind, steht nicht in allowedDIDs / allowedHandles. Prüfen Sie das Wildcard-Muster (muss mit *. beginnen) und bedenken: Der Handle-Abgleich wird per DNS/HTTP verifiziert — stimmt die DID des Handles aktuell nicht mit der vom Provider gelieferten DID überein, 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 Nutzer. Tragen Sie sich in allowedDIDs/allowedHandles ein oder lassen Sie sich von einem bestehenden Admin einladen, sodass der Nutzer beim Login schon existiert.

Login leitet zur Login-Seite weiter, ohne Fehler

Das ist fast immer das Loopback-Cookie-Problem aus Lokale Entwicklung. Öffnen Sie das Admin unter http://127.0.0.1:4321 (nach server.host: "127.0.0.1") und versuchen Sie es erneut.

Handle-Auflösung schlägt bei selbst gehostetem Handle fehl

Der Provider prüft Handles per Wettlauf zwischen DNS-over-HTTPS (Cloudflare DoH) und HTTP-Lookup auf /.well-known/atproto-did. Selbst gehostete Handles brauchen mindestens eines von:

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

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