Skip to main content
Once your Okta integration is connected, the next thing to understand is what happens each time it syncs. The Okta sync is where Okta’s view of your organization meets your Provisionr policies, and every sync, whether it was scheduled or started on demand, runs the same eight stages in the same order. The first five stages build an accurate directory from Okta. The last three read Okta’s groups and apps, and then write back the group membership that your policies decide. This page walks through each stage by name and explains what it reads, what it decides, and what it records. Scheduled Sync explains how policies are evaluated across every integration.
The eight stages of an Okta sync, from User Fetch to Group ReconciliationThe eight stages of an Okta sync, from User Fetch to Group Reconciliation

The eight stages of an Okta sync

Design Principles

Five principles shape every stage of the sync.
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.
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.
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.
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.
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
Identities that Okta no longer returns go through the missing identity sweep, which has its own safety limit. Okta Users covers each outcome in detail.
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.
A monitored policy is a safe way to try out a new policy, because the reconcile event of each sync shows exactly who it would add and remove before you allow it to write. See Scopes and Admin Roles to decide which scopes to grant.

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
The groups and apps stages record the same kind of summary.
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.
  1. The stages queued after the failed stage don’t run, so group write-back never acts on a directory that was only half updated.
  2. A critical audit event records the failed stage, the error, and the record it was working on.
  3. The next sync starts again from the first stage, with a fresh read of Okta.
policy.job.failed
Directory stages record 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.