generated from coulomb/repo-seed
97 lines
4.2 KiB
Markdown
97 lines
4.2 KiB
Markdown
# 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.
|