Authentifizierung

EmDash nutzt Passkey-Authentifizierung als primäre Anmeldemethode. Passkeys sind phishingresistent, erfordern keine Passwörter und funktionieren geräteübergreifend über Browser oder Passwort-Manager.

Bei Cloudflare-Deployments können Sie optional Cloudflare Access als alternative Authentifizierung nutzen.

Funktionsweise

Passkeys basieren auf WebAuthn, einem Webstandard, der öffentliche Schlüssel auf Ihrem Gerät erzeugt oder über den Passwort-Manager synchronisiert. Beim Login weist Ihr Gerät den Besitz des Credentials nach, ohne jemals ein Passwort über das Netzwerk zu senden.

Vorteile der Passkey-Authentifizierung:

• Keine Passwörter zum Merken oder Leaken
• Phishingresistent — Credentials sind an die Domain Ihrer Site gebunden
• Geräteübergreifende Synchronisation — funktioniert mit iCloud-Schlüsselbund, Google Password Manager, 1Password usw.
• Schneller Login — ein Tippen mit Biometrie oder PIN

Erster Benutzer (Setup)

Beim ersten Zugriff auf das Admin-Panel führt Sie der Setup-Assistent durch die Erstellung Ihres Admin-Kontos.

Anmeldung

Nach dem Setup löst erneuter Zugriff auf das Admin-Panel die Passkey-Authentifizierung aus:

Magic-Link-Fallback

Wenn Sie Ihren Passkey nicht nutzen können (z. B. verlorenes Gerät), bieten Magic Links eine Alternative. Dafür muss E-Mail konfiguriert sein.

OAuth-Login

EmDash unterstützt OAuth-Login mit GitHub und Google, sofern konfiguriert. Nutzer können Konten nach dem ersten Passkey-Setup verknüpfen.

Siehe den Configuration guide für Einrichtungshinweise.

Benutzerrollen

EmDash nutzt rollenbasierte Zugriffskontrolle mit fünf Stufen:

Jede Rolle erbt Berechtigungen aller niedrigeren Stufen. Der erste Benutzer wird immer als Admin angelegt.

Benutzer einladen

Admins können neue Benutzer über das Admin-Panel einladen:

Einladungen sind 7 Tage gültig. Admins können Einladungen auf der Seite „Users“ erneut senden oder widerrufen.

Passkeys verwalten

Nutzer verwalten ihre Passkeys in den Kontoeinstellungen:

• Add passkey — zusätzliche Passkeys für Backup oder andere Geräte registrieren
• Remove passkey — Passkeys löschen, die Sie nicht mehr nutzen
• Rename passkey — Passkeys aussagekräftig benennen

Pro Nutzer sind bis zu 10 Passkeys möglich.

Self-Signup

Für Team-Sites können Sie Self-Signup für bestimmte E-Mail-Domains aktivieren:

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";

export default defineConfig({
	integrations: [
		emdash({
			auth: {
				selfSignup: {
					domains: ["example.com"],
					defaultRole: "contributor",
				},
			},
		}),
	],
});

Nutzer mit passender E-Mail-Domain können sich ohne Einladung registrieren. Sie erhalten eine Verifizierungs-E-Mail und schließen die Registrierung mit Passkey ab.

Session-Konfiguration

Sessions nutzen sichere HttpOnly-Cookies mit sinnvollen Standardwerten:

emdash({
	auth: {
		session: {
			maxAge: 30 * 24 * 60 * 60, // 30 days (default)
			sliding: true, // Reset expiry on activity
		},
	},
});

Sicherheitshinweise

• Passkeys werden als öffentliche Schlüssel gespeichert — der private Schlüssel verlässt Ihr Gerät nicht
• Challenge-Verifizierung verhindert Replay-Angriffe
• Rate Limiting schützt vor Brute Force (5 Versuche/Minute/IP)
• Sessions sind HttpOnly, Secure, SameSite=Lax für Cookie-Sicherheit
• Magic-Link-Tokens werden mit SHA-256 gehasht — Roh-Tokens werden nicht gespeichert

Fehlerbehebung

”No passkeys registered”

Wenn dieser Fehler beim Login erscheint, wurde Ihr Passkey möglicherweise im Passwort-Manager gelöscht. Bitten Sie einen Admin um einen Magic Link oder eine neue Einladung.

”Passkey authentication failed”

Meist wurde der Passkey für eine andere Domain erstellt. Passkeys sind domaingebunden — ein Passkey für localhost:4321 funktioniert nicht auf example.com. Registrieren Sie pro Domain einen neuen Passkey.

”Session expired”

Sessions sind standardmäßig 30 Tage mit Sliding Expiration gültig. Wenn Sie unerwartet abgemeldet werden, löschen Sie Cookies und melden Sie sich erneut an.

Alle Passkeys verloren

Wenn Sie keinen Zugriff mehr auf alle registrierten Passkeys haben:

1. Bitten Sie einen anderen Admin um einen Magic Link (E-Mail muss konfiguriert sein)
2. Melden Sie sich mit dem Magic Link an
3. Registrieren Sie in den Kontoeinstellungen einen neuen Passkey

Wenn Sie der einzige Admin sind und E-Mail nicht konfiguriert ist, müssen Sie die Authentifizierung der Site über die Datenbank zurücksetzen.

Cloudflare Access

Bei Deployment auf Cloudflare können Sie Cloudflare Access als Authentifizierungsanbieter statt Passkeys nutzen. Access authentifiziert am Edge über Ihren bestehenden Identity Provider.

Warum Cloudflare Access?

• Single Sign-On — Nutzer authentifizieren sich über den IdP Ihres Unternehmens
• Zentralisierte Zugriffskontrolle — Verwaltung im Cloudflare-Dashboard, wer das Admin erreichen darf
• Kein Passkey-Management — keine Registrierung oder Verwaltung von Passkeys nötig
• Gruppenbasierte Rollen — IdP-Gruppen automatisch auf EmDash-Rollen abbilden

Einrichtung

1. Legen Sie eine Cloudflare Access application für Ihre EmDash-Site an
2. Notieren Sie den Application Audience (AUD) Tag in den Anwendungseinstellungen
3. Konfigurieren Sie EmDash für Access:

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
import emdash from "emdash/astro";
import { d1, access } from "@emdash-cms/cloudflare";

export default defineConfig({
	output: "server",
	adapter: cloudflare(),
	integrations: [
		emdash({
			database: d1({ binding: "DB" }),
			auth: access({
				teamDomain: "myteam.cloudflareaccess.com",
				audience: "abc123def456...", // From Access app settings
			}),
		}),
	],
});

Konfigurationsoptionen

Rollen-Mapping

Ordnen Sie IdP-Gruppen EmDash-Rollen zu:

emdash({
	auth: access({
		teamDomain: "myteam.cloudflareaccess.com",
		audience: "abc123...",
		roleMapping: {
			Admins: 50, // Admin
			"Content Editors": 40, // Editor
			Writers: 30, // Author
		},
		defaultRole: 20, // Contributor for users not in any group
	}),
});

Die erste passende Gruppe gewinnt, wenn ein Nutzer mehreren Gruppen angehört. Der erste Nutzer, der die Site aufruft, wird immer Admin — unabhängig von Gruppen.

Rollen-Sync-Verhalten

Standardmäßig (syncRoles: false) wird die Rolle beim ersten Login gesetzt und danach nicht mehr geändert. So können Admins Rollen manuell in EmDash anpassen.

Setzen Sie syncRoles: true, wenn IdP-Gruppen maßgeblich sein sollen — die Rolle aktualisiert sich bei jedem Login entsprechend den aktuellen Gruppen.

Funktionsweise

1. Nutzer besucht /_emdash/admin
2. Cloudflare Access fängt ab und leitet zum IdP um
3. Nutzer authentifiziert sich (SSO, MFA usw.)
4. Access setzt ein signiertes JWT in der Anfrage
5. EmDash validiert das JWT und erstellt/authentifiziert den Nutzer

Deaktivierte Funktionen

Wenn Access aktiv ist, stehen nicht zur Verfügung:

• Login-Seite (/_emdash/admin/login)
• Passkey-Registrierung und -Verwaltung
• OAuth-Login
• Magic-Link-Login
• Self-Signup
• Nutzereinladungen

Nutzer-Verwaltung erfolgt vollständig über Ihre Cloudflare Access-Policies.

Fehlerbehebung

”No Access JWT present”

Die Anfrage erreichte EmDash ohne Access-JWT. Das bedeutet:

• Access schützt die Anwendung nicht
• Die Access-Policy trifft nicht auf die Admin-Routen zu

Prüfen Sie, dass Ihre Access-Anwendung /_emdash/admin/* abdeckt.

”JWT audience mismatch”

Die audience in Ihrer Konfiguration passt nicht zum JWT. Prüfen Sie den Application Audience Tag in den Access-Einstellungen.

”User not authorized”

Der Nutzer hat sich über Access authentifiziert, aber autoProvision ist false und er existiert nicht in EmDash. Entweder:

• autoProvision: true setzen, oder
• den Nutzer manuell vor dem Login anlegen