Skip to main content
In How the Okta Sync Works, you saw that every sync runs an Identity Reconciliation stage before it reads any groups. That stage is where Provisionr decides what has happened to each person since the last sync, and this page looks at it in detail. Every Okta user becomes a Directory Identity in Provisionr, and every identity belongs to one Directory User, which is the record for the person. When Okta is your primary integration, Okta is also the source of truth for each person’s name, email, employment status, and manager. Users & Identities explains how identities from different integrations are linked to one person.

Okta Statuses

Okta gives every user one of eight statuses, and we map each one to an identity state. When Okta is the primary integration, the person’s Directory User state follows their Okta status between staged, active, and suspended. A new hire becomes active on their start date, and a suspension starts and ends with Okta. Other lifecycle states, such as a person who has left, belong to the directory’s own lifecycle and are never overwritten by a status change.

Identity Reconciliation

We match each Okta user to an existing identity by their Okta user ID, never by their email address, and then sort the user into exactly one outcome. The outcomes are checked in the order below, and the first one that applies is the one that’s used.
1

Imported Identities

No identity holds this Okta user ID yet, so we create a new identity.The new identity is linked to the Directory User with the same email address, and this is the only time that an email address is used for matching. If no Directory User matches and Okta is the primary integration, a new Directory User is created.
2

Reactivated Identities

The identity was deprovisioned, and Okta now reports the user as not deprovisioned, which happens when someone is rehired or an offboarding is reversed. The identity becomes active again, and policies can grant the person access again on the same sync. Restored Users explains how their access is worked out again from their current profile.
3

Deactivated Identities

Okta now reports the user as deprovisioned, which means the person has left.When Okta is the primary integration, the person is deprovisioned in Provisionr, and group write-back removes them from every policy-managed group right away, without waiting for a grace period. Grace periods are there to protect people whose attributes changed, not people who have left. See Wanted Members.
4

Status Changes

The user moved between staged, active, and suspended. The identity is updated with the user’s current profile, and when Okta is the primary integration, the Directory User’s state follows.A suspended person keeps the group memberships they already have, because Okta keeps a suspended user’s groups too, but they aren’t added to any new group until the suspension ends.
5

Profile Updates

One or more profile keys changed while the user is active, which usually means the person is a mover with a new department, title, or country.The profile is compared key by key in both directions, so a key that was added, removed, or changed counts, and values that are lists are compared by their content. The audit event names each key that changed, which tells you which dimensions moved for this person.A staged or suspended user’s profile changes are applied with their next status change.
6

Sign-In Updates

Only Okta’s last sign-in time or last profile update time moved. We store the new times without writing an audit event, so sign-in recency stays accurate for access reviews without an event for every sign-in.
7

Unchanged Identities

Nothing about the user changed, so nothing is written.
An identity is linked to its person by Okta user ID, so changing someone’s email in Okta never disconnects them from their access history. We record the change at the notice level as directory.identity.email.change.success, because an unexpected email change is something a security team may want to review.

Missing Identity Sweep

Some of the identities that Provisionr holds won’t appear in a sync at all. This happens when a user was deleted in Okta, or when they were deprovisioned and aged past the retention window between two syncs. We deactivate these identities, so that a person who was deleted in Okta can’t keep access through a policy. The difficulty is that a missing user and an incomplete API response look the same. An incomplete response can come from a partial outage, a pagination error, or a scope that was removed, and if we trusted it, a single bad response could offboard large parts of your company. For that reason, the sweep has a limit.
If more identities are missing in one sync than the larger of 5 identities or 10% of active identities, none of them are deactivated. Provisionr records a warning and tries again on the next sync. If they’re still missing on a sync with a complete response, they’re deactivated then.
In this example, 412 identities are missing from an integration with 2,150 active identities. The limit is 215, which is 10% of the active identities and larger than 5, so none of the 412 are deactivated.
directory.identity.sync.sweep.skipped
A swept identity that reappears in Okta later is treated like any other returning user, so it goes through the reactivated outcome described in Identity Reconciliation. An ordinary offboarding doesn’t depend on the sweep. A deprovisioned user is still returned by Okta within the retention window, so they’re handled by the deactivated outcome described above.

Logging Identity Reconciliation

This table lists the audit event that each outcome records, along with its level. A profile update records which keys changed, not their old and new values, because the values themselves are personal data. They’re encrypted in the database, and they’re already visible on the identity.
directory.identity.update.success

Once each person’s identity is up to date, the sync moves on to groups, where these identities become group members.

Sync Pipeline

Where Identity Reconciliation fits in the sync.

Okta Groups

How these identities become group members.