Zum Inhalt

Anmeldung und SSO-Modus

Anmeldung

Im Standardmodus hat Haben genau einen Inhaber und auf Wunsch Zugänge mit der Rolle Steuerberatung, die nur lesen (Zugang für die Steuerberatung). Früher hatte Haben genau einen Nutzer; diese Entscheidung ist mit dem Zugang für die Steuerberatung aufgegeben, im SSO-Modus sind mehrere Inhaber möglich.

Haben hat zwei strikt getrennte Betriebsarten, umgeschaltet nur über OIDC_ONLY: den Standardmodus mit lokaler Anmeldung (dieser Abschnitt) und den SSO-Modus mit Rollen aus OIDC-Gruppen (SSO-Modus). Im Standardmodus legt die Ersteinrichtung (/setup) den Inhaber mit E-Mail und Passwort an (mindestens 12 Zeichen). Dafür braucht es den Einrichtungscode, den der Server beim Start ins Log schreibt (server/setup-code.ts, oder fest aus HABEN_SETUP_CODE); ein Hook vor /sign-up/email prüft ihn. So kann niemand, der eine neue Instanz zuerst erreicht, das Konto an sich reißen. Jedes weitere Konto entsteht nur mit einer Einladung (server/anmeldung.ts):

  • Der Inhaber erzeugt unter Einstellungen › Sicherheit einen Link /einladung/<token>. Das Token sind 32 zufällige Bytes; gespeichert ist nur sein SHA-256 in invitations, mit Rolle und Frist (72 Stunden).
  • Die Seite schickt das Token beim Anlegen im Header x-haben-einladung mit. Der Hook vor /sign-up/email prüft, dass die Einladung noch gilt, sonst verlangt er wie bisher den Einrichtungscode. Der Datenbank-Hook user.create.before löst die Einladung atomar ein (UPDATE … WHERE nicht eingelöst, nicht zurückgezogen, nicht abgelaufen) und setzt die Rolle aus ihr; ohne Einladung entsteht ein Konto nur, solange es noch keines gibt, dann als Inhaber. Zwei gleichzeitige Anmeldungen mit demselben Link: nur eine bekommt die Zeile.
  • Rolle und Sperre sind additionalFields von Better Auth mit input: false; die Anfrage kann sie nicht setzen. Die Spalte role ist die lokale Rolle; sie hat weiterhin die Vorgabe steuerberatung und bleibt bei Konten leer, die nur per SSO entstanden sind. Der partielle eindeutige Index user_inhaber_single (er ersetzt user_single) hält genau einen lokalen Inhaber auch bei zwei gleichzeitigen Einrichtungen, ein CHECK auf invitations lässt nur Einladungen für die Steuerberatung zu, und ein Trigger lehnt gewöhnliche Rollenänderungen ab; die ausdrückliche Offline-Vorbereitung des lokalen Inhabers ist der eng begrenzte, auditierte Ausnahmeweg. Den Endpunkt update-user von Better Auth lehnt der before-Hook für alle ab: Name und Bild änderten sich dort ohne Audit-Akteur und an der Rollenprüfung vorbei.
  • Der Hook session.create.before gibt einem gesperrten Konto keine Sitzung, auch nicht per Passkey; Sperren löscht zusätzlich die laufenden Sitzungen. session.create.after schreibt jede Anmeldung mit Rolle und Art nach user_logins.

Im Standardmodus meldet man sich per Passkey an, das Passwort bleibt Rückfallebene. Better Auth begrenzt Anfragen je Client-Adresse und Pfad: Passwort, Registrierung, Passwortwechsel und den Start der SSO-Anmeldung (/sign-in/*, /sign-up/*, /change-password) mit seiner Standardregel auf 3 in 10 Sekunden, alle übrigen, auch die Passkey-Anmeldung, auf 20 je Minute (rateLimit in server/auth.ts). Es liest die Client-Adresse hinter Caddy aus X-Forwarded-For.

Beim Passwortwechsel speichert Haben den neuen Hash, widerruft alle Sitzungen des Kontos und legt in derselben Transaktion ein Ereignis in password_changes ab. Die Tabelle hält Konto-ID und Zeitpunkt fest und lässt nur neue Einträge zu. Der Audit-Trigger übernimmt das Ereignis mit dem Akteur ins Änderungsprotokoll.

Geschützt wird an vier Stellen:

  • Die Layout-Route _app leitet ohne Sitzung auf /login bzw. vor der Einrichtung auf /setup um, die Steuerberatung von jeder Seite außer ihren eigenen (steuerberatungSieht in src/lib/rollen.ts) auf /steuerberatung. Die Navigation zeigt ihr nur diese Seiten, Knöpfe zum Ändern fehlen. Das ist Bequemlichkeit, kein Schutz.
  • Jede Server Function mit Daten hängt genau eine von zwei Middlewares an (apps/web/src/server/middleware.ts): authMiddleware lässt nur den Inhaber durch und ist die Vorgabe; readMiddleware lässt auch die Steuerberatung durch und steht nur an lesenden GET-Funktionen. Beide lesen die Sitzung über sessionUser (server/rollen.ts), das gesperrte Konten und unbekannte Rollen als nicht angemeldet behandelt, und legen das Konto mit Rolle in den Kontext. Abgelehnt wird mit 403. Eine neue Server Function ist also ohne Zutun nur für den Inhaber.
  • Für die Steuerberatung läuft der Handler zusätzlich in runReadOnly (server/db/actor.ts, AsyncLocalStorage): withActor lehnt dort jede Transaktion ab. Rutscht in eine lesende Funktion doch ein Schreibvorgang mit Audit-Eintrag, schreibt er für die Steuerberatung nichts. Aufräumen beim Lesen (ein nach einem Neustart hängender Beleg auf „läuft“) lässt getDocument dann aus.
  • Jede API-Route mit Sitzung prüft den Zugriff und antwortet sonst mit 401 bzw. 403: Routen nur für den Inhaber rufen requireUser(request, "inhaber") (server/rollen.ts), Routen, die auch die Steuerberatung abruft (Dateien und Exporte), stehen in lesend (server/lese-route.ts). lesend lässt Handler und Body für die Steuerberatung in runReadOnly laufen wie die Middleware; ein Schreibversuch im Handler ergibt 403, einer im gestreamten Body (Jahresarchiv) bricht den Download ab. Damit der Rahmen auch beim Streamen gilt, erzeugt eine Hülle jeden Teil des Bodys darin; der Body der Steuerberatung kommt deshalb immer gestreamt, ohne Content-Length. Der Inhaber läuft ohne Rahmen: Der DATEV-Export schreibt neue Personenkonten nur für ihn fest und lehnt für die Steuerberatung ab, bevor er schreibt. Fehlen die Firmendaten, legt loadCompany sie beim Lesen an; für die Steuerberatung lehnt der Rahmen das ab (403), bei Server Functions wie bei Routen. Ausnahmen mit eigenem Token statt Sitzung sind das Kalender-Abo, /api/mcp und die REST-API unter /api/v1; deren Tokens legt nur der Inhaber an.

rollen.test.ts liest alle Server Functions und API-Routen aus dem Quelltext und bricht ab, wenn eine POST-Funktion nicht authMiddleware nimmt, eine Funktion mit readMiddleware nicht GET ist oder nicht in der geprüften Liste steht, eine Route die Sitzung an der Rollenprüfung vorbei liest, eine Route der Steuerberatung nicht lesend nimmt (sondern „lesen“ selbst prüft oder den Rahmen selbst setzt) oder die Liste der Routen für die Steuerberatung sich ändert; requireUser nimmt nur noch „inhaber“, das prüft auch der Typ. Wer der Steuerberatung etwas Neues zeigen will, ergänzt die Liste dort bewusst. zugang.test.ts prüft gegen Postgres Einladung, Rollen, Middleware und Routen zum Lesen für beide Rollen, Sperren und Audit; lese-route.test.ts den Rahmen beim gestreamten Body.

Dazu kommt ein Schutz vor Anfragen fremder Seiten (CSRF): Das Sitzungscookie ist SameSite=Lax, und createCsrfMiddleware in start.ts lehnt jede schreibende Anfrage (alles außer GET, HEAD, OPTIONS) ab, deren Sec-Fetch-Site nicht same-origin ist oder deren Origin bzw. Referer nicht zu BETTER_AUTH_URL passt (server/csrf.ts). Das hält auch Seiten auf Nachbar-Subdomains derselben Domain ab. /api/mcp und das Teilen-Ziel /api/belege/teilen prüfen selbst. /api/v1/… ist ausgenommen, weil die REST-API das Sitzungscookie gar nicht liest, nur das Token im Header; eine fremde Seite erbt dort also keine Rechte.

KI-Assistenten melden sich an /api/mcp nicht mit der Sitzung an, sondern mit einem API-Token oder dem Access-Token einer OAuth-Verbindung (Connector, server/modules/mcp/oauth.ts) als Bearer-Header (siehe KI-Assistenten). routes/api/mcp.ts reicht jede Anfrage an handleMcpRequest (server/modules/mcp/) weiter. Der Endpunkt ist zustandslos (Streamable HTTP mit JSON-Antworten, nur POST): authenticateMcp prüft das Token gegen den SHA-256 in mcp_tokens und ob der Zugang eingeschaltet ist, dann beantwortet ein frischer McpServer die Anfrage mit den Werkzeugen, die die Rechte des Tokens erlauben. Die Werkzeuge (tools.ts) rufen nur die index.ts der Module auf und lesen nur. Jeder Aufruf landet ohne Inhalte in mcp_calls. Alles hinter authenticateMcp kennt nur den Zugang mit seinen Rechten, nicht die Art der Anmeldung.

Die REST-API unter /api/v1 (REST-API) nimmt dieselben Tokens. routes/api/v1/$.ts reicht jede Anfrage an handleApiRequest (server/modules/api/). Welche Endpunkte es gibt, steht in einer Tabelle (routes.ts): Methode, Pfad, nötiges Recht, Handler und was die Beschreibung über sie sagt. Der Router ordnet den Pfad zu, prüft Token (authenticateMcp), Rate (dasselbe Fenster wie MCP) und Recht (hasScope, schreiben schließt lesen ein), liest den JSON-Body und ruft den Handler; jeder Aufruf landet ohne Inhalte in mcp_calls, Änderungen stehen mit dem Akteur api:<Token-ID>:<Name des Tokens> im Audit-Log. Der Name allein ist nicht eindeutig (frei wählbar, nach Widerruf und Neuanlage oft gleich); die ID (UUID aus mcp_tokens, feste Länge, vorn) macht den Akteur eindeutig und führt im selben Audit-Log über token_events zu Anlage, Verantwortlichem und Widerruf des Tokens. Einträge von vor dieser Änderung tragen api:<Name des Tokens> und bleiben so, denn das Audit-Log ist eine Hash-Kette. Die Handler prüfen die Eingabe zuerst mit einem strengen Schema der API (unbekannte Felder sind ein Fehler), dann mit dem Schema der Oberfläche (contactSchema, draftSchema) samt deren Vorgaben, und rufen die index.ts von stammdaten und rechnungen. Festschreiben, Buchen und Versand bietet die API nicht an. Die OpenAPI-3.1-Beschreibung unter /api/v1/openapi.json entsteht beim ersten Abruf aus der Tabelle und den Zod-Schemas (z.toJSONSchema, JSON Schema 2020-12); die Tests prüfen die Antworten gegen dieselben Schemas.

Die externe Referenz eines Entwurfs (invoices.external_source, external_id) macht das Anlegen idempotent: createDraftForReference liefert eine vorhandene Rechnung mit derselben Referenz, und kommen zwei Anfragen gleichzeitig, fängt der eindeutige Index invoices_external_ref die zweite ab, die dann die erste liefert. Die beiden Spalten sind gewöhnliche Spalten der versiegelten Tabelle: Das Siegel einer ab jetzt festgeschriebenen Rechnung schließt sie ein (es nimmt beim Festschreiben alle Spalten), ältere Siegel behalten ihre Spaltenliste und bleiben gültig.

Belege aus der API (POST /api/v1/belege, multipart/form-data mit eigener Grenze je Endpunkt statt der 1 MB für JSON) gehen durch uploadDocument wie ein Upload in Haben: dieselbe Prüfung der Datei (documentFileProblem), Ablage unter dem SHA-256, E-Rechnung lesen oder KI-Auslesung im Hintergrund, Status neu. Die Referenz (documents.external_source, external_id) wird nur beim Anlegen gesetzt. uploadDocument sucht zuerst nach ihr, dann nach dem Hash; fängt der eindeutige Index documents_external_ref eine gleichzeitige Anfrage ab, gilt der Beleg der anderen. Ob ein vorhandener Beleg zur Anfrage passt (gleiche oder keine Referenz: 200, sonst 409), entscheidet der Handler. Wie bei Rechnungen sind die Spalten gewöhnliche Spalten der versiegelten Tabelle: Ein ab jetzt gebuchter Beleg schließt sie in sein Siegel ein, der Trigger documents_locked sperrt sie mit dem Beleg; Siegel älterer Belege bleiben gültig.

SSO-Modus

Token-Verantwortung ist von der interaktiven Sitzungsfrist getrennt. Eine geprüfte Herabstufung oder ein Gruppenentzug deaktiviert API-/MCP- und Kalender-Tokens des Verantwortlichen in derselben Transaktion wie die negative Rollenentscheidung. Ohne erneuten OIDC-Durchlauf gilt ein Token höchstens 30 Tage nach der letzten Bestätigung des Verantwortlichen (currentTokenOwners in server/token-responsibility.ts); dieselbe Prüfung lässt nach einem Moduswechsel keine Tokens eines Kontos ohne Identität in der neuen Betriebsart gelten. Deaktivierung erhält das Geheimnis; nur ein anderer berechtigter Inhaber (bei eigenen Tokens auch der einzige Inhaber) kann ausdrücklich übernehmen. Ein gemeinsamer Advisory-Lock je Konto serialisiert Entzug, Anlage und Übernahme. Ältere Rollenentscheidungen dürfen neuere Nachweise nicht überschreiben.

Der Offline-Rückweg verwendet den exklusiven Anwendungs-Lock und einen eng begrenzten Datenbankpfad für die lokale Inhaberrolle. Gewöhnliche Rollenänderungen bleiben gesperrt. Konto-ID und SSO-Zuordnungen bleiben erhalten; fehlende lokale Credentials entstehen ausschließlich durch ausdrückliche Betreiberaktion. Token-Verwaltung wird ohne Geheimnisse in token_events, die lokale Vorbereitung in local_owner_recoveries auditiert. Jeder Schritt im Leben eines API-Tokens und des Kalender-Abos schreibt dort über withActor ein Ereignis mit dem auslösenden Konto: angelegt, widerrufen, deaktiviert (Akteur system:oidc) und reaktiviert. Ein Widerruf ändert nur ein noch nicht widerrufenes Token und schreibt deshalb höchstens ein Ereignis.

Mit OIDC_ONLY=true meldet man sich ausschließlich über einen OIDC-Anbieter an (Better Auth genericOAuth, Provider-ID oidc, Referenz Authelia); ohne diesen Schalter ist OIDC vollständig aus, auch wenn Anbieterwerte gesetzt sind. Der gemeinsame before-Hook (server/sso-policy.ts, enforceMode) sperrt in jeder Betriebsart die Endpunkte der anderen, auch bei internen auth.api-Aufrufen; im SSO-Modus sind E-Mail/Passwort abgeschaltet und das Passkey-Plugin nicht geladen, im Standardmodus ist der Anbieter nicht registriert. Verknüpfen und Entfernen von Identitäten gibt es in keiner Betriebsart, ebenso keine Token-Endpunkte.

Callback. Authorization Code Flow mit PKCE S256, browsergebundenem state (in der Datenbank), Nonce und ID-Token-Prüfung gegen die JWKS der Discovery; deren Issuer muss exakt OIDC_ISSUER sein. Der beim Start gesetzte serverseitige OAuth-State nennt den Issuer; ein vor einem Moduswechsel oder für einen anderen Issuer begonnener Vorgang wird verworfen. Nach dem geprüften ID-Token fragt server/oidc.ts UserInfo ab, wenn der Anbieter diesen Endpunkt nennt; das Subject muss exakt übereinstimmen (OIDC Core 5.3.2). Ein fehlender Gruppenclaim darf aus dem geprüften ID-Token ergänzt werden, ein vorhandener ungültiger Claim niemals. server/sso-groups.ts entscheidet die Rolle: Der Claim aus OIDC_GROUPS_CLAIM muss ein Array aus Zeichenketten sein, verglichen wird exakt; genau eine der beiden Haben-Gruppen gibt die Rolle, keine, beide, ein fehlender oder ungültiger Claim verweigern. Identitäten sind [issuer, sub] in account.account_id (partieller eindeutiger Index); Konten werden nie über gleiche E-Mail zusammengeführt (account_not_linked → Hinweis auf die Übernahme), Profilclaims ändern weder Namen noch Rechte bestehender Konten.

Atomar. server/auth-transaction.ts führt den Schreibteil des Callbacks in einer PostgreSQL-Transaktion aus. Sie beginnt erst nach dem geprüften UserInfo (beginCallbackWrites), sodass Code-Tausch und UserInfo keine Datenbankverbindung belegen; das Löschen des States liegt davor und bleibt auch nach einem Rollback bestehen. Ein AsyncLocalStorage bindet Drizzle-Adapter und Hooks an die Verbindung, auch Fehler-Redirects rollen zurück. In ihr entstehen Einrichtung (sso_issuers, beim ersten Callback eines Inhabers je Issuer), Konto (ohne lokale Rolle), Identität, bestätigte Rolle (sso_roles) und Sitzung gemeinsam oder gar nicht (server/sso-callback.ts). Vor der Einrichtung lehnt Haben die Steuerberatung ab. Ändert sich die Rolle, löscht dieselbe Transaktion alle bisherigen Sitzungen des Kontos. Wird eine bekannte Identität nach vollständig geprüftem ID-Token und UserInfo wegen ihrer Gruppen abgewiesen, widerruft eine eigene Transaktion nach dem Rollback ihre SSO-Sitzungen und setzt die Rolle in sso_roles auf leer; der Fehler-Redirect nimmt das nicht zurück. Ungeprüfte Antworten (Signatur, Nonce, State, Subject) ändern nichts.

Wirksame Rolle. Die Sitzung trägt oidc_issuer, sso_role, sso_checked_at und sso_expires_at, gesetzt nur im Callback (input: false). sso_expires_at liegt 15 Minuten nach der Prüfung, unabhängig von der Laufzeit der nach dem Callback verworfenen Tokens; der Sitzungsrefresh von Better Auth ändert nur expires_at. effectiveRole in server/sso-policy.ts liefert im Standardmodus die lokale Rolle einer lokalen Sitzung eines ungesperrten Kontos, im SSO-Modus nur sso_role einer Sitzung dieses Issuers vor Fristablauf; lokale Rolle und Sperre zählen dort nicht. sessionUser (server/rollen.ts) nimmt sie für Navigation, Server Functions, API-Routen und Audit; native Better-Auth-Endpunkte löschen eine Sitzung, die nicht gilt. Nach Fristablauf führt die Oberfläche zur Anmeldeseite, ohne automatischen Neustart des Flusses. Tokens speichert Haben nicht (Account-Create und -Update entfernen sie), einen Hintergrundrefresh gibt es nicht.

Moduswechsel. Beim Start (server/sso-mode.ts, Plugin setup-code.ts) löscht Haben die Sitzungen der anderen Betriebsart und bricht den Standardmodus ab, wenn es Konten, aber keinen ungesperrten lokalen Inhaber mit Passwort oder Passkey gibt. Gespeicherte lokale Zugangsdaten und Einladungen bleiben erhalten. Bestehende Konten ordnet nur der Betreiber zu: src/server/db/sso-uebernahme.ts (eigenständig, auch im Betriebs-Image) prüft oder übernimmt bei gestoppter Anwendung, erkennbar am Advisory Lock, den die laufende App geteilt hält; nur zum konfigurierten Issuer, nur für ein freies Subject, mit Eintrag in sso_takeovers, ohne Rolle. Mit --ersetzen tritt ein neues Subject an die Stelle der bisherigen Identität dieses Issuers; Sitzungen und bestätigte Rolle enden, replaced_subject hält das alte fest.

Tabellen. sso_issuers und sso_takeovers sind nur anhängbar, sso_roles hält je Konto und Issuer die zuletzt bestätigte Rolle; alle drei haben Audit-Trigger. Anmeldungen stehen mit wirksamer Rolle und Art sso in user_logins. Konfiguration und Authelia-Beispiel: Single Sign-on mit OpenID Connect.

Letztes Update: