Atmosphere-Anmeldung

Das Paket @emdash-cms/auth-atproto fügt eine Atmosphere-Konto-Anmeldeoption zu EmDash hinzu. Ein Atmosphere-Konto ist eine portable, benutzereigene 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 nie ein Passwort.

Dies ist eine gute Wahl, wenn:

• Ihre Mitwirkenden bereits ein Atmosphere-Konto haben.
• Sie eine org-kontrollierte Domain (*.ihrfirma.com) sperren möchten, ohne OAuth-Apps oder Einladungen zu verwalten.
• Sie etwas bauen, das Teil der breiteren Atmosphere ist und konsistente Identität mit dem Rest Ihres Stacks wollen.

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", // erforderlich für lokale Entwicklung; siehe unten
	},
	integrations: [
		emdash({
			authProviders: [atproto()],
		}),
	],
});

Das reicht aus, um Sign in with Atmosphere auf der Anmeldeseite und dem Setup-Assistenten zu platzieren. Ohne konfigurierte Allowlist wird der erste Benutzer Admin und die Selbstregistrierung wird danach für alle geschlossen — siehe Allowlists zum Ö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, kein Client-Secret und keine OAuth-App-Registrierung nötig.

Zugang konfigurieren

Der atproto()-Provider akzeptiert eine Allowlist und eine Standard-Rolle:

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

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

Allowlists

Wenn weder allowedDIDs noch allowedHandles gesetzt ist, 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.

Wenn mindestens eine Allowlist konfiguriert ist, muss jede Anmeldung mit ihr übereinstimmen, einschließlich Anmeldungen für bestehende Benutzer. Das Entfernen der DID und des Handles eines bestehenden Benutzers aus den konfigurierten Listen verhindert, dass dieses Konto sich anmeldet. Ein Benutzer wird zugelassen, wenn eine der Listen übereinstimmt:

• DID-Übereinstimmung. Der stabile Kontoidentifikator des Benutzers stimmt genau mit einem Wert in allowedDIDs überein.
• Handle-Übereinstimmung. Der Handle des Benutzers stimmt mit einem Eintrag in allowedHandles überein, exakt oder über ein führendes Wildcard-Muster (*.example.com stimmt mit alice.example.com und bob.team.example.com überein).

Handle-Allowlists sind sicher, obwohl Handles ä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 zeigt, die der Provider behauptet. Ein sich fehlverhaltender Provider kann nicht einfach behaupten, dass er sie.ihrfirma.com besitzt.

Standard-Rolle

Erlaubte Benutzer landen auf der Rolle, die Sie in defaultRole festlegen. Nur der erste Benutzer — derjenige, der das Setup abschließt — wird auf Admin gesetzt. Es gibt keine Gruppen-/Rollen-Zuordnung 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.

Ersten Benutzer einrichten

Wenn Sie eine neue Website mit dem Atmosphere-Provider starten, bietet der Setup-Assistent diese Option zum Erstellen des ersten Admin-Kontos an.

Spätere Anmeldungen beginnen mit dem Handle, gehen beim Kontoprovider weiter 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 und der Provider seine eigene Sitzung aktualisieren kann.

Lokale Entwicklung

Das OAuth-Profil des AT-Protokolls 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 Dev-Sitzung auch auf 127.0.0.1 starten muss — andernfalls ist das auf localhost gesetzte Session-Cookie nach dem Redirect auf 127.0.0.1 nicht sichtbar.

Astros Dev-Server verwendet Vite, das standardmäßig an localhost bindet. Setzen Sie Astros server.host-Option 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 Flow.

Produktion

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

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

Autorisierungsserver rufen diese URL während der Anmeldung ab, um die Redirect-URI des Clients zu verifizieren. Stellen Sie sicher, dass die Site-URL Ihres Deployments über HTTPS im öffentlichen Internet erreichbar ist — rein interne Deployments hinter einem VPN können keine Anmeldung abschließen, weil 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”

Der Handle oder die DID, mit der Sie sich angemeldet haben, ist nicht in allowedDIDs / allowedHandles. Prüfen Sie das Wildcard-Muster (es muss mit *. beginnen) und beachten Sie, dass die Handle-Übereinstimmung gegen DNS/HTTP verifiziert 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 keine Allowlist ist 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 E-Mail-Einladung verknüpft keine Atmosphere-DID mit einem EmDash-Benutzer.

Anmeldung leitet zur Anmeldeseite ohne Fehler weiter

Dies 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 durch paralleles DNS-über-HTTPS (Cloudflares DoH-Endpoint) und einen HTTP-/.well-known/atproto-did-Lookup. Selbst-gehostete Handles benötigen mindestens eines von:

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

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