Skip to main content
Now that you know how rules and conditions are put together, the next question is what Provisionr does with them. During every sync, we take the rules of each policy, compare them with the latest profile data for everyone in your directory, and work out who should have access. We call this qualification. Qualification is where the decisions are made. It doesn’t add anyone to a group or remove anyone from an application on its own. Instead, it produces the list of people that each group, resource, or attribute should contain, and the rest of the sync uses that list to make changes in your connected systems. When you want to know why someone has access, or why they still have it after moving to another team, this is where you’ll find the answer. This page walks through qualification the way you’ll need it as a systems engineer, in this order:
  • The lists that qualification works with, and the order of its steps
  • How each person’s access is recorded
  • How grace periods give people time through changes
  • Where to look when a result surprises you
The last section covers the same ground for auditors and compliance engineers, using the language of controls and evidence.
This page builds on Policies & Rules. If rulesets, rules, and conditions are new to you, start there first.

Qualification Lists

When you look at a policy in Provisionr, you’ll find three different lists of people. They overlap, and it’s easy to mix them up, but each one answers a different question, so it helps to know which one you’re looking at. The first is the list of qualified users for each rule. These are the people who match that rule’s conditions right now, and the list is rebuilt on every sync. A person who matches three rules appears on three lists, because each list is about the rule rather than the person. The second is the manifest, which is the policy’s answer to who should have access. It combines the qualified users of every rule into a single list, with each person appearing once alongside the one rule that grants their access. The manifest is what the group sync compares with the members in your vendor, and it’s also what other policies read when one of their rules uses an attribute. The third is the list of Policy Users, which are the records behind the manifest. Each Policy User is a single grant of access. It names one person, one policy, and the one rule that grants their access, along with timestamps for when the grant began and when it ended. The manifest is made up of the Policy Users that haven’t ended yet. The ones that have ended are kept, and together they become that person’s access history for the policy. There’s also a fourth list that you’ll use for change management. The staged users of a draft rule are the people it would match if you activated it. We calculate them on every sync so that you can preview a rule before it goes live, but a staged rule never grants access to anyone. You can list the staged users, qualified users, and manifest users of any ruleset or rule with the workspace API. The Policy Users list in the CLI shows the current Policy Users and, when you ask for them, the ones that have ended.

Qualification Steps

Qualification runs for a ruleset during every scheduled sync, when you activate a rule in the ruleset, and whenever someone with permission syncs the ruleset on demand. Each time, it follows the same eight steps in the same order. The order matters more than it might seem. Every step that adds or replaces a grant runs before any step that ends one, so a person who moves from one rule to another stays on the manifest the whole way through, without a gap between syncs or even between two steps of the same sync.
1

Expired Rules

A rule can have an expiration date, and once that date has passed, the rule stops granting access. The sync moves the rule to expired before it evaluates anything else, so that its people are measured against the rules that remain. This is how short-term access expires on schedule.
2

Rule Qualification

For every active rule, and for every deprecated rule that hasn’t reached its expiration date yet, the sync finds each person who matches all of the rule’s conditions and records them as the rule’s qualified users. Staged rules are evaluated in the same pass, but their matches are recorded as staged users and don’t grant anything.
3

Ruleset Manifest

The qualified users of every rule are combined into one list, with each person appearing once. When someone qualifies through more than one rule, the rule that qualifies the most people is recorded as the one that grants their access. Rule Priority explains why.
4

New Policy Users

A person on the manifest who doesn’t have a current Policy User gets a new one. It starts in the active state, names the rule that granted it, and records when the grant began in activated_at.
5

Superseded Policy Users

Sometimes a person’s current Policy User no longer describes their grant, either because a different rule now grants their access, or because they were counting down a grace period and have qualified again. In both cases, the sync creates a new record for them and ends the old one. The new record is created first and the old one is ended second, so the person stays on the manifest throughout.
6

Deactivated Policy Users

A person whose rule was deactivated, and who doesn’t qualify through another rule, is deactivated at once, without a grace period. This includes anyone who was already counting down a grace period under that rule.
7

Deprecated Policy Users

A person with an active Policy User who is no longer on the manifest is deprecated. Their record moves to expiring, deprecated_at records when this happened, and its expires_at is set to the end of their grace period, or to the rule’s expiration date if that comes first. They keep their access until then, which means that a person whose rule has already expired moves through this step and the next one in the same sync.
8

Expired Policy Users

Every expiring Policy User whose expires_at has passed moves to expired and leaves the manifest. The record itself is kept, and its deleted_at shows when the sync ended it.
Qualification doesn’t call any vendor APIs. Its job is to make the decision, and the stages that follow carry it out. For a directory attribute, the manifest is the attribute’s membership, and other policies read it through Attribute Conditions. For a group or resource, the group sync compares the manifest with the members in your vendor and writes the difference. With Okta, policy incidents can also hold those writes for review. A policy incident never changes what qualification decided. It only decides whether the result is written right away or after someone has had a chance to look at it.
Qualification keeps the access decision separate from the access change. The decision is made from documented rules and recorded as a Policy User that names its rule, and the change is written to the vendor by a separate stage with its own events. This allows an auditor to test the control (does the manifest match the policy?) independently of the vendor operation (did the vendor receive the change?).

Condition Matching

As you saw in Policy Conditions, the conditions within a rule combine with and, so a person has to match every one of them, and the rules within a ruleset combine with or, so a person only needs to qualify for one rule. When you’re investigating someone’s access, the more useful question is what exactly makes a person match a condition, and what makes them stop matching it. A rule with no conditions matches no one. We never read an empty rule as “everyone”, so a rule that you haven’t finished building can’t grant access by accident.

Attribute Condition Grace Periods

An attribute is a policy too, with its own manifest and its own grace period. When a group’s rule uses an Attribute Condition, the group trusts the attribute’s manifest, and that manifest still includes the people who are counting down their grace period for the attribute. In other words, the two grace periods run one after the other. You can see this by following Ian Sanford, the IT Applications Engineer from Policies & Rules, as he moves from IT to the Security team. The IT attribute has a 30-day grace period. The it-admins Okta group grants access with a rule that uses the IT attribute, and the group has a 7-day grace period. This is by design. The IT attribute is the source of truth for who is in IT, and its grace period is part of that answer, so everything built on top of the attribute agrees with it. If a group needs to follow a move faster than the attribute it relies on, lower the grace period on the attribute or its dimension, and not only on the group. Departures work differently, and their grace periods don’t stack in this way. A person who leaves your organization drops out of every attribute’s manifest at once, so any group rule that relies on those attributes stops matching them on the same sync. See Removing Access for Leavers.

Rule Priority

The manifest records exactly one rule for each person, so that every grant has a single reason you can point to. When someone qualifies through more than one rule, we record the rule that qualifies the most people. For example, imagine an engineering-all Google Group with two rules. Rule A matches everyone whose department is Engineering, which is 140 people. Rule B matches everyone who reports to Wren Odell, which is 9 people. Six of them are in Engineering, and the other three are contractors in another department. The six people in Engineering are recorded under Rule A, and only the three contractors are recorded under Rule B. This gives you a view where the broad rules that follow your org structure explain most of a group’s membership, and each narrow rule explains only the people who need it. When you see a Policy User that was granted by an exception rule, you know that person qualifies only through that exception, which is exactly what a reviewer wants to see.
Each rule also has a priority value, which Policies & Rules describes. Today, the sync doesn’t use priority to choose a person’s rule. The number of people each rule qualifies is what decides.
Since the choice follows the size of each rule, it can change as rules grow or shrink. If a team rule ever qualifies more people than the department rule it overlaps with, the people who match both move to the team rule on the next sync, and each of them gets a new Policy User under it. Their access doesn’t change unless the two rules grant different roles.

Policy User Record

A Policy User is a small record, and each of its fields has a specific job.
Policy User for Ian Sanford in the IT Attribute
When you’re investigating, it helps to keep expires_at and deleted_at apart in your mind. expires_at is when the grant was due to end, and deleted_at is when a sync actually ended it, which is the first sync after the due time.

Policy User States

A record never moves backward. An expiring record is never made active again, and a record that has ended is never reopened. When a person qualifies again, their history gains a new record instead of an edited one. It may help to think of a Policy User as one assignment in an employee’s job history. If someone leaves the Sales team and rejoins it a year later, their HR record shows two Sales assignments with two start dates, not one assignment with its end date erased. Policy Users work the same way. Each record describes one continuous grant, and it stays true to what happened even after circumstances change.
Because records only move forward, the system that produced the access history cannot revise it. A Policy User’s rule, start, and end are written once, and later events add new records instead of changing existing ones. Point-in-time membership can therefore be reconstructed from the records themselves, and every transition is corroborated by an event in the event log, whose records cannot be edited.

Policy User Lifecycle

Every Policy User moves through the same three phases, and this diagram follows one from start to finish. Qualification creates the record and keeps it active for as long as the person qualifies. Deprecation gives them a grace period when they stop qualifying, and expiration ends the grant and removes them from the manifest. A person only skips the grace period when the reason comes from the rule or the policy rather than from the person. When the rule that granted them expires, they go out with it on the next sync. When that rule is deactivated, they’re deactivated on the sync that follows, and when the whole policy is deactivated, everyone is deactivated at once. A person who qualifies through another rule of the same policy keeps their access when one rule ends, and they receive a new record under that rule, which Creating New Policy Users covers in detail.

Policy User Dates

A Policy User has three dates that describe how a grant ends, and reading them together tells you which situation a person is in. deprecated_at is when they stopped qualifying, expires_at is when their access is due to end, and deleted_at is when a sync actually ended it. This table shows what the first two contain in each situation. An empty deprecated_at tells you that the person never stopped qualifying during this grant, even when expires_at has a date, because that date belongs to the rule. Once both are set, the time between them is the grace period that the person actually received.

Creating New Policy Users

The guiding principle is one record for each continuous grant under one rule. Anything that ends the grant, or changes the rule that grants it, starts a new record. Grace periods are there to absorb this kind of change without disrupting anyone. Suppose your IdP renames the Commercial Sales department to Mid-Market Sales. When the IdP starts sending the new name, the identity condition for the Commercial Sales attribute stops matching, and everyone who relied on it is deprecated. Nobody’s access changes yet, because each of them is counting down a grace period. An administrator attaches the new attribute to the affected rules with a new rule version, the next sync qualifies everyone again, and each person receives a new record under the new rule. Nobody lost access along the way, and the history shows exactly what happened. Each person’s grant under the old rule ended on the day of the fix, and their grant under the new rule began at the same sync. Considerations for String Matching explains how attributes make renames like this easier to absorb.

Grace Periods

Directory data changes all the time, and not every change means that someone’s job has changed. Departments get renamed, a manager can change twice in the same week during a reorganization, an HRIS import can fail halfway through, and an administrator might fix a typo in a rule the day after activating it. If every one of these changes took effect immediately, each of them would remove access from people in the middle of their work. A grace period is the number of days that a person keeps their access after they stop qualifying. Another way to think about it is that it turns a removal into a scheduled removal. During that time the person still has access, the change is visible to your administrators, and anything that turns out to be a mistake can be fixed before anyone notices.

Inheriting and Overriding Grace Periods

You can set a grace period, in days, at several levels, and a level that doesn’t set its own inherits one from the level above it. When a person is deprecated, the first level that sets a value is the one that applies. Each level reports two values so that you can see where its grace period comes from. expires_after_days is the grace period that applies after inheritance, and expires_after_days_inherited is true when that value comes from a level above. This makes it easy for you, or a reviewer, to tell which policies follow a default and which ones were tuned on purpose. To override the grace period at a level, give it an expires_after_days value from 0 to 1095 days. To go back to inheriting, send expires_after_days_inherited: true, which clears the override. An empty value is rejected rather than treated as “inherit”, so an update that leaves the field blank, or a tool that sends empty fields, can’t clear an override by accident. Inheritance is evaluated live, which means that a level that inherits doesn’t store a number of its own. When you change a parent, the grace period changes for every level beneath it that inherits. For example, if you shorten a dimension’s grace period from 30 days to 14, every attribute ruleset and rule in that dimension that hasn’t set its own grace period now uses 14 days as well.

Removing Access Immediately

A grace period of 0 removes access on the same sync that finds the person no longer qualifies. This is a good fit for privileged access, such as production administration, finance approvals, and security tooling, where an extra week of access after someone moves teams is more of a risk than a courtesy.

Grace Periods and Expiring Rules

A grace period protects a person whose own details changed. It doesn’t apply when the rule itself is ending, because the rule’s expiration date has already given everyone notice, so a person’s access never outlives the rule that granted it. If someone stops qualifying while their rule is expiring, they keep the shorter of their grace period and the time the rule has left. When the rule reaches its expiration date, the next sync ends the access of everyone it granted, as of that date and without a second grace period, unless another rule of the same policy grants them access. The same limit applies to anyone who is already counting down when a rule is deprecated. If their grace period would end after the rule does, we bring their expires_at forward to the rule’s expiration date, and each of those people gets a policy.user.grace.shortened event that shows the old and new dates. The rule’s policy.rule.deprecate.success event records how many people were affected in metadata.expiring_users_shortened. An attribute limits a grace period in the same way, because everyone on an attribute’s policy goes with it when it expires. If someone stops qualifying while their attribute is expiring, they keep the shorter of their grace period and the time the attribute has left, and deprecating an attribute brings forward any grace period that would end after it does, with the same event for each person.

Grace Period Timing

The clock starts at the sync that detects the change, not at the moment the change was made in your HRIS or IdP. For example, if your workspace syncs daily at 02:00 and someone’s department is changed at 09:00, their grace period starts at 02:00 the next morning. In the same way, the clock stops at the first sync after expires_at. With a 7-day grace period and a daily sync, a person loses access between 7 and 8 days after the sync that deprecated them. The sync frequency of your workspace sets that precision. A grace period is also fixed at the moment it starts. If you change a grace period at any level, the change applies to the next person who is deprecated, and not to anyone who is already counting down, because their expires_at was set when they were deprecated. The only thing that can change it afterward is their rule or attribute being deprecated, which Grace Periods and Expiring Rules explains. Putting it all together, the time between a change in your source system and the removal of access is the wait for the next sync, plus the grace period, plus the grace periods of any attributes that the rule depends on, plus the wait for the first sync after the grace period ends.

Changing Rules

A live rule is never edited in place. Its conditions are locked when it’s activated, so to change a rule, you duplicate it into a new version, edit the staged draft, and activate the draft. Each rule action has a predictable effect on the people that the rule grants. The difference between deprecating and deactivating a rule is worth remembering. Deprecating a rule means that it expires on a date, so people keep their access until that date. Deactivating a rule means that it stops granting now, so people lose their access on the sync that follows.

Temporary Access

Some access is only meant to last for a short time. An on-call engineer might need production database access for a four-hour incident, or a contractor might need a shared drive for the three days of an engagement, and neither of them should still have that access next month because someone forgot to remove it. You can grant time-boxed access with a rule that has a User Condition naming the person and an expiration date. When the expiration date passes, the next sync retires the rule, and the person’s access ends along with it on that same sync, whatever grace period the rule has. Since each window is its own rule, each window also gets its own Policy User record, with its own start and its own end. If the same person needs access again next month, that’s a second rule and a second record rather than an extension of the first. This allows access reviews to see each grant separately, with its own justification, which is how temporary access should be reviewed. Short-Term Access covers more ways to use rule expiration dates. The precision follows your sync schedule. A window that ends at 14:00 in a workspace that syncs every three hours ends at the first sync after 14:00.

Removing Access for Leavers

A grace period is meant to protect people whose attributes changed, not people who have left your organization. When someone leaves, your IdP deactivates their account, and the scheduled sync takes care of everything after that, in this order.
1

Directory User Deactivation

The user sync, which runs before qualification in every scheduled sync, imports the deactivation and marks the Directory User as deactivated.
2

No Matching Conditions

During qualification, the person no longer matches any conditions. Identity conditions don’t match because their identity is deactivated, Attribute Conditions don’t match because they’ve left every attribute’s manifest, and the manager conditions and User Conditions that name them don’t match either.
3

Policy User Deprecation

Every policy that granted them access deprecates their Policy User. The record counts down that policy’s grace period like any other, so it shows when the grant would have ended if they had moved to another team instead.
4

Group Removal

Group write-back never wants a person who has left, whatever their grace period. The same sync removes them from every group that a policy manages and records the reason as departed. See Okta Groups.
The same is true of anything built on an attribute. Attributes aren’t written to a vendor, and a person who has left is no longer counted on any attribute’s manifest, so every rule that uses an Attribute Condition stops matching them on the same sync.
For a person who has left, the Policy User’s expires_at is when the grant would have ended for someone who moved teams, not when their access ended. The evidence that their access was removed is the write-back event with the reason departed.

Qualification Troubleshooting

When a result surprises you, these are the tools you’ll reach for, roughly in the order you’ll need them. Before you activate a rule, you can preview it. A staged rule’s staged users show exactly who it will grant, and comparing them with the current rule’s qualified users shows you who will gain access and who will lose it before anything changes. To look at a person’s grant, start with the Policy Users list, which you can filter by ruleset, rule, or person, and which can include the records that have ended. Describing a Policy User shows its rule, its timestamps, and links to its event logs. The event log tells the rest of the story. Every time a record changes state, we write an event that names the record, the person, the rule, and the policy, and the create and deprecate events also list the rule’s conditions in plain language. See Logging Qualification. If you don’t want to wait for the next scheduled sync, you can sync a ruleset on demand to run qualification for that policy right away, which is useful after a rule change during a change window. Each on-demand sync is recorded as policy.ruleset.sync.initiated.api.
Start by checking that the rule is active rather than staged. Then check that the person matches every condition of the rule and not just most of them, that their identity is active in the integration that each identity condition names, and that they’re on the manifest of every attribute that the rule uses. Finally, check whether a sync has run since the change. Keep in mind that a rule with no conditions grants access to no one.
They’re almost certainly counting down a grace period. Their Policy User will be expiring, and its expires_at, along with the policy.user.deprecate.success event, shows when their access ends. If the rule uses an Attribute Condition, the attribute’s grace period runs first. See Attribute Condition Grace Periods.
That’s their history. Each record is one continuous grant under one rule, so when you read them in order of activated_at, you’ll see each time they moved between rules, moved to a new rule version, or qualified again after a grace period.
This usually means that a rule was replaced by a new version, or that a rule grew larger than a rule it overlaps with, so people moved to a different rule. Each of them received a new record, the old records ended at the same sync, and their access was continuous throughout.
When a person qualifies through more than one rule, the rule that qualifies the most people is the one recorded, and priority doesn’t affect this choice. See Rule Priority.

Audit and Compliance Reference

This section describes qualification in terms of controls and evidence. Everything here is produced by Provisionr on every sync, so none of it needs to be collected by hand.

Control Objectives

Qualification shows that access is derived from policy rather than granted by hand. The membership of every managed group, resource, and attribute is computed from documented rules on every sync, and each person’s record names the rule that qualifies them. It also shows that role changes are acted on without anyone having to ask. When a person no longer meets a rule’s conditions, their access is deprecated at the next sync and removed after a defined, configured grace period, without a ticket, a reviewer, or a reminder. Exceptions are explicit and attributable. Access for a named individual requires a rule with a User Condition, and since the broadest qualifying rule is recorded for each person, a grant recorded under an exception rule identifies someone whose only access is through that exception. Policy changes are controlled as well. A live rule cannot be edited, so changes are made as new rule versions that are staged, previewed, and activated, and each step is recorded along with the person or service account that performed it.

Mapping Controls to Evidence

Qualification supports the controls below. It is one part of the control environment, and the identity lifecycle in the IdP, write-back to vendors, and administrative access to Provisionr are each covered on their own pages.

Preserving Access History

Policy User records only move forward, from active to expiring, and then to expired or deactivated, and never back. Qualifying again creates a new record instead of reopening an old one, so no transition erases an earlier one. The granting rule cannot change on a record either. A change of rule ends one record and starts another, each with its own timestamps. Ended records are retained. They are soft deleted rather than removed, and they can be listed and filtered by when they ended. When one record replaces another, the new record is created before the old one ends, so the two overlap rather than leave a gap, and continuous access always reads as continuous. Every transition also writes an event to the workspace event log. Event records cannot be edited or permanently deleted, and a soft delete of an event is itself recorded as a new event. See Event Logs. Decisions are made by the system, and policy changes are attributed to the people who made them. Qualification events record the actor that started the sync, which is the system for a scheduled sync, or the person or service account that started an on-demand sync. Rule and ruleset changes record the person or service account that made them.

Logging Qualification

All of these events are stored in the workspace event log, at the info level unless noted. Each Policy User event names the Policy User as the record, the Directory User as the subject, the granting rule as the related record, and the attribute, group, or resource that the policy belongs to as the parent. Progress summaries for each sync are written to operational logs rather than the event log, so the per-person events above are the evidence of record. The events for changes written to Okta, including changes held for review, are listed in Okta Audit Events. When a person stops qualifying, the deprecation event records the conditions they no longer meet and when their access ends.
policy.user.deprecate.success
When a grant is superseded, the event on the old record names both rules and both records. In this example, the it-admins group’s rule was replaced by a new version, and Ian moved to it at the same sync.
policy.user.update.success (old record)
The matching event on the new record has the new Policy User as its record and the new rule as its related record.

Common Audit Questions

To show who had access to a group on a given date, list the policy’s Policy Users, including the ones that have ended. A person had access on that date if their record’s activated_at is on or before the date and its deleted_at is empty or after it. A person whose record was expiring on that date still had access. The group sync’s events then show when the vendor received each change. To explain why a person has access, start with their current Policy User, which names the rule. The policy.user.create.success event lists the conditions that qualified them, and the rule’s policy.rule.activate.success event names who activated it. Reconstructing Why Someone Has Access follows the same trail backward from an Okta membership change. To show how quickly access was removed after a termination, start with the directory.user.deactivate.success event. The write-back removal events from the same sync, with the reason departed, show the person leaving each group. A termination shouldn’t wait for a grace period, so a removal that came later than the sync which imported the departure is worth investigating. To show how quickly access was removed after a transfer, look at the policy.user.deprecate.success events, which show when each policy scheduled the end of access, and the policy.user.expired.deleted events, which show when each grant ended. Each interval should equal the configured grace period plus at most one sync interval, unless the rule’s own expiration date ended it sooner, and any attribute grace periods that a group rule depends on run first. To find access that is granted by exception, list the rules that have User Conditions, along with their qualified users. The Policy Users recorded under those rules are the people whose access exists only by exception. People who match both an exception rule and a broader rule are recorded under the broader rule, so when you’re assessing whether an exception is still justified, review the exception rule’s qualified users and not only the manifest. To check whether access was interrupted during a transfer, compare the end of the old record with the activated_at of the new one. A superseded record ends at the same sync that starts its successor, and the successor is always created first.

Reviewing Qualification Settings

When you review a workspace, these are the settings that shape qualification.
  • The grace period at every level, and which policies inherit a default. Policies that grant privileged access should use 0, or have a documented reason not to.
  • The rules with User Conditions, and the business justification in each rule’s description.
  • The rules with expiration dates, which represent time-boxed or deprecated grants.
  • The rule history for the review period, including the versions that were drafted, activated, and retired.
  • The sync frequency, which sets how quickly a change in the source system is acted on.

Known Limitations

Qualification runs on the sync schedule, so it acts on a change at the next sync rather than in real time. The workspace’s plan sets how often that is. A Policy User’s expiration date is not evidence of when a termination took effect. A departed person’s Policy User counts down its grace period just like a mover’s, but their group memberships are removed on the sync that imports the departure, so use the write-back events rather than the Policy User’s expires_at to evidence the timing of a termination. For moves, an attribute’s grace period runs before the grace period of any group that uses it. See Attribute Condition Grace Periods. Keep in mind that qualification makes the decision and write-back carries it out. The manifest is the authoritative statement of who should have access, and whether a vendor reflects it depends on the group sync and, for Okta, on any changes that are held for review.
With qualification in place, every policy has a list of the people it grants and a record of how each of them got there. The next page looks at the groups and resources that those lists are written to. Continue reading: Groups & Resources →