net-kingdom/docs/tutorials/protected-system-flex-auth.md

Add a protected system to flex-auth

Exercise status: unexercised Workplan task: NK-WP-0009-T05 Pattern(s): authorization boundary (docs/platform-identity-security-architecture.md, ADR-0006); IAM Profile v0.3 consumption

Exercise notes: the offline commands in steps 4 and 5 were run once by Claude on 2026-09-28 against the secrets-engine example in a local flex-auth checkout and produced the outcomes listed under Verification. The live caller-authentication steps (6 and 7) have not been run. Nobody has yet completed the whole tutorial, so it stays unexercised.

Outcome

Your system publishes its resources and actions to flex-auth, sends check requests carrying a projected caller identity, enforces the decision it gets back, and is refused when the caller is wrong.

Prerequisites

• [owner: flex-auth] A local checkout of flex-auth with Go, to run go run ./cmd/flex-auth. Read flex-auth/docs/decision-record-contract.md.
• [owner: your system's repo] A system id and a list of the things it protects and the actions it performs on them.
• [owner: railiance-platform / package owner, ADR-0015] A Kubernetes ServiceAccount that will represent your system. Package and runtime declarations belong to the owner, not to this repo.
• [owner: net-kingdom] Accepted IAM Profile v0.3 for the identity you present (canon/standards/iam-profile_v0.3.md).

Architecture context

flex-auth is the policy decision point; your system is the enforcement point. flex-auth never sees secret material, only coordinates (ids, types, attributes). The worked example throughout is secrets-engine (flex-auth/examples/secrets-engine/). Two gates protect a consumer: caller authentication (who is asking) and the policy decision (may they). A consumer running with caller auth in warn mode is not protected.

Steps

1. [owner: your system's repo] Define the resource types and the action vocabulary. Actions are your system's own strings; do not infer them. Copy the shape of flex-auth/examples/secrets-engine/protected_system_manifest.yaml: resource_types (name, scope level, planes) and actions (name, capabilities, planes, exposure modes, required context). Keep a verb that is not a real gate out of the list (revoke is deliberately not an action in the example; the CLI verb gates as deactivate).
2. [owner: your system's repo] Publish resource manifests and, for callers, a subject manifest: one service identity per protected system. Send empty lists rather than omitting or guessing attributes.
3. [owner: flex-auth] Write the policy package (Markdown with Rego) and fixtures covering every allow and every denial branch, including wrong tenant, unknown subject and unknown action.
4. [owner: flex-auth] Validate and load offline: go run ./cmd/flex-auth validate -kind policy -file <policy_package.md> then go run ./cmd/flex-auth load-registry -file <registry_snapshot.json>.
5. [owner: flex-auth] Evaluate a check request locally: go run ./cmd/flex-auth check -registry <registry_snapshot.json> -policy <policy_package.md> -request <request.json>. A request is tenant, subject, action, resource and context. The result is a decision envelope (flex-auth.decision-record.v1) with effect, reason, and a deterministic decision id.
6. [owner: package owner] Give the caller a projected identity: a short-lived, audience-scoped ServiceAccount token, and register the exact binding <system>=system:serviceaccount:<namespace>:<serviceaccount> on the flex-auth pin with audience flex-auth. Send the token as Authorization: Bearer. Use the in-cluster trailing-dot FQDN of the pin, never a bare service name.
7. [owner: flex-auth] Set caller authentication to enforce and run the four negative tests from flex-auth/docs/operator-caller-access-path.md (no header, wrong ServiceAccount, wrong audience, expired token).
8. [owner: your system's repo] Enforce the envelope: allow proceeds; deny blocks; redact and audit_only apply their obligations; any error or missing decision fails closed. Persist the decision id with every deny, redaction, export and privileged action.

Verification

Done when:

• validate and load-registry exit 0 on your package and snapshot.
• Offline check returns allow for a permitted request, and deny with reason wrong_tenant, unknown_subject and unknown_action for the matching negative requests. (Observed on the secrets-engine example: allow / catalog_lane_policy_matched; deny / wrong_tenant; deny / unknown_action for revoke; deny / unknown_subject.)
• Against the live pin under enforce: a valid token returns 200 and an allow; no header returns 401; a token for the wrong ServiceAccount returns 403; a wrong-audience token returns 401; an expired token returns 401. All four negatives must be refused before policy is evaluated.
• A pin whose logs still show warn is reported as not enforcing. That is a failed check, not a pass.

Rollback

• Offline artifacts are files; revert them in git.
• On the live pin, set caller authentication back only as a recorded, time-boxed exception owned by the package owner, and never leave a consumer in warn as the resting state.
• Removing a protected system means removing its binding and manifests; consumers must then fail closed.

Threat checks

• Never send a permanent token; mint short-lived tokens per use.
• Never point a consumer at a bare in-cluster service name; workstation resolvers can answer it with an unrelated host. Use the trailing-dot FQDN.
• A port-forward bypasses NetworkPolicy, so caller authentication is the only gate on an operator path.
• Never put secret values in a resource attribute or a check request.
• Do not give raw upstream group names platform meaning; map them explicitly per tenant.
• Do not apply stale tenant-engine reference YAML; take manifests from the current owner package.

Ownership notes

Concern	Owner
Action vocabulary, resource manifests, enforcement of decisions	the protected system's repo
Policy packages, decision envelope, caller-auth verification	flex-auth
ServiceAccount, package and runtime declaration	package owner under ADR-0015
Identity contract (IAM Profile v0.3)	net-kingdom
Credential routing for the token	ops-warden (pointer only)