net-kingdom/workplans/NK-WP-0042-workload-mfa-step-up.md

id	type	title	domain	repo	status	flavor	owner	topic_slug	created	updated	related	state_hub_workstream_id
NK-WP-0042	workplan	Let workloads require MFA for all or part of their features	infotech	net-kingdom	finished	planning	claude-code	netkingdom	2026-09-23	2026-10-10	NK-ADR-0016 NK-WP-0037	3f702215-704b-5788-8ca0-b8b9ba2dd3f8

ADR-0016 makes MFA a user preference by default and lets a workload require it for all or some of its features. This workplan defines how a workload states that requirement and how the flow enforces it. It does not require MFA anywhere; the enrollment and recovery usability gate in ADR-0016 still applies first.

Specify the workload-requested step-up contract

id: NK-WP-0042-T01
status: done
priority: medium
state_hub_task_id: "d66a6347-b714-5cca-aeb5-7121328f4dec"

Define how a workload requests AAL2: per client registration for the whole feature set, or per request as a step-up when a protected feature is used. Specify:

• which OIDC parameter the request uses (acr_values, max_age, or both);
• what KeyCape must return when a user has no factor (a clean refusal and an enrollment route, never silent AAL1);
• how the resulting assurance.level reaches flex-auth.

Record it as an IAM Profile amendment. key-cape owns the implementation.

Done 2026-09-27. Drafted as canon/standards/iam-profile_v0.4.md (status proposed, supersedes v0.3, which stays accepted and normative until this is accepted). The new "Workload-Requested Step-Up (proposed)" section specifies acr_values carrying an assurance.level value (aal2/aal3) as the step-up request, max_age as an optional additive freshness request that must never stand in for strength alone, the two conforming no-factor refusal shapes (inline enrollment detour or an explicit error=mfa_required-class refusal, never silent AAL1), and that flex-auth keeps reading the issued assurance.level with no new claim. The exact enrollment/recovery UX is left to T02, which this section names explicitly.

Agree the user-facing step-up and enrollment journey

id: NK-WP-0042-T02
status: cancel
needs_human: false
closure_reason: "Duplicate attended acceptance consolidated into existing USER-WP-0027-T04 and USER-WP-0028-T03; decision cef97ccd remains open there. Demand-deferred workload-requested interoperability retained in residual NET-IN-0003."
priority: medium
state_hub_task_id: "4e51585d-2b57-56d4-84c1-314041d26bcf"

With user-engine (U06, factor recovery) and one pilot workload, agree what a user sees when a feature needs MFA and they have none. That includes the enrollment detour, the return to the feature, and recovery. It must be accepted from a user's perspective before any workload turns the requirement on.

Waiting 2026-09-27. Routed to user-engine via State Hub message 892fd489-113d-4108-8048-727f4b0ed048, referencing the T01 contract and asking for a proposed pilot workload and U06 touchpoints. This is a UX/product agreement across two repos and a pilot workload owner; NetKingdom cannot decide it unilaterally.

2026-10-03: human gate routed to hub decision cef97ccd-4ee7-40fe-859e-1df9c9360ecb (D10: Identity record and MFA: accept NK-ADR-0017, choose the record read surface, agree the MFA user experience) by CUST-WP-0075; resolving that decision raises C-40 here.

2026-10-03 (CUST-WP-0075 inbox sweep): gate re-checked, unchanged. The unread user-engine message of 2026-10-03 (db1b7d6e, USER-WP-0026-T03) was about the workload catalogue/admission and access-decision owner, not this journey; it was answered (reply 19a0cbcd: access-engine owns decisions, grants, revocation and the protected-system registry; the catalogue is the onboarding binding of access-engine protected system, key-cape OIDC client and user-engine application record; NetKingdom only orchestrates). It does not settle T02. Our 2026-09-27 request 892fd489 (pilot workload, U06 touchpoints) is still unread by user-engine, so blocked_on: message-from:user-engine stays real, and the founder's acceptance under decision cef97ccd stays the human gate. The reply reminds user-engine of 892fd489.

2026-10-09: user-engine answered 892fd489 (message a459e8a6), as a proposal; the pilot choice and the AAL2 switch-on stay founder decisions:

• Pilot workload: coulomb-social (the current registration/onboarding client, owner of application action step-up). One non-privileged feature behind acr_values=aal2. Precedent: the user-engine portal's administration step-up ("Verify with MFA" -> /login?recovery=1&return_path=..., P06 recent-MFA guard, deployed).
• Refusal shape: inline enrollment detour at the issuer; factor screens stay on the IdP and user-engine never collects an OTP or reads a seed. Fallback on an mfa_required-class refusal: link to the public user-engine /security page. Return means the workload re-requests with acr_values; a return URL is never proof of enrollment.
• U06 touchpoints reused: /security; My account -> Sign-in security -> provider management (USER_ENGINE_MFA_MANAGEMENT_URL, deliberately unset until attended KEY-WP-0035 self-service checks pass); U07 lost device and U08 replace/remove (replacement verified before removal, no bypass link; P04 operator-assisted recovery); P06 policy preview/rollback so switching on does not lock out unenrolled users.
• Constraint: user-engine's attended real-factor U05-U08 run (USER-WP-0027-T03 / USER-WP-0028-T03) is pending, and route net-kingdom-privacyidea-admin-token is still resolvable: false (railiance-platform). user-engine proposes running the pilot's user-perspective acceptance in that same attended session (enrollment detour -> return -> lost-factor recovery, end to end once).

NetKingdom's reading: the proposal fits the T01 contract (issuer owns factor screens, workload enforces issued assurance, return is not evidence). The message dependency is cleared; T02 stays wait on the founder under decision cef97ccd: choose the pilot, then accept the journey in the combined attended session. Note that coulomb.social fits oidc-browser-relying-party 1.0 only partly (NK-WP-0048 README fit table), so the pilot's KeyCape acr_values handling is checked on its existing registration.

2026-10-09: founder decision, relayed by user-engine (message 60673e40; recorded in user-engine docs/mfa-pilot-decision.md):

1. Pilot workload: coulomb-social.
2. MFA stays in NetKingdom infrastructure: enrollment, verification, replacement, recovery and MFA-required policy live with KeyCape/issuer plus the provider factor and user-engine (/security, P04, P06). coulomb-social stays a plain OIDC relying party with no factor, enrollment, recovery or MFA policy code.
3. MFA is optional for coulomb-social users: password-only stays valid (U05), enrollment is voluntary via U06, and the issuer enforces the factor once a user has enrolled (U07). No acr_values=aal2 switch-on now.
4. Admin-required MFA for coulomb-social users is deferred and not urgent; when wanted, it is an issuer-side client policy applied through the NetKingdom admin surface (P06 preview/apply/rollback), with a separate founder go.

Consequence for this plan: the pilot proves the optional-after-enrollment journey, not workload-requested step-up. The T01 acr_values contract stays valid but unexercised by this pilot. Not settled: decision cef97ccd stays open for user-perspective acceptance, which runs in user-engine's attended U05-U08 session (USER-WP-0027-T04 / USER-WP-0028-T03) with a coulomb-social user. T02 stays wait on that session.

Infrastructure review — 2026-09-28

Build T02 on the already completed USER-WP-0033 and KEY-WP-0035 P06 work. Their September 14 release evidence records optional-after-enrollment policy for user-engine-portal and vergabe-demo-company, privileged MFA guards, confirmed enrollment/cancellation and old-session checks. Do not rebuild those capabilities or interpret this plan as the first delivery of MFA policy.

The residual is workload-level interoperability and an accepted pilot journey: agree the pilot owner, reuse U06 recovery, prove no-factor enrollment and return to the protected action, and test stale AAL1, refusal and provider unavailability. Existing scoped policy does not prove arbitrary-client acr_values support or acceptance of IAM v0.4. KeyCape owns issuer enforcement; user-engine owns the journey; the workload and flex-auth enforce the issued assurance at the protected action. T02 remains wait for that agreement and actual-user acceptance, coordinated with KEY-WP-0034 / USER-WP-0028 / VERGABE-WP-0019, without reopening their completed provider work.

Evidence and cross-plan priorities: estate review.

2026-10-10 — Consolidated planning closure

This planning workplan is finished for its delivered contract proposal and policy/pilot agreement; it does not claim a working arbitrary-client step-up capability or accepted real-user MFA journey. T01 produced proposed IAM v0.4 while v0.3 remains normative. The founder's October 9 decision explicitly selected optional MFA on coulomb-social, issuer/provider-held MFA mechanics and no current acr_values=aal2 switch-on (user-engine/docs/mfa-pilot-decision.md; owner relay 60673e40).

T02's remaining attended acceptance was already owned by live USER-WP-0027-T04 and USER-WP-0028-T03 with the same decision cef97ccd. user-engine/docs/mfa-attended-run.md now specifies the actual U05-U08 run with tegwick, the approved client, the already-live management handoff, the verification and evidence rules. USER-WP-0028 records founder approval of tegwick/coulomb-social and the live handoff reply 7ee2459e on October 10. T02 is cancelled only as a duplicate local acceptance gate: those existing owners and decision remain open until observed acceptance. No MFA or browser check has been marked complete.

Future workload-requested step-up interoperability (no-factor refusal, enrollment return, stale AAL1 and provider outage) remains demand-deferred under NET-IN-0003, origin residual / origin_ref NK-WP-0042, rather than disappearing into closure prose. Do not implement that residual without promotion and a separately approved client policy/rollout.