AlignSync (Directory Mismatches)

AlignSync compares each person’s details across your connected directories against a source of truth you choose, shows where they disagree, and writes back the corrections you apply.

Catch & Fix Directory Drift

Over time, the same person’s details fall out of step across systems — a title changes in HR but not in Okta, a department is wrong in Microsoft Entra ID, someone who left still has an active account somewhere. AlignSync runs a drift scan that compares each identity against the source of truth you choose, then shows you exactly which fields disagree. The source of truth can be your Zonitix directory, one of your connected directories, a CSV file you upload, a policy that names the winning source field by field, or simply whichever copy was updated most recently. Nothing is changed silently: a scan and a dry run never write, and every correction you apply is audited, re-read from the target to confirm it took, and can be rolled back. A correction for one person takes effect as soon as an administrator who is allowed to write to the directory applies it. You can also require a second person to approve large bulk applies — that rule is off by default, and we recommend turning it on.

You do all of this on one screen: Access Governance → AlignSync, which has three tabs — Drift, Directory and Logs. AlignSync is part of the Team and Advanced plans.

If something here is not working as you expect, start with When something goes wrong.

Reconciliation API

AlignSync lives in the integration service and exposes a least-privilege API: viewing drift, editing the alignment policy / source file, approving changes, and executing write-back each have their own permission. manage_hooks is a superset that also grants policy edits and write-back, so the separation only holds for people who do not hold it. A drift scan hits every connected provider, so results are cached briefly (~5 min).

Reconciling A Directory

The steps on screen are in the guide Fix directory drift with AlignSync. This section gives the requests, fields and rules behind them.

1. Give It A Source Of Truth

Any connected, verified identity hook becomes a comparison source automatically. You can also upload an HR export as a file source: POST /align/source-file with a JSON body that carries the file text in a csv field: { "csv": "<file text>" }. A body without that field is rejected with a 400. The header row must contain an email column; firstName, lastName, department, position, employeeId and sAMAccountName are recognised, and these aliases are accepted: mail, upn, userprincipalname and primaryemail for email; givenname; surname and familyname; dept; title and jobtitle; empid and employeenumber; sam and login. Headers are matched ignoring case, spaces, underscores and hyphens.

2. Set The Policy

The policy decides which attributes are in scope and who wins a conflict. Per attribute you set enabled and a sourceOfTruth. Then the auto-reconcile block: intervalHours (default 24), driftThresholdPct (default 10 — the alert line), blastRadiusPct (default 30 — the safety cap), and applyMode, which defaults to preview. Preview never writes.

3. Scan, And Read The Result Properly

A scan hits every connected provider for every user, so the result is cached for about five minutes — add ?refresh=1 to force a recompute. Read comparable first: it is inSync + inDrift, the users that actually had something to compare against. localOnly users exist nowhere else, and driftPct is a percentage of comparable, not of everyone. If connected comes back false, no hook is verified and no CSV is loaded, so coverage is not measurable yet.

Use GET /align/orphans for hygiene: accounts in a provider but not in your source, local users missing from a provider, and active/disabled disagreements.

4. Write Back, With Or Without A Second Approver

A single-user sync writes straight away: it is audited, the target is re-read to confirm the write took, and it can be rolled back. A bulk apply does the same unless the approval policy is on. That policy is approval.enabled (default false) with approval.minUsers (default 10). When it is on, a bulk apply of that many users or more does not execute — it becomes a change request and returns { pendingApproval: true, requestId }. The approver cannot be the person who requested it; the server rejects a self-approval outright. Dry runs return the proposed diff without touching anything, and a blank value never overwrites a populated one.

The same approval queue also holds offboarding account disables that were parked by the directory-write safety limit (see Identity Hooks → How a directory write is protected). Those can be released from the notice on the Identity Hooks screen on every plan, with or without AlignSync.

5. The Blast-Radius Cap

If a direct bulk apply would touch more of the directory than blastRadiusPct allows, it stops with 409 blast_radius_exceeded and reports the percentage and the cap. Re-send with "override": true if it really is intentional. The scheduled reconciler applies the same guard and, when exceeded, skips the run entirely rather than applying half of it.

6. Undo

Every apply is written to the alignment log with the prior state, and listed on the Logs tab, where each row has a Rollback button. POST /align/rollback/:id restores local and provider fields from that snapshot in a transaction and marks the entry rolled back. A provider disconnected since the original run is skipped rather than failing the rollback.

If scheduled reconcile never seems to run: check that autoReconcile.enabled is true (it defaults to false), that enough time has elapsed for intervalHours, and — for the alert email specifically — that SMTP is configured under Security Settings. The drift alert is emailed to your primary administrator (the account created at setup). There is no recipient setting in the app today. A missing SMTP config skips the alert with a logged warning rather than failing the run.