> ## Documentation Index
> Fetch the complete documentation index at: https://docs.provisionr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How the Okta Sync Works

> Every Okta sync runs eight stages in order, which read users, dimensions, groups, and apps from Okta, reconcile your directory, and then write policy-managed group membership back to Okta.

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](https://docs.provisionr.io/concepts/control/sync.md) explains how policies are evaluated across every integration.

![The eight stages of an Okta sync, from User Fetch to Group Reconciliation](https://mintcdn.com/provisionr/MWlUhtyl9lYRkT1i/images/diagrams/integrations/okta/sync/okta-sync-pipeline.svg?fit=max\&auto=format\&n=MWlUhtyl9lYRkT1i\&q=85\&s=c3b6be01f126de4ce5f0088a42c91395)

The eight stages of an Okta sync

## Design Principles

Five principles shape every stage of the sync.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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](#when-a-stage-fails).

> [accordion] 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](https://docs.provisionr.io/integrations/okta/audit-events).

> [accordion] Integration Scopes
>
> The access that the [connection test](https://docs.provisionr.io/integrations/okta/connect.md#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](#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](https://docs.provisionr.io/concepts/control/sync.md#data-retention-duration).

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](https://docs.provisionr.io/concepts/control/dimensions.md) 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](https://docs.provisionr.io/integrations/okta/users.md#missing-identity-sweep), which has its own safety limit. [Okta Users](https://docs.provisionr.io/integrations/okta/users.md) covers each outcome in detail.

**4. Manager Mapping**

When [manager mapping](https://docs.provisionr.io/concepts/control/users.md#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](https://docs.provisionr.io/concepts/control/policies.md#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](https://docs.provisionr.io/integrations/okta/groups.md#group-read-down).

**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](https://docs.provisionr.io/integrations/okta/apps.md).

**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](https://docs.provisionr.io/integrations/okta/groups.md#group-reconciliation) and [Policy Incidents](https://docs.provisionr.io/integrations/okta/incidents).

## Access Levels and Policy Modes

The first five stages always run. The last three depend on the access that the [connection test](https://docs.provisionr.io/integrations/okta/connect.md#connection-test) proves for your integration and on the mode of each group's policy.

| Access level | Group Read-Down | Group Reconciliation | App Read-Down | App assignments |
| - | - | - | - | - |
| Audit (Read-Only) | Runs | Reports drift for monitored, additive, and authoritative policies, and never writes | Runs | Never changed |
| Groups Only (No App Cleanup) | Runs | Reports drift for monitored policies, and writes for additive and authoritative policies | Runs | Never changed |
| Groups + App Assignments | Runs | Reports drift for monitored policies, and writes for additive and authoritative policies | Runs | Each app's [Provisionr group](https://docs.provisionr.io/integrations/okta/apps.md#provisionr-groups) is assigned to its app, and leftover direct assignments can be removed |

A policy can be in one of four modes, and two of them write to Okta.

| Policy mode | What Group Reconciliation does |
| - | - |
| Ignored | Nothing. The group was detected, and its members aren't read. |
| Monitored | Evaluates the policy and reports the difference. Nothing is written. |
| Additive | Evaluates the policy and writes the difference to Okta, at an access level that writes groups, and leaves members who were added outside of Provisionr alone. |
| Authoritative | Evaluates the policy and writes the difference to Okta, at an access level that writes groups, and also removes members who were added outside of Provisionr. |

> [!TIP]
>
> 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](https://docs.provisionr.io/integrations/okta/oauth2.md#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.

```json directory.identity.sync.process.finished theme={null}
{
  "event_type": "directory.identity.sync.process.finished",
  "level": "debug",
  "record_type": "okta_integration",
  "record_id": "okitg_01m4k1ben6mjeen4r46m8r2aw6",
  "metadata": {
    "identity_stats": {
      "imported": 3,
      "reactivated": 0,
      "deactivated": 1,
      "status": 1,
      "updated": 12,
      "timestamps": 240,
      "ignored": 1890,
      "missing": 0
    }
  }
}
```

The groups and apps stages record the same kind of summary.

```json workspace.integration.sync.okta.groups.finished theme={null}
{
  "event_type": "workspace.integration.sync.okta.groups.finished",
  "level": "info",
  "metadata": {
    "group_stats": {
      "imported": 2,
      "updated": 148,
      "removed": 1,
      "members_unchanged": 131
    }
  }
}
```

## 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.

```json policy.job.failed theme={null}
{
  "event_type": "policy.job.failed",
  "level": "critical",
  "message": "Background Job Failed; jobs queued after it did not run",
  "record_type": "okta_group",
  "record_id": "okgrp_01m4m2c7a9xq5p3h8w1k6d0ezt",
  "errors": [
    "Okta API returned 429 Too Many Requests"
  ],
  "metadata": {
    "job": "ReconcileOktaGroup",
    "exception": "RuntimeException"
  }
}
```

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](https://docs.provisionr.io/integrations/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.

> [card] [Okta Users](https://docs.provisionr.io/integrations/okta/users.md)
>
> How each Okta user is reconciled with your directory.

> [card] [Okta Groups](https://docs.provisionr.io/integrations/okta/groups.md)
>
> How group membership is read down and written back.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.