From b29d30ff101a4a3fe79cb798710439a8b4798e77 Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 21 May 2026 02:21:59 +0200 Subject: [PATCH] Draft NK-WP-0012: NetKingdom IAM Profile specification Plan to make net-kingdom the canonical owner of the IAM Profile. A v0.1 draft exists in the-custodian canon (all-hubs, Custodian-flavored, Keycloak as reference provider); this workplan relocates ownership and evolves it to a provider-neutral, platform-neutral v0.2 that is tenant- and agent-aware, carries explicit assurance evidence, specifies the claim contract flex-auth consumes, and ships an executable conformance check. Enables NK-WP-0011 (T6 conformance) and depends on NK-WP-0006 (recursive tenant model). Status: proposed; not yet registered in the hub. Co-Authored-By: Claude Opus 4.7 --- .../NK-WP-0012-iam-profile-specification.md | 198 ++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 workplans/NK-WP-0012-iam-profile-specification.md diff --git a/workplans/NK-WP-0012-iam-profile-specification.md b/workplans/NK-WP-0012-iam-profile-specification.md new file mode 100644 index 0000000..cc6bfd7 --- /dev/null +++ b/workplans/NK-WP-0012-iam-profile-specification.md @@ -0,0 +1,198 @@ +--- +id: NK-WP-0012 +type: workplan +title: "NetKingdom IAM Profile Specification" +domain: netkingdom +repo: net-kingdom +status: proposed +owner: worsch +topic_slug: netkingdom +planning_priority: high +planning_order: 12 +created: "2026-05-21" +updated: "2026-05-21" +depends_on: + - NK-WP-0006 +state_hub_workstream_id: TBD +enables: + - NK-WP-0011 +--- + +# NK-WP-0012 — NetKingdom IAM Profile Specification + +> The IAM Profile is referenced everywhere as "the contract all applications +> target," but it does not exist as a net-kingdom artifact. A draft **v0.1 +> exists in the-custodian canon** (`canon/standards/iam-profile_v0.1.md`), +> scoped "all-hubs" and Custodian-flavored. SCOPE.md says net-kingdom owns +> the IAM Profile. This workplan resolves that: net-kingdom becomes the +> canonical owner, and the profile is made provider-neutral, tenant- and +> agent-aware, and conformance-testable. + +## Goal + +Produce the **canonical, versioned NetKingdom IAM Profile** in net-kingdom +canon — the OIDC/PKCE contract every implementation issues and every +application and the authorization layer consume — together with an +**executable conformance check**. + +The profile is the contract that makes the rest of the architecture +coherent: + +- it is what `key-cape` (lightweight) and Keycloak (expanded) each + implement, interchangeably (capability ladder C1/C5); +- it is the identity input `flex-auth` consumes for authorization + decisions (responsibility map: the identity layer owns the claim + contract — that contract is this profile); +- it is the thing **NK-WP-0011-T6** runs conformance checks against, so + this workplan **enables** NK-WP-0011. + +## Why now / what exists + +The v0.1 draft is a strong base — discovery contract, Authorization Code + +PKCE human flow, service-account flow, required claims, token lifecycle, +emergency/break-glass, and a local-development profile. But it has gaps for +the current architecture: + +| Gap in v0.1 | Needed because | +|---|---| +| Lives in the-custodian, scoped "all-hubs" | net-kingdom owns the profile (SCOPE.md, responsibility map) | +| Keycloak named as *the* reference provider | provider-neutral now: key-cape lightweight / Keycloak expanded are interchangeable implementations | +| Scope/role vocabulary is hub-specific (`hub:*`, `ops:*`, `fin:*`) | the core profile must be platform-neutral; hub/app scopes are downstream extensions | +| No tenant claim | recursive `tenant:platform` vs tenant model (NK-WP-0006) needs tenant in the token | +| Only human/service identities | architecture distinguishes human / service / **agent** principals | +| Assurance is implicit | flex-auth decision envelopes require explicit assurance evidence | +| No executable conformance check | NK-WP-0011-T6 and every implementation need a runnable contract test | + +## Scope + +In scope: + +- ownership and reconciliation decision (ADR) with the-custodian v0.1 +- a provider-neutral, platform-neutral **v0.2** profile in net-kingdom canon +- tenant- and agent-aware claims, and explicit assurance evidence +- the identity→authorization claim contract consumed by flex-auth +- an executable conformance check +- versioning and breaking-change governance for the profile +- migration of downstream references to the canonical net-kingdom spec + +Out of scope: + +- implementing the profile in key-cape or Keycloak (their repos own that) +- defining tenant- or application-specific scope vocabularies +- deploying any identity provider + +## Tasks + +```task +id: NK-WP-0012-T1 +status: todo +priority: high +``` + +**Ownership & reconciliation decision (ADR-0011).** Record that net-kingdom +is the canonical owner of the IAM Profile. Decide how the-custodian's +all-hubs v0.1 reconciles: net-kingdom owns the **core/platform profile**; +hub- and app-specific scope vocabularies (`hub:*`, `ops:*`, `fin:*`) become +**downstream extensions** that map back to the core, not part of it. Define +the profile's **versioning and breaking-change governance** (what a +breaking change is, how downstream is notified, how versions coexist). + +```task +id: NK-WP-0012-T2 +status: todo +priority: high +``` + +**Author IAM Profile v0.2 (provider-neutral core).** Create +`canon/standards/iam-profile_v0.2.md` in net-kingdom. Carry forward the +solid v0.1 material — discovery contract, Authorization Code + PKCE human +flow, service-account flow, required/recommended claims, token lifecycle, +emergency/break-glass, local-development profile — and make it +**provider-neutral**: key-cape (lightweight) and Keycloak (expanded) are +named as interchangeable implementations, neither as "the" reference. +Remove hub-specific vocabulary from the core. + +```task +id: NK-WP-0012-T3 +status: todo +priority: high +``` + +**Extend for the recursive and agent model.** Add a **tenant** claim +(`tenant:platform` vs tenant id), formalize the **human / service / agent** +principal types and how each is represented, and define an explicit +**assurance evidence** claim (how authentication strength / MFA is conveyed +in the token). Align with NK-WP-0006 and the responsibility map. + +```task +id: NK-WP-0012-T4 +status: todo +priority: high +``` + +**Define the identity→authorization claim contract.** Specify exactly which +claims the profile guarantees as inputs to flex-auth decision envelopes — +subject, issuer, audience, tenant, groups, roles, scopes, assurance — so +flex-auth treats the profile as normative input and never re-derives +identity. This is the contract named in the responsibility map. + +```task +id: NK-WP-0012-T5 +status: todo +priority: high +``` + +**Executable conformance check.** Build a runnable suite that validates an +issuer/implementation against the profile: discovery document completeness, +PKCE enforcement, claim shape, JWKS and key-rotation tolerance, token +validation (issuer/audience/expiry/signature), and rejection of +local-development issuers in production. This is the artifact NK-WP-0011-T6 +consumes; it must run against both a key-cape and a Keycloak issuer. + +```task +id: NK-WP-0012-T6 +status: todo +priority: medium +``` + +**Migration & cross-references.** Supersede or relink the-custodian v0.1 +(deprecation note pointing at the net-kingdom canonical spec), and update +downstream references — `key-cape` and `flex-auth` interface docs, +NK-WP-0011, and any architecture docs — to cite the canonical net-kingdom +profile. Per ADR-0010, downstream **intents** are not touched; only +interface/reference docs. + +## Acceptance Criteria + +- The canonical IAM Profile lives in net-kingdom canon, versioned, and an + ADR records ownership and the reconciliation with the-custodian v0.1. +- The core profile is provider-neutral and platform-neutral (no + hub-specific scopes in the core; no single "reference provider"). +- The profile carries tenant, principal-type (human/service/agent), and + assurance claims, aligned with the recursive model. +- The claims flex-auth consumes are specified as a normative contract. +- An executable conformance check exists and passes against both a + key-cape and a Keycloak issuer. +- Versioning and breaking-change governance is documented. +- Downstream reference docs point at the canonical spec; the custodian v0.1 + carries a deprecation/relocation note. + +## Dependencies & Sequencing + +- **Depends on NK-WP-0006** for the recursive tenant model the claims encode. +- **Enables NK-WP-0011** — T6 (IAM Profile conformance) cannot pass without + the spec and the conformance check from this workplan. NK-WP-0012 should + land before NK-WP-0011-T6. +- Coordinates with **flex-auth** (the consumed claim contract, T4) and with + **key-cape**/**Keycloak** as the implementations the conformance check + runs against — those repos implement, this workplan specifies and tests. + +## Open Questions + +- Canonical role claim: `roles` vs `realm_access.roles`, or adapter + normalization of both (carried over from v0.1). +- Audience granularity: audience-per-service vs audience-per-endpoint. +- How agent principals differ from service accounts in claims and assurance + (delegated-authority agents vs plain workloads). +- Whether the conformance check is a standalone tool in net-kingdom or a + shared library other repos import.