flex-auth/docs/iam-profile-consumption.md

NetKingdom IAM Profile — flex-auth Consumption Surface

Date: 2026-05-16 Status: Draft for FLEX-WP-0005 P5.5; binds the input contract for the standalone evaluator (FLEX-WP-0002) and every PDP adapter (FLEX-WP-0004). Upstream: ~/the-custodian/canon/standards/iam-profile_v0.1.md.

Boundary

The NetKingdom IAM Profile defines the OIDC contract shared across hubs and services. flex-auth consumes verified claims; it does not verify token signatures, fetch JWKS, or terminate OIDC sessions. Those responsibilities belong upstream:

• key-cape (lightweight mode) validates tokens against its local OIDC provider and emits claims that conform to the profile.
• Keycloak (heavy mode) signs tokens; integration code (e.g. Markitect's NetKingdomIdentityClaimsAdapter) validates issuer, audience, signature, expiry, and clock skew before handing claims to flex-auth.

A flex-auth deployment that exposes a network endpoint MUST be fronted by an identity layer that does the verification. The flex-auth core accepts a normalized claim envelope and is responsible for everything after "this caller is authenticated".

Input Envelope

flex-auth's standalone evaluator and adapters consume a normalized envelope identical to Markitect's EnterpriseIdentity shape:

issuer: <oidc issuer URL>          # required
subject: <stable subject id>       # required
principal_type: human | service | emergency
audience: [<aud>, ...]             # required, non-empty
authorized_party: <azp or client_id, optional>
preferred_username: <string>       # required for humans
roles: [<role>, ...]               # required, non-empty
scopes: [<scope>, ...]             # required, non-empty
groups: [<group>, ...]             # optional; resolved by directory layer
assurance:
  acr: <oidc acr value, optional>
  amr: [<oidc amr value>, ...]     # e.g. pwd, otp, mfa, hwk
  mfa: <bool — derived from amr>
directory:
  groups_claim_present: <bool>
  group_overage: <bool>            # Microsoft Entra-style group overage
claims: { ... }                    # full original claim map (minus 'groups')
provenance:
  source: claims | jwt | jwt-fixture
  verified_signature: <bool>

This is the envelope every check API call receives, regardless of which upstream identity provider produced the token.

Required Claims (per IAM Profile §"Required Claims")

flex-auth treats the following as hard requirements. Missing any produces a validation_error before the request reaches a policy package.

Claim	flex-auth field	Notes
iss	issuer	Must match the deployment's expected issuer; production rejects local-dev issuers (localhost, 127.0.0.1, .local, dev.local).
sub	subject	Stable identifier; not a username.
aud	audience	Must include the flex-auth instance or the protected system.
exp	(validated upstream)	flex-auth tolerates ≤60s clock skew per profile §"Token Lifecycle".
iat	(validated upstream)	Same.
scope or scp	scopes	At least one scope required. Empty scope is a hard fail.
preferred_username	preferred_username	Required for principal_type=human. Optional for service accounts.
roles or realm_access.roles or resource_access.<client>.roles	roles	Union of all three sources. At least one role required.

Recommended Claims

Claim	flex-auth field	Use
email	claims.email	Contact identity; never used for authorization decisions.
name	claims.name	Display only.
groups	groups (after resolution)	Authorization input; subject to freshness/overage.
azp	authorized_party	Distinguishes service-account client from impersonating client.
acr	assurance.acr	Authentication context class; gates high-trust scopes.
amr	assurance.amr	Authentication methods; otp/mfa/hwk lift assurance.mfa to true.

Tolerated Variations

flex-auth normalizes — protected systems never see the variation.

• Role claim location. Three OIDC providers ship roles in three places: top-level roles, Keycloak's realm_access.roles, and Keycloak's per-client resource_access.<client>.roles. flex-auth unions all three.
• Scope encoding. scope (space-separated string) and scp (array) both accepted; both produce the same scopes array.
• Audience encoding. aud as a single string or as an array; flex-auth always normalizes to an array.
• MFA signal. Either an explicit mfa: true claim or any of otp/mfa/hwk in amr produces assurance.mfa = true.

Principal-Type Detection

flex-auth classifies the principal by:

1. If client_id is set and service is in roles → service.
2. If azp starts with svc- or service is in roles → service.
3. If emergency is in roles → emergency.
4. Otherwise → human.

This matches Markitect's NetKingdomIdentityClaimsAdapter._principal_type and follows IAM Profile §"Hub-to-Hub Service Account Pattern" (service accounts named svc-* and carrying the service role).

Group Overage and Freshness

Microsoft Entra and Keycloak both clip the groups claim once a threshold is reached; the token then carries hasgroups: true (Entra) or _claim_names.groups (also Entra). flex-auth's directory layer is responsible for resolving the full set via Graph/SCIM/Keycloak admin API; the claim envelope carries directory.group_overage = true so policy packages can decide whether to fail-closed or accept the partial set with an audit_only outcome.

Group freshness is tracked at the directory-resolver layer (out of scope for this document; see FLEX-WP-0004 T05).

Production vs Local Development

Per IAM Profile §"Local Development Profile":

• Local-development issuers (localhost, 127.0.0.1, hostnames ending in .local, dev.local) are rejected when environment=production is set in the request context.
• A development token marked clearly through issuer/audience is accepted in non-production environments.
• The local-development path exists to keep flex-auth useful before Keycloak is wired in; it never weakens production rules.

Emergency Principals

Per IAM Profile §"Human Override and Emergency Access":

• emergency is a first-class principal_type.
• Every decision involving an emergency principal MUST record a record_emergency obligation in the decision envelope.
• Policy packages MAY allow emergency principals; flex-auth's audit layer ensures the action is durable regardless.

Reference Implementation

Markitect's NetKingdomIdentityClaimsAdapter (at markitect-tool/src/markitect_tool/policy/enterprise.py) implements the validation steps above in Python. flex-auth's Go implementation (FLEX-WP-0002 P2.4) mirrors its behavior and stays in sync via contract tests against the fixtures in examples/claims/.

Open Items

• Whether roles becomes canonical and realm_access.roles becomes legacy is still listed as an open question in IAM Profile v0.1. As of 2026-05-16 flex-auth normalizes both with no preference.
• Workload identity (Kubernetes service-account tokens, GCP/AWS workload-identity federation) is not yet in the IAM Profile. flex-auth's service-account handling is currently OIDC-only.