Reconciliation Engine

Expected vs Actual access, drift detection, and per-system policies.

Expected vs Actual — the central duality

The reconciliation engine compares two states for each identity on each system:

Actual — what is in the target right now. This comes from the most recent sync.
Expected — what should be there according to the governance model: access grant policy matches (birthright, including bare-account grants), approved access requests, role-based assignments, and explicit keeps. Grant provenance uses a fixed vocabulary: policy · request · manual · sync.

Drift is any case where Actual differs from Expected. For each attribute or assignment, the engine classifies the drift and decides how it should be resolved. Throughout the product this comparison is labelled Expected / Actual.

Three kinds of drift

Attribute drift — a writable attribute on the account differs from what the governance model expects. For example, displayName was changed by hand in Entra.
Unapproved grant — an assignment exists in the target but not in the Expected state. For example, someone was added to an Active Directory group directly, outside the platform.
Account missing — the Expected state says "this identity should have an account on system X" but none exists. Whether the platform may create the account itself is decided by a single shared resolver (an override chain where the most specific non-null value wins): EntitlementType.auto_provision_account_override → AccountType.auto_create_on_demand (tri-state; an explicit False is a veto) → ConnectorInstance.auto_provision_account_default. The account type follows the classification: privileged and admin entitlements route to an administrative account type — never to a personal account that happens to exist.

Per-system policy: attribute drift action

How aggressively may the engine write back? This is set per system (ConnectorInstance):

auto_fix (default) — the engine writes the Expected value to the target. If the target write fails, the fallback is a provisioning job with failure_reason=TARGET_API_ERROR.
review — drift is always flagged as a provisioning job with failure_reason=CONFIG_ERROR; the engine never writes on its own. For organizations that want explicit governance over every piece of drift.
keep — no operation; the drift stays visible only in the reconciliation display panel. For sandbox systems or visibility-only flows.

⚠ Note

Production Entra (business_id="entra-rv-target") is ALWAYS flagged as a provisioning job, regardless of policy — this is a hardcoded gate. It ties into the "never touch serge@rapidvalue.be" security rule.

Unapproved grant policy

Set per system via unapproved_action:

keep — accept the assignment in the governance model as a new record (creates an EntitlementGrant).
auto_remove — revoke the assignment in the target.
auto_certify — open a drift access review in the unified review inbox (via an event-driven access-review rule that covers entitlement.drifted; a per-entitlement override is possible through unapproved_action_override).

Three-layer attribute propagation filter

When an identity attribute changes and must be propagated to targets, the engine runs a three-layer filter per account:

Layer 1: IdentitySyncConfig.propagate_attributes (tenant-wide allowlist)
Layer 2: ConnectorInstance.provisioning_field_mappings (per system, job_type=account_modify)
Layer 3: AccountType.write_attributes (per-account-type allowlist)

If all three layers match → connector.update_identity(). If an attribute is not allowlisted in even one layer → silent skip (by design). If the target write itself fails → a provisioning job with status=FAILED in the Failed Jobs queue.

Further reading: