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

# Okta Users

> How every Okta user is reconciled with your Provisionr directory, so joiners, movers, leavers, suspensions and email changes are detected, audited and acted on.

In [How the Okta Sync Works](https://docs.provisionr.io/integrations/okta/sync.md), 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](https://docs.provisionr.io/integrations/okta/connect.md#primary-integration), Okta is also the source of truth for each person's name, email, employment status, and manager. [Users & Identities](https://docs.provisionr.io/concepts/control/users.md) 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.

| Okta status | Identity state | Why |
| - | - | - |
| Active | Active | The person is working. |
| Provisioned | Active | The account exists and is waiting for the person to set a password. |
| Locked out | Active | A forgotten password is not a change in employment, so access does not churn. |
| Password expired | Active | Same as locked out. |
| Recovery | Active | Same as locked out. |
| Staged | Staged | A new hire who has not started yet. |
| Suspended | Suspended | Access is paused, usually for leave or an investigation. |
| Deprovisioned | Deactivated | The person has left. Only read within your retention window. |

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](https://docs.provisionr.io/concepts/control/users.md#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](https://docs.provisionr.io/integrations/okta/groups.md#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.

> [!NOTE]
>
> 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.

> [!WARNING]
>
> 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.

```json directory.identity.sync.sweep.skipped theme={null}
{
  "event_type": "directory.identity.sync.sweep.skipped",
  "level": "warning",
  "message": "More identities are missing from Okta than the sweep allows; none were deactivated",
  "count_records": 412,
  "record_type": "okta_integration",
  "record_id": "okitg_01m4k1ben6mjeen4r46m8r2aw6",
  "metadata": {
    "missing": 412,
    "active": 2150,
    "limit": 215
  }
}
```

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

| Outcome | Audit event | Level |
| - | - | - |
| Imported | `directory.identity.import.success` | info |
| Reactivated | `directory.identity.reactivate.success` | info |
| Deactivated | `directory.identity.deactivate.success` | info |
| Status changed | `directory.user.state.change.success`, with the old and new state, for the primary integration | info |
| Profile updated | `directory.identity.update.success`, naming each changed key | info |
| Email changed | `directory.identity.email.change.success` | notice |
| Sign-in updated | None | — |
| Missing identities deactivated | `directory.identity.deactivate.success` | info |
| Sweep skipped | `directory.identity.sync.sweep.skipped` | warning |

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.

```json directory.identity.update.success theme={null}
{
  "event_type": "directory.identity.update.success",
  "level": "info",
  "record_type": "directory_identity",
  "record_id": "dridt_01m4k9w2r8b6c3x0v5n7q1j4hy",
  "metadata": {
    "changed_keys": ["department", "title"]
  }
}
```

***

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

> [card] [Sync Pipeline](https://docs.provisionr.io/integrations/okta/sync.md)
>
> Where Identity Reconciliation fits in the sync.

> [card] [Okta Groups](https://docs.provisionr.io/integrations/okta/groups.md)
>
> How these identities become group members.


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