generated from coulomb/repo-seed
Implement NK-WP-0012 IAM profile specification
This commit is contained in:
@@ -0,0 +1,127 @@
|
||||
# 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.
|
||||
@@ -184,6 +184,11 @@ TTL policy:
|
||||
|
||||
## IAM Profile Requirements
|
||||
|
||||
The canonical token contract is NetKingdom IAM Profile v0.2
|
||||
(`canon/standards/iam-profile_v0.2.md`). The vending service consumes the
|
||||
profile as normalized identity input and sends resource-specific
|
||||
authorization questions to flex-auth.
|
||||
|
||||
Accepted issuers:
|
||||
|
||||
- key-cape lightweight mode for local, sandbox, and small deployments;
|
||||
@@ -198,10 +203,9 @@ Required token properties:
|
||||
exchange audience;
|
||||
- `sub` is stable for the principal;
|
||||
- `exp`, `nbf`, and `iat` are present and within skew tolerance;
|
||||
- `tenant` or equivalent tenant mapping is present for tenant-scoped
|
||||
requests;
|
||||
- service accounts and agents are distinguishable from humans;
|
||||
- assurance/MFA claims are present when policy needs them;
|
||||
- `tenant` is present for every request;
|
||||
- `principal_type` distinguishes humans, service accounts, and agents;
|
||||
- `assurance` is present, including MFA evidence where policy needs it;
|
||||
- groups or roles are mapped through IAM Profile semantics, not
|
||||
provider-specific bucket policy.
|
||||
|
||||
|
||||
@@ -124,6 +124,12 @@ key-cape is the lightweight profile implementation. Keycloak is the
|
||||
expanded-mode profile implementation. privacyIDEA provides MFA/token
|
||||
capabilities where the deployment mode uses it.
|
||||
|
||||
The canonical profile is NetKingdom IAM Profile v0.2
|
||||
(`canon/standards/iam-profile_v0.2.md`). It requires explicit `tenant`,
|
||||
`principal_type`, `groups`, `roles`, `scope`/`scp`, and `assurance`
|
||||
claims so flex-auth receives normalized identity input regardless of
|
||||
whether key-cape or Keycloak issued the token.
|
||||
|
||||
The choice between lightweight and expanded mode is **capability-driven,
|
||||
not scale-driven**. key-cape comfortably serves large internal user
|
||||
populations; expanded-mode Keycloak is introduced when a *capability* is
|
||||
@@ -333,9 +339,12 @@ Required implications:
|
||||
- Policy packages must distinguish `tenant:platform` policy from
|
||||
tenant-local packages such as `tenant:coulomb`.
|
||||
- Decision envelopes must carry subject, issuer, audience, tenant,
|
||||
protected-system id, resource, action, requested TTL where relevant,
|
||||
assurance evidence, obligations, deny reasons, and audit correlation
|
||||
ids.
|
||||
principal type, groups, roles, scopes, protected-system id, resource,
|
||||
action, requested TTL where relevant, assurance evidence, obligations,
|
||||
deny reasons, and audit correlation ids. Subject, issuer, audience,
|
||||
tenant, principal type, groups, roles, scopes, and assurance come from
|
||||
the IAM Profile v0.2 token contract rather than provider-specific
|
||||
session state.
|
||||
- Topaz is a delegated PDP runtime behind flex-auth. It must not become
|
||||
the canonical policy model, identity provider, or platform control
|
||||
plane.
|
||||
@@ -428,7 +437,7 @@ an explicit check:
|
||||
|
||||
| Area | Readiness check |
|
||||
| --- | --- |
|
||||
| MFA and identity | key-cape or Keycloak issues IAM Profile-compatible tokens; privacyIDEA or the selected MFA provider enforces required assurance for privileged actions |
|
||||
| MFA and identity | key-cape or Keycloak issues IAM Profile v0.2-compatible tokens and passes `tools/iam-profile-conformance/`; privacyIDEA or the selected MFA provider enforces required assurance for privileged actions |
|
||||
| Bootstrap and recovery | age/SOPS material, emergency bundle, and break-glass credentials are present, tested, and separated from tenant administration |
|
||||
| OpenBao runtime secrets | OpenBao is initialized, unsealed or auto-unsealed by the approved mechanism, backed up, audited, and using scoped auth methods and mounts |
|
||||
| Secret rotation | service, database, OpenBao-issued, and break-glass rotation paths have documented blast radius and verification steps |
|
||||
@@ -449,9 +458,7 @@ an explicit check:
|
||||
or via CSI-mounted secrets?
|
||||
- Which tenant metadata is required before a service can register
|
||||
resources with flex-auth?
|
||||
- When does the platform switch from key-cape lightweight mode to
|
||||
Keycloak expanded mode? (Answered as capability-driven — see Capability
|
||||
Progression, tier C5. The remaining open part is the precise per-tenant
|
||||
trigger and dual-issuer coexistence rule, owned by NK-WP-0011-T1.)
|
||||
- What precise per-tenant trigger and dual-issuer coexistence rule should
|
||||
NK-WP-0011-T1 use for Keycloak expanded mode?
|
||||
- Does Topaz run centrally for the platform, per tenant, or per service
|
||||
for the first production deployment?
|
||||
|
||||
@@ -77,8 +77,8 @@ and what NetKingdom is responsible for (meta-orchestration).
|
||||
| | |
|
||||
| --- | --- |
|
||||
| **Resources held** | users, groups, sessions, MFA tokens, OIDC clients, the directory |
|
||||
| **Repo owns** | the lightweight IAM implementation conforming to the IAM Profile |
|
||||
| **NetKingdom orchestrates** | the IAM Profile contract it must conform to; which identity/2FA capabilities are enabled (capability ladder C1–C2); user/group/role and OIDC-client provisioning policy; assurance requirements; identity-trust readiness and profile conformance |
|
||||
| **Repo owns** | the lightweight IAM implementation conforming to the NetKingdom IAM Profile v0.2 |
|
||||
| **NetKingdom orchestrates** | the IAM Profile contract in `canon/standards/iam-profile_v0.2.md`; which identity/2FA capabilities are enabled (capability ladder C1–C2); user/group/role and OIDC-client provisioning policy; tenant and assurance requirements; identity-trust readiness and profile conformance |
|
||||
|
||||
### `flex-auth` — authorization
|
||||
|
||||
@@ -86,7 +86,7 @@ and what NetKingdom is responsible for (meta-orchestration).
|
||||
| --- | --- |
|
||||
| **Resources held** | roles, scopes, policies, protected-system registrations, resource/action vocabulary, decision/audit records |
|
||||
| **Repo owns** | the authorization registry, control plane, and PDP adapters |
|
||||
| **NetKingdom orchestrates** | the decision-envelope contract; platform vs tenant policy boundaries; which protected systems/resources are registered; policy-package import and governance; audit retention; authorization-trust readiness |
|
||||
| **NetKingdom orchestrates** | the decision-envelope contract fed by IAM Profile v0.2 claims; platform vs tenant policy boundaries; which protected systems/resources are registered; policy-package import and governance; audit retention; authorization-trust readiness |
|
||||
|
||||
---
|
||||
|
||||
@@ -95,7 +95,8 @@ and what NetKingdom is responsible for (meta-orchestration).
|
||||
Across the orchestrated repos, NetKingdom is responsible for the coherent,
|
||||
cross-landscape management of:
|
||||
|
||||
- **Identities** — humans, service accounts, agents, groups, tenants
|
||||
- **Identities** — humans, service accounts, agents, groups, tenants,
|
||||
and assurance evidence as normalized by the IAM Profile
|
||||
- **Roles, scopes, and policies** — coarse claims through fine-grained
|
||||
authorization
|
||||
- **Secrets and credentials** — bootstrap material and runtime secret
|
||||
|
||||
Reference in New Issue
Block a user