Users & Identities

Provisionr manages access for each of your employees, contractors, temporary workers, and 3rd party collaborators (customers, partners, vendors, etc). 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 users. Whether you authenticate with a local user account or single sign-on (SSO), there is still a user account. When you enable an integration with a vendor, we import each of the users on each integration system as a Directory Identity. Provisionr provides a single pane of glass with a Directory User that acts as the unified profile for each person that correlates each of the configured integrations and establishes a relationship with each of the user’s identities.

Importing Directory Users and Identities

Source of Truth

Provisionr needs a source of truth to know when users join and leave the company. Your Identity Provider (IdP) is usually the best source for state management. Provisionr is designed to use Google or Okta as your authoritative source. You can connect both, however the first one you enable should be the one with the most profile data for each user that is usually already integrated with your Human Resources Information System (HRIS). Provisionr does not currently integrate with your HRIS, so we use your IdP as our source of truth. The first integration that you configure will be the authoritative source for each Directory User’s name, email, manager relationship, (optional) employee ID(s), and employment state. Additional integrations provide supplemental profile data to enrich the Directory User data with imported Dimensions and Attributes.

Profile Field Mapping

Directory User Field	Google Profile Field	Okta Profile Field
`first_name`	`name.givenName`	`profile.firstName`
`last_name`	`name.familyName`	`profile.lastName`
`full_name`	`name.fullName`	`profile.firstName` + `profile.lastName`
`email`	`primaryEmail`	`profile.email`
`username`	`primaryEmail` (before the `@`)	`profile.login` (before the `@`)
`created_at`	(Date Imported to Provisionr)	(Date Imported to Provisionr)
`updated_at`	(Date Updated in Provisionr)	(Date Updated in Provisionr)
`provisioned_at`	`creationTime`	`created` ¹
`expires_at`	(Date Set in Provisionr)	(Date Set in Provisionr)
`deprovisioned_at`	`deletionTime` if set, or (Date Deprovisioned in Provisionr)	`statusChanged` if `status === "DEPROVISIONED"`
`deleted_at`	(Date Deleted in Provisionr)	(Date Deleted in Provisionr)

¹ The created field is the date the user was created in Okta. We do not use the activated date (ex. if you pre-stage users), since a user can be re-activated and this doesn’t reflect the original onboarding provisioning date. You can create or use a custom profile attribute (ex. start_date) if you need to create a rule condition with an less or greater date comparison.

Manager Mapping

Manager relationships are established based on looking up a key that is available on both the manager’s Identity and the direct report user’s Identity. This may be an employee_id and manager_id, or a manager email address. Every organization is different, so we support dynamic keys for manager ID mapping. Manager sync can be configured using any integration, but is most commonly done with your primary integration (IdP).

Enable Manager Sync on an Integration

prv workspace-integration:update --key manager_enabled

Configure the Key on the Direct Report Profile

prv workspace-integration:update --key manager_id_child_key

Configure the Key on the Manager Profile

prv workspace-integration:update --key manager_id_parent_key

Employee ID and Badge ID Mapping

Each Directory User has a employee_id, employee_alt_id, and badge_id field that are null by default that can be mapped to any profile array key on your primary (first) integration. These names are generic—you can use any kind of value for each field. We recognize that an employee_id might be different between Identity/IT and HR systems, and a user might have more than one badge depending on the building. These are simply provided for you to use integer or string references to identify users without using their name, username, or email address. There are no plans to support renaming these keys. You can enable attributes on a dimension if you need customization of the name of the key. Badge ID, Employee ID, and Employee Alt ID are for table list and export reference only to help with audit and compliance data cross-reference correlation. The Directory User mappings cannot 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 a dimension.

Configure the Badge ID

prv workspace-integration:update --key badge_id_profile_key

Configure the Employee ID

prv workspace-integration:update --key employee_id_profile_key

Configure the Employee Alt ID

prv workspace-integration:update --key employee_alt_id_profile_key

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. If the primary identity is deprovisioned, the Directory User is deprovisioned. The Directory User state is verified or updated during each scheduled sync.

Google State
Okta State

Provisionr State	Google Logic
staged	N/A for Google
active	`suspended` is `false` + `archived` is `false` + `deletionTime` is not set
expiring	Only if set in Provisionr
expired	Only if expired by Provisionr. Expired users are archived in Google.
suspended	`suspended` is `true`
deactivated	`archived` is `true` or `deletionTime` is set

Okta supports granular user states.

Provisionr State	Okta State
`staged`	`STAGED`
`active`	`ACTIVE`
`active`	`LOCKED_OUT`
`active`	`PASSWORD_EXPIRED`
`active`	`PROVISIONED`
`active`	`RECOVERY`
`suspended`	`SUSPENDED`
`deactivated`	`DEPROVISIONED`

Scheduled Sync Flow

Primary vs. Secondary Identities

The Primary Identity comes from your primary source (usually your IdP/SSO system that’s connected to your HRIS).

Establishes the Directory User record
Provides authoritative name and employment status
Changes trigger joiner/mover/leaver workflows

Secondary Identities from additional sources:

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 using email address during the initial sync only. Once an Identity has been established with a User, it will not change if an email address has changed since we use the vendor’s unique user ID for API calls and correlation. Identities are imported into the Provisionr database during the scheduled sync after we use the integration API credentials to fetch the list of users from the vendor’s API. We check whether we know about the Identity or not based on the integration vendor’s ID of the user that we stored in the vendor_id field during the first sync that we detected this user. If no vendor_id match is found, we create a new Identity record in Provisionr for that integration. When Provisionr creates the Identity, we check for an existing Directory User to link to by matching the vendor user’s email address against the Directory User’s email address. If no existing Directory User is found with that email address and this is the primary integration (ex. your IdP), a new Directory User is created in Provisionr and the Identity is linked to that new user for a single pane of glass of all system identities associated with the human user.

Orphaned Identities

If this is not the primary integration, the directory_user_id field is left null until a match is found in a future sync, and is considered an orphaned identity. The state is set to orphan instead of active. Dimensions and attributes for orphaned identities are not imported until the identity is linked to a Directory User. This avoids having erroneous “dirty” profile data in your Directory for users that are not part of your organization, such as secondary, testing, or service accounts. You can see the orphaned identities by filtering by the orphan state.

prv directory-identity:list --state=orphan

In an upcoming release, you will be able to manually link orphaned identities to existing Directory Users.

New Identities Sync Flow

Existing Identities Sync Flow

State Changes

If the Identity in the primary integration changes to deprovisioned, then the Directory User is also deprovisioned and the human user will be removed from all policy-managed attributes, groups, and resources. This should only occur during employee offboarding. If the Identity is deprovisioned in any other integration, that user will only be removed from that integration’s groups and resources. For example, if a user is deprovisioned in GitLab, they will only lose access to GitLab Groups and Projects, and not Google Workspace Groups or Slack Groups.

There may be customer use cases that we haven’t thought about yet. If you experience problems with a user being deprovisioned unexpectedly or run into a situation where you need different behavior, please email us at support@provisionr.io.

Deprovisioned Users

When a Directory User is deprovisioned, they are no longer included in the policy ruleset sync list of qualified users, so are removed from all policy-managed groups and resources during the next phase of the same sync.

Deprovisioned User Retention Period

You can configure retention_days on an integration to control how long deprovisioned identities are retained in Provisionr. By default, identities are retained for 90 days after they have been deprovisioned. The Directory User record is retained indefinitely. This allows you to comply with data retention and personally identifiable information redaction after it no longer serves a business purpose. The first and last name of the user and their title, department, and other organization meta data is retained for audits, but no contact information or other data on any of their identities is retained.

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 support@provisionr.io to help us understand your use case.

Scheduled Expiration

Your IdP is the source of truth, so if they are deprovisioned there first, they will be removed immediately. Your HRIS may have more detailed information about when an employee or contractor’s last day is. Many organizations struggle with contractor expiration dates that are not managed in your HRIS or IdP. If you have an employee or contractor with a known end date, you can use the directory-user:deprecate CLI command to set the expires_at field on the Directory User. This will automatically deprovision their access to groups and resources on that date. You will still need to deprovision the user in your IdP, however any access granted by group membership will be revoked on that date automatically.

It is possible that this may cause a race condition with Restored Users if the user is reactivated in your IdP before the expiration date. If the user is reactivated in your IdP, they will be restored during the next scheduled sync regardless of the expiration date.We have a feature request for sending deactivate user API calls to your IdP to prevent this from happening in the future. If this is a concern for your organization, please email support@provisionr.io to help us understand your use case.

Restored Users

If the primary integration user (ex. IdP user) is deprovisioned and is reactivated later, the Directory User will be restored during the next scheduled sync after they are active in the IdP. We have a record of which groups and resources they were previously a member of, however we do not automatically restore their access to those groups and resources. These old policy user relationships remain in a soft deleted state for auditing purposes. As part of the reactivation process, we evaluate the user’s current profile data against all rulesets to determine which groups and resources they now qualify for membership in. 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 previously. Any policies that they were previously a named user member of will need to be manually re-created (or duplicated and activated) by an administrator.

Suspended Users

We trust that your IdP is handling whether or not a suspended user can log in to your systems. A suspended state user is not included when syncing policy-managed groups or resources. Only active and expiring users have access. If a user changes from active to suspended in your IdP, they will be deprovisioned from all policy-managed groups and resources in Provisionr. When the user is un-suspended in your IdP, their state will change to active and their access to groups and resources will be restored during the next phase of the current scheduled sync.

Provisionr is currently hard coded to look for users in a active or expiring state when syncing policy-managed groups and resources.We recognize that some organizations may want to retain access for suspended users instead of deprovisioning them. We have a feature request to implement a boolean toggle for whether to retain access for suspended users. This could easily be deployed globally and potentially at the ruleset level as well.If this is something your organization needs, please contact support@provisionr.io to discuss your use case to help us make more informed decisions with our implementation.

Suspended users are usually used for security incidents and temporary access suspension. We generally recommend deprovisioning users in your IdP to ensure that 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 support@provisionr.io to discuss your use case to see how we can best support your workflow.We have a feature request to implement a boolean toggle for whether to treat suspended users as deprovisioned users for offboarding workflows. We want to understand more customer use cases before implementing this change.

FAQs and Edge Cases

Temporarily Disabling Sync

You can disable sync on all integrations when you declare an incident to freeze all activity in your workspace. You can disable sync on a specific integration by toggling the sync_enabled boolean.

prv workspace-integration:update --key sync_enabled

Multiple Email Addresses and Aliases

Provisionr only supports and imports the primary email address of a user. As a workaround, you can configure the secondary email address as an organization attribute in Google or a custom profile attribute in Okta that will be imported with the user profile. You can then use an Identity condition with string matching to access this value for policies. See Orphaned Identities for more information about how Provisionr handles email address mismatches.

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 is based on whatever fields that you organization has configured. Provisionr detects each of these keys automatically and will create a dimension for each one.

Google API Data

Google Documentation for User Profile

{
    "id": "123456789012345678901",
    "primaryEmail": "dade.murphy@redshirt.systems",
    "name": {
      "givenName": "Dade",
      "familyName": "Murphy",
      "fullName": "Dade Murphy"
    },
    "suspended": false,
    "archived": false,
    "creationTime": "YYYY-MM-DDTHH:MM:SS.000Z",
    "lastLoginTime": "YYYY-MM-DDTHH:MM:SS.000Z",
    "deletionTime": "YYYY-MM-DDTHH:MM:SS.000Z",
    "organizations": [
        // We only get attributes from the primary organization
        {
            "department": "Security",
            "title": "Security Engineer",
            "primary": true
        }
    ],
    "relations": [
        {
            "type": "manager",
            "value": "ebelford@reshirt.systems"
        }
    ],
    "orgUnitPath": "/Org Unit/Child Org Unit",
    "includedInGlobalAddressList": true,
}

Google Identity Data

{
    "id": "dridt_01hq8xyzabc123def456ghi789",
    "workspace_integration_id": "wsitg_01hq8xyzabc123def456ghi789",
    "directory_user_id": "drusr_01hq8xyzabc123def456ghi789",
    "vendor_id": "123456789012345678901",
    "email": "dade.murphy@redshirt.systems",
    "profile": {
        "givenName": "Dade",
        "familyName": "Murphy",
        "fullName": "Dade Murphy",
        "email": "dade.murphy@redshirt.systems",
        "department": "Security",
        "title": "Security Engineer",
        "orgUnitPath": "/Org Unit/Child Org Unit",
        "orgUnitSlug": "org-unit/child-org-unit",
        "globalAddressList": true,
    },
    "provisioned_at": "YYYY-MM-DDTHH:MM:SSZ",
    "profile_changed_at": "YYYY-MM-DDTHH:MM:SSZ",
    "last_authenticated_at": "YYYY-MM-DDTHH:MM:SSZ",
    "deprovisioned_at": null,
    "created_at": "YYYY-MM-DDTHH:MM:SSZ",
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
    "state": "active"
}

Okta Profile Data

Provisionr imports the following profile data from each Okta user. The organization metadata is based on whatever fields that you organization has configured. Provisionr detects each of these keys automatically and will create a dimension for each one.

Okta API Data

Okta Documentation for User Profile

{
    "id": "00u1a2b3c4d5e6f7g8h9",
    "status": "ACTIVE",
    "created": "2025-01-28T13:37:00.314Z",
    "activated": null,
    "statusChanged": null,
    "lastLogin": null,
    "lastUpdated": "2025-05-04T03:27:00.066Z",
    "passwordChanged": null,
    "profile": {
        "costCenter": "R&D",
        "department": "Security",
        "division": "Engineering",
        "email": "dade.murphy@redshirt.systems",
        "employeeNumber": "a0308923",
        "firstName": "Dade",
        "handle": "dmurhy",
        "lastName": "Murphy",
        "managerId": "85aacf98",
        "title": "Security Engineer"
    }
}

Okta Identity Data

{
    "id": "dridt_01hq8xyzabc123def456ghi789",
    "workspace_integration_id": "wsitg_01hq8xyzabc123def456ghi789",
    "directory_user_id": "drusr_01hq8xyzabc123def456ghi789",
    "vendor_id": "123456789012345678901",
    "email": "dade.murphy@redshirt.systems",
    "profile": {
        "costCenter": "R&D",
        "department": "Security",
        "division": "Engineering",
        "email": "dade.murphy@redshirt.systems",
        "employeeNumber": "a0308923",
        "firstName": "Dade",
        "handle": "dmurhy",
        "lastName": "Murphy",
        "managerId": "85aacf98",
        "title": "Security Engineer"
    },
    "provisioned_at": "YYYY-MM-DDTHH:MM:SSZ",
    "profile_changed_at": "YYYY-MM-DDTHH:MM:SSZ",
    "last_authenticated_at": "YYYY-MM-DDTHH:MM:SSZ",
    "deprovisioned_at": null,
    "created_at": "YYYY-MM-DDTHH:MM:SSZ",
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
    "state": "active"
}

Slack Profile Data

The Slack integration will be added in an upcoming release. If you would like early access to this integration, please email support@provisionr.io.

GitLab Profile Data

The GitLab integration will be added in an upcoming release. If you would like early access to this integration, please email support@provisionr.io.

Each user has profile metadata — departments, titles, and more. Next, we’ll look at how Provisionr structures this data into Dimensions and Attributes that power policy decisions. Continue reading: Dimensions & Attributes →

Introduction

Concepts

Integration Identities

Source of Truth

Profile Field Mapping

Manager Mapping

Employee ID and Badge ID Mapping

State Mapping

Scheduled Sync Flow

Primary vs. Secondary Identities

Creation and Correlation

Orphaned Identities

New Identities Sync Flow

Existing Identities Sync Flow

State Changes

Deprovisioned Users

Deprovisioned User Retention Period

Scheduled Expiration

Restored Users

Suspended Users

FAQs and Edge Cases

Temporarily Disabling Sync

Multiple Email Addresses and Aliases

Data Schema Reference

Provisionr API Documentation

Provisionr CLI Documentation

Google Profile Data

Google API Data

Google Identity Data

Okta Profile Data

Okta API Data

Okta Identity Data

Slack Profile Data

GitLab Profile Data

Introduction

Concepts

Documentation Index

​Integration Identities

​Source of Truth

​Profile Field Mapping

​Manager Mapping

​Employee ID and Badge ID Mapping

​State Mapping

​Scheduled Sync Flow

​Primary vs. Secondary Identities

​Creation and Correlation

​Orphaned Identities

​New Identities Sync Flow

​Existing Identities Sync Flow

​State Changes

​Deprovisioned Users

​Deprovisioned User Retention Period

​Scheduled Expiration

​Restored Users

​Suspended Users

​FAQs and Edge Cases

​Temporarily Disabling Sync

​Multiple Email Addresses and Aliases

​Data Schema Reference

​Provisionr API Documentation

​Provisionr CLI Documentation

​Google Profile Data

​Google API Data

​Google Identity Data

​Okta Profile Data

​Okta API Data

​Okta Identity Data

​Slack Profile Data

​GitLab Profile Data

Integration Identities

Source of Truth

Profile Field Mapping

Manager Mapping

Employee ID and Badge ID Mapping

State Mapping

Scheduled Sync Flow

Primary vs. Secondary Identities

Creation and Correlation

Orphaned Identities

New Identities Sync Flow

Existing Identities Sync Flow

State Changes

Deprovisioned Users

Deprovisioned User Retention Period

Scheduled Expiration

Restored Users

Suspended Users

FAQs and Edge Cases

Temporarily Disabling Sync

Multiple Email Addresses and Aliases

Data Schema Reference

Provisionr API Documentation

Provisionr CLI Documentation

Google Profile Data

Google API Data

Google Identity Data

Okta Profile Data

Okta API Data

Okta Identity Data

Slack Profile Data

GitLab Profile Data