Skip to main content
Provisionr manages access for each of your employees, contractors, temporary workers, and third-party collaborators, such as customers, partners, and vendors. Every human has a single record in the Directory that we refer to as a Directory User, regardless of how many systems they have access to or what type of relationship they have with your business. Another way to think about this is that every unique email address, whether inside or outside of your company, has a 1:1 relationship with a Directory User record. In technical terms, you may also refer to this as the Global Address List (GAL). In non-technical terms, think of this as your address book, email contact list, or phone book.

Integration Identities

Each of your organization’s SaaS applications, platforms, and tech stack systems has its own users. Whether people sign in with a local user account or with single sign-on (SSO), each system still has a user account for them. When you enable an integration with a vendor, we import each of that system’s users as a Directory Identity. The Directory User then acts as the unified profile for each person. It’s linked to each of that person’s identities across your configured integrations, which gives you a single pane of glass for every system that they have an account in.
Importing Directory Users and IdentitiesImporting Directory Users and Identities

Extract-Transform-Load (ETL) flow for importing Identities and Users from Integration APIs


Source of Truth

Provisionr needs a source of truth to know when people join and leave your company, and your Identity Provider (IdP) is usually the best source for that state. Provisionr is designed to use Google or Okta as your authoritative source. You can connect both, but the first one you enable should be the one with the most profile data for each user, which is usually the one that’s already integrated with your Human Resources Information System (HRIS). Provisionr doesn’t integrate with your HRIS today, so we use your IdP as our source of truth. The first integration that you configure becomes the authoritative source for these parts of each Directory User:
  • Name
  • Email
  • Manager relationship
  • Employee IDs, which are optional
  • Employment state
Additional integrations provide supplemental profile data, which enriches the Directory User with imported Dimensions and Attributes.

Profile Field Mapping

This table shows where each Directory User field comes from in Google and in Okta. 1 The created field is the date that the user was created in Okta. We don’t use the activated date, which can differ if you pre-stage users, because a user can be reactivated, so that date doesn’t always reflect when they were first provisioned during onboarding. If you need a rule condition that compares dates with the less or greater operators, you can create or use a custom profile attribute such as start_date.

Manager Mapping

Manager relationships are built by looking up a key that’s available on both the manager’s identity and the direct report’s identity. This might be a pair of keys such as employee_id and manager_id, or a manager’s email address. Every organization stores this differently, so you can choose which profile key to use for manager ID mapping on each side. You can configure manager sync on any integration, although it’s most often configured on your primary integration, which is usually your IdP. It takes three settings.
1

Manager Sync

Enable manager sync on the integration.
2

Direct Report Profile Key

Set the key on the direct report’s profile that identifies their manager.
3

Manager Profile Key

Set the key on the manager’s profile that the direct report’s key is matched with.

Employee ID and Badge ID Mapping

Each Directory User has employee_id, employee_alt_id, and badge_id fields. They’re empty by default, and you can map each of them to any profile key on your primary integration, which is the first integration that you configured. The names are generic, so you can use any kind of value in each field. An employee_id might differ between your identity and HR systems, for example, and a person might have more than one badge depending on the building. The fields are there so that you can use integer or string references to identify people without using their name, username, or email address. There are no plans to support renaming these fields. If you need a field with a name of your own, you can enable attributes on a dimension instead. The Badge ID, Employee ID, and Employee Alt ID appear in table lists and exports only, to help you cross-reference audit and compliance data with your other systems. These Directory User fields can’t be used in ruleset conditions. As a workaround, you can use an Identity Condition with string matching on the profile key, or enable attributes for its dimension. Each of these fields is mapped with its own setting on the integration.
1

Badge ID

2

Employee ID

3

Employee Alt ID

State Mapping

A Directory User’s state is determined by the state of their primary identity. If the primary identity is active, the Directory User is active, and if the primary identity is deprovisioned, the Directory User is deprovisioned. We check the Directory User’s state, and update it when it has changed, during each scheduled sync.

Scheduled Sync Flow

Primary and Secondary Identities

Each person’s primary identity comes from your primary integration, which is usually the IdP or SSO system that’s connected to your HRIS. The primary identity:
  • Establishes the Directory User record
  • Provides the authoritative name and employment status
  • Triggers joiner, mover, and leaver workflows when it changes
Secondary identities come from your additional integrations, and they:
  • Enrich the Directory User with additional attributes
  • Provide vendor-specific IDs for resource management
  • Don’t trigger employment lifecycle events

Creation and Correlation

Provisionr correlates identities across integrations by email address, and only during the initial sync. Once an identity has been linked to a Directory User, the link doesn’t change if the email address changes later, because we use the vendor’s unique user ID for API calls and correlation. During each scheduled sync, we use the integration’s API credentials to fetch the list of users from the vendor’s API, and we import them into Provisionr as identities. To tell whether we already know about an identity, we look for the vendor’s ID for the user in the vendor_id field, which we stored during the first sync that detected the user. If there’s no match on vendor_id, we create a new identity in Provisionr for that integration. When we create the identity, we look for an existing Directory User to link it to, by matching the vendor user’s email address with the Directory User’s email address. If there’s no Directory User with that email address and this is the primary integration, such as your IdP, we create a new Directory User and link the identity to it. That Directory User is where all of the person’s identities across your systems come together.

Orphaned Identities

If there’s no matching Directory User and this is not the primary integration, the identity’s directory_user_id field is left empty until a match is found in a future sync. We call this an orphaned identity, and its state is set to orphan instead of active. We don’t import the dimensions and attributes of an orphaned identity until it’s linked to a Directory User. This keeps erroneous, or “dirty”, profile data out of your directory for accounts that aren’t part of your organization, such as secondary, testing, or service accounts. To see your orphaned identities, filter the list of identities by the orphan state.
In an upcoming release, you’ll be able to link orphaned identities to existing Directory Users by hand.

New Identities Sync Flow

New Identities FlowNew Identities Flow

Decision flow for handling new identities during scheduled sync

Existing Identities Sync Flow

Existing Identities FlowExisting Identities Flow

Decision flow for handling existing identities during scheduled sync


State Changes

When a person’s identity in the primary integration changes to deprovisioned, their Directory User is deprovisioned too, and they’re removed from every policy-managed attribute, group, and resource. This should only happen when someone is offboarded. When an identity is deprovisioned in any other integration, the person is only removed from that integration’s groups and resources. For example, a person who is deprovisioned in GitLab only loses access to GitLab groups and projects, and not to their Google Workspace groups or Slack groups.
There may be customer use cases that we haven’t thought about yet. If a user is deprovisioned unexpectedly, or you run into a situation where you need different behavior, please email us at [email protected].

Deprovisioned Users

When a Directory User is deprovisioned, they’re no longer among the qualified users of any policy, so they’re removed from every policy-managed group and resource in a later stage of the same sync. Removing Access for Leavers walks through each step.

Deprovisioned User Retention Period

You can set retention_days on an integration to control how long Provisionr keeps deprovisioned identities. By default, an identity is kept for 90 days after it’s deprovisioned, while the Directory User record is kept indefinitely. This allows you to meet data retention requirements and redact personally identifiable information once it no longer serves a business purpose. We keep the person’s first and last name, along with their title, department, and other organization metadata, for audits, but we don’t keep their contact information or any other data from their identities. Data Retention Duration describes the range of values you can choose from.
We have a feature request to implement pseudonymization of deprovisioned identities instead of full deletion, as well as for Directory User PII. If this is something your organization needs, please email [email protected] to help us understand your use case.

Scheduled Expiration

Your HRIS may have more detailed information than your IdP about when an employee’s or contractor’s last day is, and contractor end dates are often hard to keep track of when they aren’t managed in your HRIS or IdP. When you know an employee’s or contractor’s end date ahead of time, you can use the directory-user:deprecate CLI command to set the expires_at field on their Directory User, which is their expiration date. On that date, their access to groups and resources is deprovisioned automatically. You still need to deprovision the person in your IdP, but any access that they were granted through group membership is revoked on that date without anyone having to remember it. Your IdP remains the source of truth, so if the person is deprovisioned there first, they’re removed immediately, without waiting for their expiration date.
This can cause a race condition with Restored Users if the person is reactivated in your IdP before their expiration date. A person who is reactivated in your IdP is restored during the next scheduled sync, regardless of their expiration date.We have a feature request for sending deactivate user API calls to your IdP, which would prevent this from happening in the future. If this is a concern for your organization, please email [email protected] to help us understand your use case.

Restored Users

When a person’s identity in the primary integration, such as their IdP account, is deprovisioned and later reactivated, their Directory User is restored during the next scheduled sync after they’re active in the IdP again. We keep a record of the groups and resources that they were previously a member of, but we don’t automatically restore their access to those groups and resources. Their old Policy Users stay in a soft deleted state for auditing purposes. As part of the reactivation process, we evaluate the person’s current profile data against every ruleset to determine which groups and resources they now qualify for. Each policy that they qualify for again gives them a new Policy User, so their history shows the gap between the two grants. Creating New Policy Users explains when a new record is created. If their job role, department, location, or other profile data has changed since they were deprovisioned, they may qualify for different groups and resources than they had before. When a Directory User is deprovisioned, the User Conditions that name them are deactivated. So if they were a named member of a policy through a User Condition, an administrator needs to re-create that rule, or duplicate it and activate the new version, before it grants them access again.

Suspended Users

We trust your IdP to decide whether a suspended user can sign in to your systems. A user in the suspended state isn’t included when we sync policy-managed groups or resources, because only active and expiring users have access. If a user changes from active to suspended in your IdP, they’re deprovisioned from all policy-managed groups and resources in Provisionr. When the suspension ends in your IdP, their state changes back to active, and their access to groups and resources is restored in a later stage of the same scheduled sync.
Provisionr is currently hard coded to look for users in the active or expiring state when it syncs policy-managed groups and resources.Some organizations may want suspended users to keep their access instead of having it deprovisioned. We have a feature request for a setting that would retain access for suspended users, which could be applied globally and potentially at the ruleset level as well.If your organization needs this, please contact [email protected] to discuss your use case, which helps us make better decisions about how we implement it.
Suspension is usually used for security incidents and for pausing someone’s access temporarily, so we generally recommend deprovisioning users in your IdP to ensure that their access is fully revoked across all systems.If you suspend users instead of archiving or deactivating them as part of your offboarding process, please contact [email protected] to discuss your use case, so that we can see how best to support your workflow.We have a feature request for a setting that would treat suspended users as deprovisioned users for offboarding workflows, and we’d like to understand more customer use cases before we implement it.

FAQs and Edge Cases

Temporarily Disabling Sync

When you declare an incident, you can disable sync on all integrations to freeze all activity in your workspace. To disable sync on a single integration, change its sync_enabled value. To pause one group or resource instead, see Disabling Sync for a Group or Resource.

Multiple Email Addresses and Aliases

Provisionr only supports and imports a user’s primary email address. As a workaround, you can store the secondary email address in an organization attribute in Google, or in a custom profile attribute in Okta, so that it’s imported with the user’s profile. You can then use an Identity Condition with string matching to use this value in your policies. Orphaned Identities explains how Provisionr handles email addresses that don’t match.

Data Schema Reference

Provisionr API Documentation

Provisionr CLI Documentation

Google Profile Data

Provisionr imports the following profile data from each Google user. The organization metadata depends on the fields that your organization has configured. Provisionr detects each of these keys automatically and creates a dimension for each one.

Google API Data

Google Documentation for User Profile
Google User from the Directory API

Google Identity Data

Directory Identity for a Google User

Okta Profile Data

Provisionr imports the following profile data from each Okta user. The organization metadata depends on the fields that your organization has configured. Provisionr detects each of these keys automatically and creates a dimension for each one.

Okta API Data

Okta Documentation for User Profile
Okta User from the Users API

Okta Identity Data

Directory Identity for an Okta User

Slack Profile Data

The Slack integration will be added in an upcoming release. If you would like early access to this integration, please email [email protected].

GitLab Profile Data

The GitLab integration will be added in an upcoming release. If you would like early access to this integration, please email [email protected].

Each person’s identities carry profile metadata, such as their department and title. The next page looks at how Provisionr organizes that data into Dimensions and Attributes, which your policies use to decide who gets access. Continue reading: Dimensions & Attributes →