Authentication architecture · 2026 – present

Heimdall

The authentication and authorisation layer above ZITADEL: web sessions, mobile device sessions and machine access in one model.

Back to all projects
Role
Sole developer & architect
Timeframe
2026 – present
Context
Designed and built from scratch on my own
Technologies
NestJSTypeScriptNode.jsPostgreSQLSequelizeZITADELOIDC / PKCEJWT / JWKSDockerPM2Bitbucket Pipelines

Heimdall is the shared authentication and authorisation layer above ZITADEL. It connects three very different trust models — browser, mobile app and service-to-service — through one model for organisations, roles, modules and seats. I designed and built the platform as the sole developer in around four months across 124 commits.

01

Context

The existing products had grown over years. Each product verified SSO tokens and partly managed roles and project grants itself — with different rules for web, mobile and machine communication.

ZITADEL remained the identity provider. Heimdall was to unify the layer above it — sessions, organisations, roles, modules and seats — and make revocation possible in one place.

02

My contribution

  • Set up the NestJS monorepo with three deployable services: bff-web, bff-mobile and m2m-gateway; shared core and features libraries, ten models and eleven migrations.
  • Web login through ZITADEL OIDC with PKCE and state; a server-side cookie session; five guards in a fixed order: JWT, session, organisation, role, permission.
  • Separated home and effective organisation: switching organisation requires a role; permissions are checked per service and role.
  • Mobile login bridge: a 60-second code stored only as a SHA-256 hash and claimable exactly once with an atomic delete; then an opaque device session, also stored only as a hash.
  • Mobile access tokens as 15-minute RS256 JWTs; the private key exists only in bff-mobile, the public key and JWKS in m2m-gateway; a derived key ID keeps several PM2 workers verifiable.
  • M2M access through service identities and endpoint allowlists; session validation for socket handshakes; identity and cookie headers are stripped before the reverse proxy and replaced with verified values.
  • Seats and roles are re-checked when a token is issued; changes revoke app sessions transactionally and release device data on a best-effort basis after the commit.
  • Documented the architecture and turned it into a skill for further development.
03

Architecture & delivery

  • NestJS and TypeScript: bff-web, bff-mobile and m2m-gateway share core and features libraries.
  • ZITADEL remains the identity provider for OIDC, SSO and user management; Heimdall owns the session, organisation, role and seat layer above it.
  • PostgreSQL with ten models and eleven migrations; migrations run in a dedicated one-shot container before the app containers start.
  • Four PM2 workers per service, Docker and blue-green deployment; the JWKS is cached briefly so token verification works across workers and products.
  • Deliberate limits: no cache, no queue, no distributed transaction. Correctness comes from clear ownership, constraints and idempotent flows.
System design Three trust models, one authorisation layer
Clients
Trust boundary
Identity & data
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 Identity Sessions X-User-Id Headers

Web, mobile and service-to-service access run through separate BFFs but share the same guard chain and role/seat context. The proxy strips spoofable identity headers before setting verified values.

Design decisions
  • Three trust models share one authorisation layer.
  • The mobile code is valid for 60 seconds, stored only as a SHA-256 hash and claimed atomically once.
  • The mobile JWT expires after 15 minutes; the private key lives only in bff-mobile, the public key/JWKS in m2m-gateway.

Scroll horizontally to see the full design.

04

The hard parts

01

Three clients, three trust models

A browser needs a different session than a mobile app or a server. Web uses a server-side cookie session, mobile a durable device session plus a 15-minute JWT, and M2M its own service identity. The architecture makes those differences explicit instead of forcing one token for everything.

02

One code, exactly once

Mobile login hands a 60-second code from the browser to the app. Two concurrent exchanges must not both win. A DELETE with RETURNING claims the row atomically; only the SHA-256 hash is stored, never the code itself.

03

Revocation that arrives

Roles and seats are re-checked whenever a token is issued. Changes revoke the app session transactionally; releasing device data in Intervento runs best-effort after the commit. Revocation stays as close as possible to the database without making product availability depend on an external service.

05

Outcome

  • One central layer for sessions, organisations, roles, modules and seats above ZITADEL.
  • Web, mobile and M2M share the same authorisation logic while using credentials and lifetimes suited to each channel.
  • MyEvoSys and Intervento are connected to Heimdall; integration of the remaining products is in progress. Mobile clients receive short-lived JWTs instead of proxy calls.
  • The architecture is documented and can be continued as a skill inside the repository.

Contact

Let's talk about the next role.

I am looking for a position where I can take responsibility for systems and teams as a lead engineer or software architect. Ideally where reliability, data and real-world workflows meet.

Send an email [email protected]

Availability

Region
Thun/Bern
Workload
80%
Work location
On-site, hybrid or remote by arrangement
Travel
Generally yes, scope depending on the role and responsibilities
Start
by agreement