Skip to main content
Now that you’ve seen how each Okta user becomes an identity, you can look at what Provisionr does with those identities in your Okta groups. We add and remove the members of Okta groups through the Okta API. When an Okta group is assigned to an Okta application, every member of the group gets access to the application, so managing a group’s membership with a policy also manages who can reach each app assigned to that group. This is the most common way that customers use Provisionr, because it automates application provisioning for most or all of the applications in your tech stack that you manage with Okta. Many teams come to it after they outgrow Okta’s built-in group rules. By then, they’re often managing group membership by hand one user at a time, building Terraform configurations that break when attributes change, or maintaining homegrown scripts that accumulate edge cases over time. Once a policy manages a group, its membership follows the profile data in your directory instead:
  • People get the right application access on their first day, based on their role.
  • Group memberships stay in sync as attributes change in your HRIS.
  • When someone moves to a new role, their application access is updated automatically.
  • When someone leaves, offboarding removes their access across all of your Okta-managed applications.
Two stages of the Okta sync handle groups. Group Read-Down learns what Okta has, and Group Reconciliation decides what Okta should have and writes the difference. The rest of this page explains each stage, the reason recorded for every change, and the events you’ll find in the audit trail.

Group Types

Okta has three kinds of group, and only one of them can be managed by a policy.

Group Read-Down

During Group Read-Down, Provisionr reads every group in your Okta org and compares the list with the groups it already knows, working through the steps below. Members are only read for groups whose policy isn’t ignored.
1

New Groups

A new Okta group is imported with a policy that has no rules, in the mode set by the integration’s default_ruleset_mode, which is monitored unless you change it to ignored. Provisionr never takes control of a group on its own, so you decide whether a policy manages it. Groups & Resources explains this opt-in model.
2

Group Members

The members of each group that isn’t ignored are matched to identities by their Okta user ID. Deactivated identities are matched too, because Okta keeps a deactivated user in their groups. Okta users that Provisionr never imported, such as people deprovisioned before your retention window, are skipped.
3

Unchanged Groups

Okta records when each group’s membership last changed. If that time hasn’t moved since the last sync, and no new identity has been imported since then, the member list isn’t requested again. In a large org, most groups don’t change between syncs, so this saves thousands of API calls and leaves more of your Okta rate limit for everything else.A write-back by Provisionr moves the same timestamp, so a group that we just changed is always read again on the next sync.
4

Removed Groups

A group that no longer exists in Okta is retired. Any open policy incident for the group is cancelled with the reason resource_removed, its policy is deactivated, and its member list is cleared. The group’s history and audit events are kept.

Group Reconciliation

Group Reconciliation runs for every group whose policy isn’t ignored. For each group, it works out who should be a member but isn’t, and who is a member but shouldn’t be. The diagram shows the whole decision, from evaluating the policy to writing the changes, and the sections below explain each part of it.
Group reconciliation decision flow from policy evaluation to write-backGroup reconciliation decision flow from policy evaluation to write-back

How group reconciliation decides what to write to Okta

Policy Evaluation

The policy is evaluated again with this sync’s directory, so new hires, movers, and leavers are already reflected. Policies & Rules explains how rules and conditions are built, and Qualification explains how each sync qualifies users and how grace periods work.

Wanted Members

A person is wanted in the group when all three of these are true:
  1. They have a Policy User that is active, or that is expiring and still inside its grace period.
  2. Their Directory User is active, which means that they haven’t left.
  3. They have an active identity in this Okta org.
A person who has left is never wanted, so they lose access right away, whatever their grace period. A grace period is there to protect people whose attributes changed, not people who have left. Removing Access for Leavers follows a departure through the whole sync.

Comparing With Okta

Provisionr compares the wanted people with the group’s members in Okta and builds two lists. The add list holds the wanted people who aren’t members yet, and the remove list holds the members who aren’t wanted. Two exceptions keep the remove list safe.
A member whose Directory User is suspended keeps their membership, because Okta keeps a suspended user’s groups too. They’re never added to a new group while they’re suspended. When the suspension ends, they carry on as before, and if they’re deprovisioned, they’re removed.
Non-Authoritative A non-authoritative policy only removes members that it granted at some point. Members who were added in Okta by hand, or by other automation, are left alone, which makes this the safe default for a group that you’re bringing under policy for the first time.Authoritative An authoritative policy is the single source of truth for the group, so it removes every member it doesn’t want, however they were added.

Change Reasons

Every change carries a reason, and the reason is recorded in its audit event.

Write-Back Checks

Before a change reaches Okta, it goes through four checks in this order.
1

Write Access

Only a managed policy on an integration that has proven it can add and remove group members writes to Okta. Otherwise, the changes are reported in the reconcile event and nothing is written. If the policy was writing back before, any open incident for it is cancelled with the reason not_writing_back, because there’s no longer anything to hold.
2

Approved Changes

Some changes were reviewed before they came due, and these are called approved changes. An approved change comes from one of these reviews:Each approved change covers one person being added or removed, and it expires. An approved change is written without being held again, and each one can only be used once.
3

First Write-Back Confirmation

The first time a policy writes to a group, nothing is written until an admin confirms the diff. If the diff is empty because the group already matches the policy, the first write-back is confirmed automatically. See First Write-Back Confirmation.
4

Safety Checks

Two safety checks look for changes that are more likely to be a mistake than a business decision. When a rule matches a dimension value that nobody holds anymore, the retired attribute check holds every change. When a sync would remove many members at once, the mass removal check holds the removals and lets the additions through. Held changes go into a policy incident for a person to review.
Everything that passes is written to Okta one change at a time. A change that Okta rejects is recorded with the error, as okta.group.member.add.failed or okta.group.member.remove.failed, and it’s tried again on the next sync. A rejected change doesn’t stop the rest of the changes.

What Gets Recorded

Every membership change gets its own audit event, so you can always answer a question like “why does Ian Sanford have Salesforce?” with the rule that qualified him. Every removal records why it happened, and who approved it if it was reviewed. Reconstructing Why Someone Has Access follows these events back to their cause. When a person is added, the event names the reason and the rule that qualified them. No approval was used for this addition, so approved is null.
okta.group.member.add.success
A removal that a person approved names the approval, where it came from, and the record that it came from.
okta.group.member.remove.success
Each reconciliation also records one summary event for the group, so a single event tells you what happened to the group in this sync.
okta.group.reconcile.process.finished
The summary message is one of four outcomes.
When a safety check holds changes, they’re raised as a policy incident for someone to review, and when a rule change removed the wrong people, a rollback puts the previous version back.

Policy Incidents

How the safety checks hold changes, and how they are reviewed.

Rule Rollback

How to undo a rule change that removed the wrong people.