The eight stages of an Okta sync
Design Principles
Five principles shape every stage of the sync.Reading Before Writing
Reading Before Writing
We never write to Okta based on what we remember. Every group write-back is a comparison between what your policy wants and what Okta reports in the same sync, so a change that someone made by hand in Okta since the last sync is seen before anything is written.
Stage Order
Stage Order
Each stage depends on the one before it. Policy rules match dimension values, so dimensions are discovered before identities are reconciled. Group members are matched to identities, so groups are read only after identities are up to date.
Stage Failures
Stage Failures
If a stage fails, the stages after it don’t run against a half-updated directory. The failure is recorded as a critical audit event that names the stage and the error, so you can alert on it and investigate. See When a Stage Fails.
Audit Events
Audit Events
Each stage records a summary event with its counts. Each change that matters to a person, such as an identity being deactivated, a profile key changing, or a group member being added or removed, gets its own event with the reason for it. See Audit Events.
Integration Scopes
Integration Scopes
The access that the connection test proves for your integration decides which of the last three stages run at all. With read-only group access, we can report how far each group has drifted from its policy, but we can’t change anything. See Access Levels and Policy Modes.
Sync Stages
The stages run in this order on every sync.1
User Fetch
Provisionr asks Okta for every user who is active, staged, provisioned, suspended, locked out, recovering, or whose password has expired. It also asks for the users who were deprovisioned within your retention window.Users who were deprovisioned before the retention window aren’t requested at all, which is how a former employee’s personal data ages out of Provisionr.Before anything is stored, we discard each user’s home address fields, which are the street address, postal address, and zip code. We have no need for them to evaluate policy, so we never keep them.
2
Dimension Discovery
Every key in an Okta user profile, such as
department, title, or countryCode, becomes a dimension, and every distinct value of that key becomes an attribute of the dimension. A key that we’ve never seen before creates a new dimension, along with its attributes.Values are only compared within their own key, so Sales as a department and Sales as a division are separate attributes. Dimensions & Attributes explains why policy rules match these records instead of raw text.3
Identity Reconciliation
Each Okta user is compared with the identity that Provisionr already holds for the same Okta user ID, and the comparison sorts each user into exactly one of these outcomes:
- Imported
- Reactivated
- Deactivated
- Status changed
- Profile updated
- Sign-in timestamps updated
- Unchanged
4
Manager Mapping
When manager mapping is enabled for the integration, each user’s manager reference is resolved to the manager’s Directory User. This builds the reporting lines that Manager Conditions in policy rules rely on.
5
Org Snapshot Refresh
Each Directory User carries a snapshot of their organization attributes, which keeps policy evaluation fast. When a dimension is enabled or renamed, the snapshot of a user whose own profile didn’t change would otherwise go stale. This stage refreshes those snapshots, and it leaves users who already carry the current snapshot untouched.
6
Group Read-Down
Provisionr reads every Okta group, along with the members of each group whose policy isn’t ignored, as Okta has them. New groups are imported, and groups that were deleted in Okta are retired. A group whose membership hasn’t changed since the last sync isn’t read again. See Okta Groups.
7
App Read-Down
Provisionr reads every Okta app, the groups assigned to it, and the users assigned to it directly. This stage is read-only. See Okta Applications.
8
Group Reconciliation
For every group whose policy isn’t ignored, the policy is evaluated again, and the members it wants are compared with the members that Okta has. A monitored policy reports the difference. A managed policy writes the difference back to Okta, unless a safety check holds it for review.This is the stage that changes access in Okta. See Okta Groups and Policy Incidents.
Access Levels and Policy Modes
The first five stages always run. The last three depend on the access that the connection test proves for your integration and on the mode of each group’s policy.
A policy can be in one of four modes, and two of them write to Okta.
Stage Summary Events
Each stage records a summary event when it finishes. The identity summary counts how many Okta users landed in each outcome, which makes an unusual sync easy to spot. For example, a sync that suddenly deactivates hundreds of users shows it in these counts. A few of the counts are named differently from their outcomes.updated counts profile updates, timestamps counts the users whose sign-in times were the only thing that changed, and ignored counts the users who were unchanged.
directory.identity.sync.process.finished
workspace.integration.sync.okta.groups.finished
When a Stage Fails
A stage can fail because the Okta API returned an error, a request timed out, or the data wasn’t what Provisionr expected. When this happens, you can rely on three things.- The stages queued after the failed stage don’t run, so group write-back never acts on a directory that was only half updated.
- A critical audit event records the failed stage, the error, and the record it was working on.
- The next sync starts again from the first stage, with a fresh read of Okta.
policy.job.failed
directory.job.failed, and policy and group stages record policy.job.failed. Both are good candidates for an alert in your SIEM, and Okta Audit Events lists the other events that are worth alerting on.
Identity Reconciliation is where the sync works out what has happened to each person since the last sync, so the next page looks at that stage in detail.
Okta Users
How each Okta user is reconciled with your directory.
Okta Groups
How group membership is read down and written back.