The NetKingdom IAM Profile is the provider-neutral OIDC contract that
identity implementations issue and applications consume.
It defines:
- OIDC discovery and endpoint requirements;
- Authorization Code + PKCE for human login;
- service-account and workload identity token requirements;
- human, service, and agent principal representation;
- tenant and platform-boundary claims;
- explicit assurance evidence;
- the identity-to-authorization claim contract consumed by flex-auth;
- local-development and emergency-access behavior;
- executable conformance expectations.
Applications target this profile, not a concrete identity provider.
key-cape is the lightweight implementation. Keycloak is the expanded-mode
implementation. Both are interchangeable at the application and
authorization boundary when they conform to this document.
## Ownership
NetKingdom owns the core/platform profile. See ADR-0011.
Downstream systems may define extension scopes, roles, resource names,
and tenant policy vocabularies. Those extensions are not part of the core
profile unless a future version explicitly adopts them. Extension
vocabularies must map back to the core claims in this document before
flex-auth or applications consume them.
## Design Principles
- Consumers trust signed OIDC tokens, not provider-specific sessions.
- Identity providers assert identity and authentication evidence; they do
not make final resource authorization decisions.
- The same profile works in lightweight key-cape mode and expanded
Keycloak mode.
- Tenancy is explicit. `tenant:platform` is distinct from tenant planes
such as `tenant:coulomb`.
- Human, service, and agent principals are distinguishable.
- Assurance evidence is explicit enough for flex-auth policy.
- Local-development issuers are useful but never accepted by production.
- Emergency access is auditable, time-bounded, and reviewable.
## Discovery Contract
Every IAM Profile implementation MUST expose OIDC discovery at:
```text
GET <issuer>/.well-known/openid-configuration
```
The discovery response MUST include:
| Field | Requirement |
| --- | --- |
| `issuer` | Exact issuer identifier used in tokens |
| `authorization_endpoint` | Required for human Authorization Code + PKCE |
| `token_endpoint` | Required for token exchange and service accounts |
| `jwks_uri` | Required for signature validation |
| `userinfo_endpoint` | Required when userinfo is supported by the flow |
| `scopes_supported` | MUST include `openid`; SHOULD include `profile` and `email` |
| `response_types_supported` | MUST include `code` |
| `grant_types_supported` | MUST include `authorization_code`; MUST include `client_credentials` or a documented workload-token exchange for service identities |
| `id_token_signing_alg_values_supported` | MUST include the implementation signing algorithm; RS256 is required for v0.2 conformance |
| `code_challenge_methods_supported` | MUST include `S256` |
The response SHOULD include `end_session_endpoint` where logout is
supported and `claims_supported` listing the core claims below.
Consumers MUST discover endpoints and key material from the issuer
metadata instead of hardcoding provider-specific paths.
## Required Flows
### Human Interactive Flow
Human users authenticate with Authorization Code + PKCE.
Required properties:
- PKCE with `S256` is mandatory for browser and CLI clients.
- Implicit flow is not part of the profile.
- MFA or equivalent strong assurance is mandatory for privileged,
destructive, platform-root, and emergency access in production.
- Access tokens are short-lived.
- Refresh tokens are allowed only for trusted clients with explicit
rotation and revocation.
### Service Account Flow
Service-to-service traffic uses client credentials or a deployment's
