net-kingdom/workplans/NK-WP-0012-iam-profile-specification.md

id: NK-WP-0012 type: workplan title: "NetKingdom IAM Profile Specification" domain: infotech repo: net-kingdom status: finished owner: worsch topic_slug: netkingdom planning_priority: high planning_order: 12 created: "2026-05-21" updated: "2026-05-22" depends_on: - NK-WP-0006 state_hub_workstream_id: 9b8e4afc-eb71-47d9-8750-799a082b320a 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 state_hub_task_id: 284dda38-b778-445a-a7dc-9b5a12fa380f status: done 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 state_hub_task_id: 0070398d-b0a4-4c11-a6fa-000166e1108f status: done 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 state_hub_task_id: 6fc2a5e1-1480-42f1-86a2-3e714359e1ba status: done 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 state_hub_task_id: 0e52ed45-afa7-4832-9d6a-1ebbbab43872 status: done 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 state_hub_task_id: f0a62e77-b781-4625-b8bd-d191b48af58e status: done 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 state_hub_task_id: a1fd53a9-526f-4d87-89db-6073710c885d status: done 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. ## Completion Notes - ADR: docs/adr/ADR-0011-iam-profile-ownership-and-version-governance.md - Canonical profile: canon/standards/iam-profile_v0.2.md - Executable conformance suite: tools/iam-profile-conformance/iam_profile_conformance.py - Fixture tests cover key-cape-like and Keycloak-like issuers, local-dev rejection in production mode, tenant claim enforcement, provider-native role normalization warnings, and delegated-agent claim shape. - Cross-repo reference docs updated without touching downstream INTENT.md: key-cape README/spec references now point at v0.2, and flex-auth consumption docs plus claim fixtures now include v0.2 tenant, principal, and assurance inputs. ## 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. ## Resolved Questions - Canonical role claim: roles is canonical. realm_access.roles is a transitional/provider-native source that must be mapped before production consumption. - Audience granularity: the core profile requires the receiving service in aud; endpoint/resource granularity belongs to flex-auth resource/action policy. - Agent principals differ from service accounts through principal_type: agent, an agent object, and delegated actor context (actor_sub or act.sub) when applicable. - The conformance check is a standalone tool in net-kingdom for v0.2. Other repos consume it as an executable contract rather than importing a shared library for now.