Directory Identity for Ian Sanford
department, becomes a dimension, and each distinct value of that key, such as IT, can become an attribute of the dimension. The rest of this page explains how we create and maintain those records, and why your policies match them instead of the raw text.
Directory Dimensions
The profile keys are the Dimensions, such as department, division, cost center, and job title. We automatically create a Dimension record for each unique key that appears in any of the user profiles in your integration’s API response. In Okta, for example, this includes all of the standard attributes and any custom profile attributes that your organization uses. These keys include business contact information, such asname, email, phone number, and status, and organization data, such as title, department, division, and cost center. For data safety, we don’t import postal address information at the street or postal code level. We do import the city, the province or state, and the country code, because some systems, such as HR benefits applications, depend on where each person lives. How the Okta Sync Works describes how the Okta integration discards home address fields before anything is stored.
Each dimension has a name for display and a handle, which is a short, lowercase abbreviation, such as dept, that’s safe to use in email handles and URL paths. You can also create custom dimensions and attributes of your own, which Attribute Conditions describes.
Enabled Dimensions
We detect every dimension that exists, but we only create attribute records for a dimension once you enable attributes for it. This allows you to opt in to how much of your data is stored in Provisionr. Each dimension has anattributes_enabled field that is false by default. When it’s true, we collect the unique values of that key across your users during each sync, and we create an Attribute record for each value, linked to its dimension by directory_dimension_id.
You only need to enable attributes for the organizational dimensions that you want to use in policies. You wouldn’t use employeeNumber or firstName in a policy, for example, but you’ll likely want department and title. Before you enable a dimension, you can preview all of its unique attributes to check that it contains useful data for policy conditions. Once you enable attributes for a dimension, they can’t be disabled again, so it’s a good idea to check the preview first.
When your Workspace Integration is synced for the first time, we check each dimension against a list of sensible defaults for the vendor and enable attributes for the ones on the list. For Okta, these dimensions have attributes enabled by default:
organizationtitledivisiondepartmentcostCentercountryCodetimezone
Directory Dimensions with Attributes Enabled
Directory Attributes
When we import identities, we look at their profile data and find all of the unique values of each key whose dimension hasattributes_enabled set to true. These values are the dimension’s Attributes.
During each scheduled sync, we look for new values and import each one as a new attribute. When a value is no longer found, its attribute is deprecated and expires 30 days later, whichever dimension it belongs to. Once the attribute reaches its expiration date, the next sync soft deletes it and deactivates its policy, and everyone on that policy goes with it.
That 30-day countdown belongs to the attribute, and it’s separate from how long each person keeps the attribute after they stop qualifying for it. While the attribute still exists, a person’s grace period comes from the attribute’s ruleset, which inherits the dimension’s grace period unless the ruleset or one of its rules sets its own. A grace period never runs past the attribute’s expiration date, so one that would end later is brought forward to that date. Inheriting and Overriding Grace Periods explains how each level inherits from the one above it.
These are the attributes of the Department dimension, with IT highlighted.
Attributes of the Department Dimension
IT Department Attribute Data
Attribute Lifecycle Changes
If you use string-matching rules today, you’re already working with dimensions and attributes, even if you haven’t called them that. A rule likedepartment equals engineering treats department as the dimension and engineering as the attribute.
Now imagine that the department is renamed to Software Development. With string matching, you’d need to find and update every rule that references Engineering, and any rule that you miss stops matching without telling anyone. This comes up often for administrators, and it’s one of the main reasons that attributes are records of their own in the Provisionr policy engine.
Provisionr maintains a single source of truth for every dimension and its unique attribute values, detected automatically from the users in your IdP directory. Instead of matching the raw string department equals engineering, we store a Dimension record for Department and an Attribute record for Engineering. Each record has its own ID, timestamps, and state, and rules reference these records by ID rather than by name, which means that the relationships between rules, dimensions, and attributes are managed through stable references rather than string matching.
When a value changes in your IdP, for example because a department was renamed in your HRIS, the next sync treats the new value as a new attribute, because nothing in the imported data says that the two values are related. The old attribute is deprecated and starts counting down to its expiration date, and the new attribute is imported alongside it. A new profile key works the same way, and it becomes a new dimension.
If you know about the rename ahead of time, you can keep the existing record instead. Each attribute has a profile_value, which is what the sync matches against your imported data, and a name, which is what you see in Provisionr. When you update the attribute so that its profile_value is the new value, the sync keeps matching the same attribute, with the same ID and every rule that references it. The name stays as it was unless you change it, so a department can be renamed at the source while it keeps its old name in Provisionr. A dimension works in the same way, through its profile_key and its name.
Make this update before the next sync if you can, because once a sync has imported the new value, it’s already a separate attribute. In that case, you can link the two with directory_attribute_id_successor, so that the predecessor records the attribute that replaced it. This link is there for history and audit discovery, so that you can follow an attribute forward to the one that replaced it, in the same way that a rule version records its successor in Rule Rollback.
All of this gives you better visibility into your policies as your organization changes. You don’t need to track down string-matching rules spread across many policies, and the audit trail shows what changed, when, and why.
Dimension Deprecation
A dimension can stop appearing in your integration’s API, and when it does, we don’t want that to cause an unexpected breaking change in your policies. So rather than removing the dimension right away, we deprecate it. We use the dimension’s grace period, which is its ownexpires_after_days or the workspace default of 30 days when it doesn’t set one, to set the expiration date of the dimension and of each of its attributes.
This gives you a log alert, which is recorded as a directory.dimension.deprecate.success event, along with a notice period in the UI and time for your administrators to update the rules that are affected.
If you need more time, you can change the dimension’s expiration date by deprecating the dimension again with a new expires_at. If the key was renamed in your integration rather than removed, you can update the dimension so that its profile_key is the new key. You can also convert the dimension from an imported dimension to a custom dimension, which preserves the existing attributes and attached users. Keep in mind that a custom dimension no longer has a source of information, so its data stays frozen in time unless you change it yourself.
After the expiration date has passed, the dimension and each of its attributes are soft deleted, and each attribute’s own policy is deactivated. You can reactivate these records, which soft restores them, if you need to.
The rules and conditions that reference these records aren’t deactivated along with them, so update any rules that are affected before the expiration date.
Logging Dimensions and Attributes
Each change to a dimension or an attribute is written to the workspace event log at theinfo level. These are the events that you’ll see most often.
Creating, activating, and deactivating a dimension or an attribute are recorded as well, with events such as
directory.attribute.create.success, directory.attribute.activate.success, and directory.attribute.deactivate.success.
API Reference
Since dimensions and attributes are records of their own, you can query users by a specific attribute value without parsing each user’s profile JSON. These API endpoints are available:/api/v1/directory/dimensions/api/v1/directory/dimensions/{ulid}/api/v1/directory/attributes/{ulid}/api/v1/directory/users
The
directory-dimension and directory-attribute commands in the CLI work with the same records.
Dimensions and attributes give us the vocabulary for describing the people in your directory. The next page looks at how policies use that vocabulary to decide who gets access to what. Continue reading: Policies & Rules →