net-kingdom/docs/adr/ADR-0006-recursive-multi-tenant-identity-authorization.md

ADR-0006 - Recursive Multi-Tenant Identity and Authorization Architecture

Status: Accepted Date: 2026-05-17 Deciders: Bernd Worsch

Context

The Coulomb platform is being built from the same repositories and services that will later support other use cases. This creates a recursive architecture problem: Coulomb needs to use the shared identity, security, policy, and deployment capabilities, while those capabilities are themselves part of the infrastructure being built.

If this recursion is left implicit, the first internal use case can drift into being treated as the platform root of trust. That would make future multi-tenant use harder, blur operational authority, and make secure bootstrap/recovery decisions harder to reason about.

NetKingdom already owns identity and security architecture concerns. key-cape provides a lightweight IAM implementation of the NetKingdom IAM Profile. Keycloak remains the expanded production IAM option. privacyIDEA is relevant for MFA/token lifecycle. flex-auth is emerging as the canonical authorization control plane and practical reference implementation of CARING authorization semantics. Topaz is the most likely first delegated authorization runtime behind flex-auth.

Decision

We will document and implement the platform security architecture as a recursive multi-tenant architecture with three explicit planes:

• Bootstrap plane - establishes the first trusted runtime and recovery authority before normal platform services exist.
• Platform control plane - operates shared identity, MFA, secrets, authorization, policy, audit, and explanation services.
• Tenant plane - runs Coulomb and future workloads under scoped tenant authority.

Coulomb will be treated as the first internal/reference tenant, not as the platform root of trust.

NetKingdom will own the canonical security architecture and standards. Railiance will own deployment layering and orchestration boundaries. flex-auth will own the canonical authorization interface and CARING-based policy/decision model. Topaz will be the first delegated PDP runtime, with other authorization engines treated as adapters where useful.

Consequences

• Architecture documentation must separate platform-root authority from tenant administration, even for Coulomb.
• Workplans for identity, authorization, and bootstrapping must include explicit tenant and control-plane boundaries.
• Bootstrap design must include trust-state transitions and recovery procedures rather than assuming the final IAM service already exists.
• flex-auth should model tenants, platform resources, CARING descriptors, decision envelopes, and runtime adapters in a provider-neutral way.
• key-cape and Keycloak should be treated as implementations of the IAM Profile, not as the canonical source of resource authorization semantics.
• A future orchestration repo may be useful, but only to coordinate safe sequencing across Railiance and NetKingdom capabilities. It must not bypass Railiance stack ownership.

Alternatives Considered

Treat Coulomb As The Platform Root

This is simpler during early development but creates long-term coupling between one internal use case and the shared platform. It makes later multi-tenant operation and secure bootstrap harder.

Put All Security Semantics Into Keycloak

Keycloak is useful for expanded IAM and can provide authorization features, but making it the canonical model would make lightweight mode and future authorization backends harder to support. The preferred model keeps identity provider concerns separate from canonical authorization semantics.

Create An Orchestration Repo Immediately

A dedicated orchestration repo may become appropriate. Creating it before we define trust states and repo boundaries would risk encoding accidental sequence logic too early. The immediate step is to document the state machine and update workplans.

Follow-Up

• Refine bootstrapping around explicit trust-state transitions.
• Add tenant/control-plane language to flex-auth authorization workplans.
• Define the first production Topaz integration boundary for flex-auth.
• Decide when key-cape is sufficient and when Keycloak expanded mode is required.
• Decide what, if anything, should live in a future orchestration repo.