Auth-Architektur · 2026

Heimdall

Die Authentifizierungs- und Autorisierungsschicht über ZITADEL: Web-Sessions, mobile Geräte-Sessions und Maschinen-Zugriffe in einem Modell.

Zurück zu allen Projekten
Rolle
Sole Developer & Architekt
Zeitraum
2026
Kontext
Von Grund auf allein entworfen und aufgebaut
Technologien
NestJSTypeScriptNode.jsPostgreSQLSequelizeZITADELOIDC / PKCEJWT / JWKSDockerPM2Bitbucket Pipelines

Heimdall ist die gemeinsame Authentifizierungs- und Autorisierungsschicht über ZITADEL. Es verbindet drei sehr unterschiedliche Vertrauensmodelle — Browser, mobile App und Service-zu-Service — mit einem gemeinsamen Modell für Organisationen, Rollen, Module und Sitzplätze. Ich habe die Plattform als alleiniger Entwickler entworfen und in rund vier Monaten in 124 Commits aufgebaut.

01

Ausgangslage

Die bestehenden Produkte waren über Jahre gewachsen. Jedes Produkt prüfte SSO-Tokens und führte Rollen- und Projektfreigaben teilweise selbst — für Web, Mobile und Maschinen-Kommunikation mit unterschiedlichen Regeln.

ZITADEL blieb der Identity Provider. Heimdall sollte darüber die Ebene für Sessions, Organisationen, Rollen, Module und Sitzplätze vereinheitlichen und Widerruf an einer Stelle ermöglichen.

02

Mein Beitrag

  • NestJS-Monorepo mit drei deploybaren Diensten aufgesetzt: bff-web, bff-mobile und m2m-gateway; gemeinsame core- und features-Bibliotheken, zehn Modelle und elf Migrationen.
  • Web-Login über ZITADEL OIDC mit PKCE und State; serverseitige Cookie-Session; fünf Guards in fester Reihenfolge: JWT, Session, Organisation, Rolle, Berechtigung.
  • Heim- und effektive Organisation getrennt: Organisationswechsel nur mit Rolle; Berechtigungen service- und rollenbasiert geprüft.
  • Mobile Login-Bridge: 60-Sekunden-Code, nur als SHA-256-Hash gespeichert und atomar genau einmal einlösbar; danach eine opake Geräte-Session, ebenfalls nur gehasht gespeichert.
  • Mobile Zugriffstoken als 15-Minuten-RS256-JWT; privater Schlüssel nur im bff-mobile, öffentlicher Schlüssel und JWKS im m2m-gateway; abgeleitete Key-ID für mehrere PM2-Worker.
  • M2M-Zugriffe über Service-Identitäten und Endpoint-Allowlists; Session-Validierung für Socket-Handshakes; identitäts- und Cookie-Header werden vor dem Reverse Proxy entfernt und durch geprüfte Werte ersetzt.
  • Sitzplätze und Rollen werden bei der Token-Ausgabe erneut geprüft; Änderungen widerrufen App-Sessions transaktional und geben Gerätedaten nach dem Commit best-effort frei.
  • Architektur dokumentiert und als Skill für die Weiterentwicklung aufbereitet.
03

Architektur & Umsetzung

  • NestJS und TypeScript: bff-web, bff-mobile und m2m-gateway teilen sich core- und features-Bibliotheken.
  • ZITADEL bleibt der Identity Provider für OIDC, SSO und Benutzerverwaltung; Heimdall besitzt die Session-, Organisations-, Rollen- und Sitzplatzebene darüber.
  • PostgreSQL mit zehn Modellen und elf Migrationen; Migrationen laufen als eigener One-Shot-Container vor den App-Containern.
  • Vier PM2-Worker pro Dienst, Docker und Blue-Green-Deployment; das JWKS wird kurz gecacht, damit Token-Prüfung über Worker und Produkte hinweg funktioniert.
  • Bewusste Grenzen: kein Cache, keine Queue, keine verteilte Transaktion. Korrektheit entsteht über klare Zuständigkeiten, Constraints und idempotente Abläufe.
Systementwurf Drei Vertrauensmodelle, eine Autorisierung
Clients
Vertrauensgrenze
Identität & Daten
Vue Web cookie session
Flutter App session → JWT
Services service identity
bff-web OIDC · reverse proxy
bff-mobile 60s code · 15min JWT
m2m-gateway validation · JWKS
Guards JWT → session → org → role → permission
Tenant & seats roles · modules · quotas
Trusted proxy header stripping
ZITADEL OIDC · SSO
PostgreSQL sessions · roles · seats
Products verified identity
OIDC PKCE 60s Code Key Session Identität Sessions X-User-Id Headers

Web, Mobile und Service-zu-Service-Zugriffe laufen über getrennte BFFs, teilen sich aber dieselbe Guard-Kette und denselben Rollen- und Seat-Kontext. Der Proxy entfernt vortäuschbare Identitätsheader, bevor er verifizierte Werte setzt.

Designentscheide
  • Drei Vertrauensmodelle teilen sich eine Autorisierungsschicht.
  • Der Mobile-Code ist 60 Sekunden gültig, wird nur als SHA-256-Hash gespeichert und atomar einmal eingelöst.
  • Das Mobile-JWT läuft nach 15 Minuten ab; der private Schlüssel liegt nur im bff-mobile, der öffentliche Schlüssel/JWKS im m2m-gateway.

Horizontal scrollen, um den ganzen Entwurf zu sehen.

04

Die schwierigen Teile

01

Drei Clients, drei Vertrauensmodelle

Ein Browser braucht eine andere Session als eine mobile App oder ein Server. Web nutzt eine serverseitige Cookie-Session, Mobile eine langlebige Geräte-Session plus 15-Minuten-JWT, M2M eine eigene Service-Identität. Die Architektur macht diese Unterschiede explizit, statt ein Token für alles zu erzwingen.

02

Ein Code, genau einmal

Der mobile Login übergibt einen 60 Sekunden gültigen Code vom Browser an die App. Zwei gleichzeitige Einlösungen dürfen nicht beide gewinnen. Ein DELETE mit RETURNING beansprucht die Zeile atomar; gespeichert wird nur der SHA-256-Hash, nie der Code selbst.

03

Widerruf, der ankommt

Rollen und Sitzplätze werden bei jeder Token-Ausgabe neu geprüft. Änderungen widerrufen die App-Session transaktional; die Freigabe der Gerätedaten in Intervento läuft best-effort nach dem Commit. Der Widerruf bleibt so nah wie möglich an der Datenbank, ohne die Produktverfügbarkeit von einem externen Dienst abhängig zu machen.

05

Resultat

  • Eine zentrale Schicht für Sessions, Organisationen, Rollen, Module und Sitzplätze über ZITADEL.
  • Web, Mobile und M2M nutzen dieselbe Autorisierungslogik, aber jeweils passende Credentials und Laufzeiten.
  • MyEvoSys und Intervento wurden an Heimdall angebunden; mobile Clients erhalten kurzlebige JWTs statt Proxy-Aufrufen.
  • Die Architektur ist dokumentiert und als Skill im Repository weiterführbar.

Kontakt

Lassen Sie uns über die nächste Rolle sprechen.

Ich suche eine Position, in der ich als Tech Lead, Software-Architekt oder Senior Full-Stack Engineer Verantwortung für Systeme und Teams übernehmen kann. Am liebsten dort, wo Zuverlässigkeit, Daten und echte Abläufe zusammentreffen.