2026-07-29 23:14:09 +02:00
|
|
|
# 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.
|
2026-07-29 23:41:42 +02:00
|
|
|
|
|
|
|
|
## 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.
|
