net-kingdom/docs/adr/ADR-0011-iam-profile-ownership-and-version-governance.md

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.