Each group has a 1:1 relationship with a policy.
Policy Rulesets
A policy can have one or more Policy Rules, and together they form a set of rules that we call a Policy Ruleset. Each rule, in turn, holds the conditions that a user has to match.A ruleset holds rules, and each rule holds conditions.
Throughout the documentation, we use Policy, Ruleset, and Policy Ruleset interchangeably, and they all refer to the same thing. The official name is Policy Ruleset, but we often say Policy or Ruleset for short.
Imported Attribute Rulesets
When you connect an integration and import its groups or resources, Provisionr automatically creates a Policy Ruleset for each group or resource that you imported. The same is true of the attributes that we import from your users’ profile data, as Dimensions & Attributes describes, so every imported attribute has a ruleset of its own. For example, an integration might give you these counts of imported attributes for each dimension.Count of Imported Attributes
policy_ruleset_id field of every attribute, group, and resource record in Provisionr. Here is the IT attribute, followed by its ruleset.
IT Department Attribute Data
Policy Ruleset for IT Department Attribute
authoritative mode, and the ruleset of an attribute can’t be changed to another mode. Its 30-day grace period is inherited, which is why expires_after_days_inherited is true. Inheriting and Overriding Grace Periods explains where an inherited grace period comes from.
Each imported ruleset includes one rule by default.
Policy Rule for IT Department Attribute
IT attribute, that’s a department that equals IT.
Policy Condition for IT Department Attribute Rule
Policy Conditions
A Policy Ruleset can have an unlimited number of rules, and each rule can have an unlimited number of conditions, so you can build rulesets with as much granularity as you need. A condition works like an equation. We evaluate the left side against the right side with an operator, and the result is either true, which means the user matches, or false, which means they don’t. If a user matches every condition in a rule, they are considered a qualified user for that rule. In other words, the conditions of a rule combine as this and that. A user who matched in the past but no longer matches is considered a disqualified user, and any user who doesn’t match all of the conditions is ignored. A user only needs to qualify for any one of the rules to be added as a Policy User. In other words, the rules of a ruleset combine as this or that.Rules combine with or, so a user who matches any rule qualifies.
Typical ruleset with multiple rules and conditions
Sales division. You can narrow it further with a custom Sales Region dimension, in which a US Country Sales Team attribute uses a single rule with two conditions, and a user must match both of them.
Each condition that you add to a rule tightens the result. A
California Sales Account Executives attribute narrows the audience down to one team with four conditions, all of which must be true.
There is no hard limit on the number of conditions in a rule, but in practice, a handful is enough to isolate almost any team.
Each additional condition narrows a rule to a more precise audience.
Identity Conditions
An Identity Condition matches users on the string values in their identity profile data for an integration, which is the profile that the vendor’s API returns for each of them. When you create an Identity Condition, you choose an existing integration and the key that you want to evaluate, such asdepartment. Then you choose the operator to use, such as equals, and enter the string value that you’re looking for, such as IT.
You’ve already seen how we import the profile data from the integration API and create dimensions and attributes from the keys and values in that profile data. Each of those imported rules uses an Identity Condition.
During each sync, Provisionr looks at every identity, which is a user’s data from the chosen integration, and returns the users whose profile has the key with a value that satisfies the operator. In other words, a user matches when their value, compared with yours by the operator, evaluates as true. Only identities that are active or scheduled to expire are evaluated, so a deactivated identity never matches.
Condition Operators
We support several condition operators for string evaluation. Most of them compare the user’s profile value with the value in the condition, whileempty and exists only check whether the profile has a value for the key at all. Every operator ignores case, so it and IT are treated as the same value.
Identity Condition Example
The typical ruleset shown in Policy Conditions includes a rule for the IT Applications team with an Identity Condition wheretitle contains IT Applications. This means that any user whose job title includes the keyword “IT Applications” matches this condition, although they still have to match all of the rule’s other conditions as well.
Ian Sanford’s identity shows how this works. His title is IT Applications Engineer, so he matches the condition.
Directory Identity Data
Considerations for String Matching
Identity string matching is a raw string evaluation with no lifecycle management. If the value is renamed in the integration, the condition silently stops matching, and neither your administrators nor your end users can see that it happened. If you reuse the same logic in multiple places, or the value is predictable, use an Attribute Condition instead. This gives you a single source of truth, and a menu of choices to select from rather than raw strings repeated in each rule.Your policies are mapped to the ID instead of the string value, so if the value changes, you can update the attribute’s display name and all of the policies that reference that attribute will automatically be updated.
Commercial Sales to Mid-Market Sales, the next sync detects the new value and creates an attribute for it, while the old imported condition stops matching, because no user carries the old value anymore. Rather than silently dropping access, Provisionr surfaces the affected users for review and hands them to the deprecation lifecycle, which grants a grace period before any access is removed. That’s enough time for a role change that needs a few days of overlapping access. Creating New Policy Users follows a rename like this one from start to finish. If you know about a rename ahead of time, you can avoid the new attribute altogether by updating the existing attribute’s profile_value.
You can also use expires_at to give an attribute an expiration date. Once the expiration date is reached, the attribute is automatically deprecated and no longer used in policies, and any users who were attached to it are automatically detached.
Attribute Conditions
An Attribute Condition matches the users who hold a directory attribute. It’s the most flexible condition type for defining rules based on user attributes, because the logic that decides who holds each attribute lives in a single source of truth. Since each Directory Attribute has its own ruleset with rules and conditions, it acts as a reusable ruleset. You can define your string matching once, as a single source of truth for your organization’s logic, and then reuse that attribute in the rules of different groups and resources without repeating your string-matching logic in each of them. You’ve already seen how we import the profile data from the integration API and create dimensions and attributes from the keys and values in that profile data. Each of these attributes can now be used in any rule as an Attribute Condition. A user matches an Attribute Condition while they’re on the attribute’s manifest, including while their grace period for the attribute counts down. Attribute Condition Grace Periods explains how that grace period and the group’s own grace period run one after the other. You can also create custom Directory Dimensions and Attributes. Each of them has a ruleset that you can add rules and conditions to, and that you can reuse by attaching it to various groups and resources. This is useful for granular dimensions that are now available in your HRIS and that you want to use across multiple groups and resources. For example, you could create aTeam dimension with an attribute for each team in your organization, and then use those attributes in any rule for any group or resource.
Custom attributes are also useful for special projects, sales regions, or deciding who should have access to data about a specific customer. If you’re used to creating a Google Group and adding everyone to it, you can use a Provisionr attribute instead, and then use that attribute in your group rulesets. This gives you a single source of truth for who should have access to that customer or project, and you can use the attribute across multiple groups and resources without having to manage the membership of a Google Group, Google Drive folder, Slack channel, and so on.
Since each attribute has a database record with its own ID, you select the attribute from a dropdown menu when you create a condition, rather than having to remember the exact string that you need to match.
Manager Conditions
A Manager Condition lets you choose a manager, and every user who reports to that person matches it. Both the manager and the report need to be active or scheduled to expire, so a report who has left the organization stops matching. A rule can mix condition types. Pairing a Manager Condition with an Identity Condition keeps only the reports who also match a profile field. ANorCal Account Team rule might combine the two.
Without the Identity Condition, the rule includes everyone who reports to the manager, and with it, the team narrows to a single job title.
New hires who report to this manager are added automatically. If a user’s manager changes, they no longer qualify for the rule. This is handled by the deprecation lifecycle, so their access to groups and resources expires after the ruleset’s grace period.
User Conditions
A User Condition names a single Directory User, whom you select from a dropdown list. It’s meant for corner cases, where a user doesn’t have one or more of the attributes that would qualify them for a rule.Policy User Lifecycle
A Policy Ruleset has a list of Policy Users, which is a many-to-many mapping to Directory Users. This list is recalculated on a recurring schedule, so new users who match the conditions are added, and users who no longer match are deprecated. When a user is attached to a ruleset, the relationship is stored as a Policy User. Each Policy User is a single grant of access to one user by one rule. Keeping each relationship as a record of its own gives you lifecycle tracking, which provides valuable data for auditing.
A Policy User only moves forward, from
active to expiring to expired, or to deactivated when its policy is deactivated. When a user qualifies again, or qualifies under a different rule, we create a new Policy User instead of reopening the old one, so a user’s history in a ruleset is a list of grants, each with its own start and end.
Qualification explains how each sync qualifies users, when a new Policy User is created, and where each grace period comes from.
Rule Priority
Each rule has a priority from 1 to 99. If you don’t set one, a custom rule gets a priority of 42 and an imported attribute rule gets 88, and yes, both of those numbers are pop culture easter eggs. A user may qualify for multiple rules, but their Policy User is associated with only one of them. The sync records the rule that qualifies the most users, not the rule with the lowest priority value, so priority doesn’t change this choice today. This is designed so that the rules that apply to entire departments explain most of a ruleset’s membership, and the narrower rules for a team, a manager, or a named user are recorded only for the users who qualify through them alone. It makes the exceptions in a ruleset easy to see, keeps your rule sprawl to a minimum, and shows you which rules don’t have any effect. For example, if a user qualifies for Rule X, which matches 140 users, and Rule Y, which matches 9 users, their Policy User is associated with Rule X. Rules are qualified during each scheduled sync, when you activate a rule, and on demand when you sync a specific ruleset. If the user no longer qualifies forRule X but still qualifies for Rule Y, a new Policy User with Rule Y is created on the same sync, and the Rule X Policy User is expired. The user never stopped qualifying, so there’s no grace period and no gap, and unless the role associated with each rule is different, the user won’t notice any disruption or change. The two records show when they qualified under each rule.
If the user no longer qualifies for any rule, their Policy User is deprecated and scheduled for expiration at the end of its grace period. Qualification explains the choice of rule in more detail.
Short-Term Access
When the conditions of a rule are only meant to apply for a short period of time, you can give the rule an expiration date by deprecating it with anexpires_at value. Once the expiration date has passed, the next sync expires and soft deletes the rule, and the users it qualified stop qualifying through it.
Those users lose their access along with the rule on that same sync, without a grace period, unless another rule grants it to them. Temporary Access shows this pattern for a single person’s access window.
An expiration date is useful for temporary access, such as these cases:
- A contractor who only needs access for 90 days
- A special project
- Vacation coverage that only needs access for a few days or weeks
- An employee who has changed job roles and is supporting their old team for the next few weeks or months while they transition to the new role
With rules and conditions in place, the next page looks at how each sync turns them into a list of people, and how each person’s access is recorded. We call this qualification. Continue reading: Qualification →