User-engine enterprise identity extension points

Purpose

This document freezes the compatibility seams for later customer-owned directories and identity providers. It does not enable enterprise federation; NK-WP-0011 remains demand-triggered.

Stable ownership boundaries

Concern	Authority
Authentication, MFA, federation protocol, upstream session	KeyCape or Keycloak
Customer directory users and groups	Customer directory
Platform user profile, tenant membership and lifecycle projection	user-engine
Fine-grained authorization decision	flex-auth
Credential and secret custody	NetKingdom/OpenBao
Audit evidence	owning service plus platform audit sink

User-engine must consume verified IAM Profile claims and provider-neutral lifecycle events. It must not store enterprise passwords, MFA factors, SAML assertions, refresh tokens, or directory administrator credentials.

Adapter seams

OIDC and SAML federation

KeyCape/Keycloak terminates OIDC or SAML and emits the same IAM Profile envelope used by local identities. Upstream issuer and subject remain traceable in a private provenance claim while downstream applications trust only the canonical platform issuer.

SCIM provisioning

A future SCIM adapter translates customer create, update, suspend and delete events into idempotent user-engine lifecycle commands. It uses an immutable provider object identifier plus tenant identifier as its key. SCIM transport, bearer credentials and retry queues stay outside the user-engine domain.

JIT provisioning

JIT may create a pending platform projection after a successfully verified login. It must not grant tenant-admin or platform authority solely from an unmapped upstream claim. Privileged mappings require a pre-approved mapping rule or an existing platform-side membership.

Directory group mapping

Mappings are tenant-scoped, versioned and deny ambiguous multi-tenant envelopes. Raw customer group names are never interpreted as platform roles without an explicit mapping. Platform roles and tenant:platform remain reserved.

Conflict and freshness rules

Immutable provider subject identifiers win over mutable email addresses.
Email is a login/display alias, not the cross-system identity key.
Customer-owned attributes are refreshed from the customer source; platform memberships and application preferences remain platform-owned.
Suspension or offboarding from an authoritative customer source fails closed for new sessions and invalidates cached authorization projections.
Duplicate email or provider-subject collisions enter reconciliation; they are never merged automatically.
Events carry provider version/time, correlation ID and idempotency key. Older events cannot overwrite newer state.
A stale connector cannot silently reactivate a suspended identity.

Offboarding and failure behavior

Customer offboarding first blocks authentication, then suspends the user-engine tenant account and emits revocation/audit events. Destructive profile deletion is delayed by retention policy. Provider outage preserves the last known projection but does not bypass authentication, MFA, suspension or freshness limits.

Demand triggers

Enterprise implementation begins only when a named tenant supplies:

protocol and provider choice;
authoritative attribute/group contract;
lifecycle and offboarding SLA;
acceptable freshness window;
tenant-specific role mappings;
test tenant and rollback owner.

Until then, local LLDAP plus KeyCape remains the managed identity path.

Provider reconciliation contract

The local LLDAP adapter establishes the provider-neutral operational pattern that later enterprise adapters must preserve:

drift performs a read-only comparison of desired identity, tenant groups, roles, and lifecycle status;
reconcile converges only adapter-owned attributes and reports every change;
ambiguous email/subject conflicts fail for explicit repair instead of silently relinking an identity;
newly created identities are compensated when initial group projection cannot complete;
deprovisioning is replay-safe, and transient transport failures may be retried only with the caller's required idempotency key.

SCIM and directory-synchronization adapters should implement this same seam instead of adding provider-specific repair behavior to user-engine.

4.3 KiB Raw Blame History