generated from coulomb/repo-seed
128 lines
5.3 KiB
Markdown
128 lines
5.3 KiB
Markdown
# ADR-0011 - NetKingdom IAM Profile Ownership And Version Governance
|
|
|
|
**Status:** Accepted
|
|
**Date:** 2026-05-22
|
|
**Deciders:** Bernd Worsch, Codex
|
|
|
|
## Context
|
|
|
|
The IAM Profile is the identity contract that applications, flex-auth,
|
|
key-cape, Keycloak, and bootstrap identity tooling all target. It defines
|
|
the OIDC discovery, flow, token, claim, assurance, tenant, and conformance
|
|
requirements that make lightweight and expanded identity modes
|
|
interchangeable at the application boundary.
|
|
|
|
A draft IAM Profile v0.1 existed in the-custodian canon with an
|
|
all-hubs scope. That draft captured useful material: OIDC discovery,
|
|
Authorization Code + PKCE, service-account tokens, required claims,
|
|
token lifecycle, emergency access, and local-development behavior.
|
|
However, NetKingdom now owns the platform identity domain. SCOPE.md names
|
|
the NetKingdom IAM Profile as an in-scope, versioned standard, and
|
|
ADR-0006 requires key-cape and Keycloak to be implementations of the
|
|
profile rather than the canonical source of authorization semantics.
|
|
|
|
The v0.1 draft also used hub-specific scope and role vocabulary. That
|
|
made sense for the Custodian hub landscape, but the core NetKingdom
|
|
profile must be platform-neutral so it can serve tenant, service,
|
|
application, and agent use cases without encoding one downstream system's
|
|
scope names.
|
|
|
|
## Decision
|
|
|
|
NetKingdom is the canonical owner of the IAM Profile.
|
|
|
|
The profile is versioned under `canon/standards/` in this repository. The
|
|
first canonical NetKingdom version is
|
|
`canon/standards/iam-profile_v0.2.md`.
|
|
|
|
The relationship to the earlier the-custodian draft is:
|
|
|
|
- the-custodian IAM Profile v0.1 is superseded as a core/platform
|
|
standard;
|
|
- NetKingdom owns the provider-neutral core profile;
|
|
- downstream systems may define hub-, tenant-, or application-specific
|
|
scopes and roles as extensions, but those extensions must map back to
|
|
the core identity and authorization input contract;
|
|
- key-cape lightweight mode and Keycloak expanded mode are
|
|
interchangeable implementations of the same profile;
|
|
- flex-auth consumes the profile as normative identity input and must not
|
|
re-derive identity facts from provider-specific state.
|
|
|
|
## Versioning
|
|
|
|
The IAM Profile uses explicit document versions:
|
|
|
|
- Patch/editorial changes clarify wording, examples, or non-normative
|
|
guidance without changing the token contract.
|
|
- Minor versions add optional claims, optional flows, or additional
|
|
conformance checks that existing implementations can pass unchanged.
|
|
- Major or breaking versions change required claims, claim meanings,
|
|
validation rules, flow requirements, assurance semantics, tenant
|
|
semantics, or token acceptance rules.
|
|
|
|
Every versioned profile file remains immutable enough for downstream
|
|
references to cite. New versions are added as new files rather than
|
|
rewriting historical versions in place, except for clearly editorial
|
|
fixes that do not affect semantics.
|
|
|
|
## Breaking-Change Governance
|
|
|
|
A breaking profile change requires:
|
|
|
|
1. a new ADR or ADR refinement that explains the change and migration
|
|
path;
|
|
2. a new versioned profile document;
|
|
3. an update to the executable conformance suite;
|
|
4. a coexistence window that lets at least one previous supported profile
|
|
version and the new version be accepted where practical;
|
|
5. notification in workplans or interface docs for known consumers,
|
|
especially key-cape, Keycloak/expanded-mode work, flex-auth, and
|
|
application integration docs.
|
|
|
|
Breaking changes include:
|
|
|
|
- removing or renaming a required claim;
|
|
- changing the meaning, type, or allowed values of required claims such
|
|
as `tenant`, `principal_type`, `roles`, `groups`, `scope`/`scp`, or
|
|
`assurance`;
|
|
- changing accepted issuer, audience, or signing validation rules;
|
|
- weakening PKCE, MFA/assurance, local-development rejection, or
|
|
emergency-access requirements;
|
|
- moving authorization decisions into an identity provider instead of
|
|
flex-auth.
|
|
|
|
## Consequences
|
|
|
|
- `canon/standards/iam-profile_v0.2.md` is the canonical profile.
|
|
- the-custodian's v0.1 draft should carry a relocation/deprecation note
|
|
pointing to this repository.
|
|
- Hub-specific scopes such as `hub:*`, `ops:*`, and `fin:*` are
|
|
downstream extensions, not core profile vocabulary.
|
|
- key-cape and Keycloak must emit or normalize to the same claim contract
|
|
before applications and flex-auth consume tokens.
|
|
- The conformance suite in `tools/iam-profile-conformance/` is the
|
|
executable contract for implementations.
|
|
|
|
## Alternatives Considered
|
|
|
|
### Keep The Custodian Draft As Canonical
|
|
|
|
The draft is useful, but keeping ownership there would conflict with
|
|
NetKingdom's repository scope and with ADR-0006's responsibility split.
|
|
It would also leave the profile coupled to Custodian hub vocabulary.
|
|
|
|
### Make Keycloak The Reference Provider
|
|
|
|
Keycloak is the expanded-mode implementation and remains important for
|
|
enterprise federation. Making it the reference provider would make
|
|
lightweight mode, local bootstrap, and future identity adapters secondary
|
|
to one implementation. The accepted model keeps providers
|
|
interchangeable behind the profile.
|
|
|
|
### Put Scope And Role Vocabulary In The Core Profile
|
|
|
|
A shared vocabulary is useful, but core identity must stay stable across
|
|
applications and tenants. Downstream systems can define extension scopes
|
|
and roles as long as they map to the core claim shapes and flex-auth
|
|
decision inputs.
|