generated from coulomb/repo-seed
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 <noreply@anthropic.com>
This commit is contained in:
198
workplans/NK-WP-0012-iam-profile-specification.md
Normal file
198
workplans/NK-WP-0012-iam-profile-specification.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user