Skip to main content

Sailpoint SCIM

Learn how to automatically sync users from Sailpoint to Envoy using SCIM.

Overview

If your team uses SailPoint Identity Security Cloud (ISC) for identity governance, you can use this integration to automatically keep your Envoy employee directory up to date. When identities and attributes change in SailPoint, they provision through to Envoy, so you don't have to worry about your Envoy employee directory falling out of sync.

Configuration

Step 1: Install SailPoint in the Envoy dashboard

  1. On the Envoy dashboard, navigate to Integrations page.

  2. Under Directory and SSO, click Directory settings.

  3. Click Install under SailPoint.

  4. Choose how you'd like to sync employees, then click Save:

    • Sync all users: Good for companies with a single location or for those who want the same master Envoy employee directory across all locations.

    • Sync specific users per location: Choose this to sync specific identities to specific locations (creating separate Envoy directories per location).

  5. Take note of your OAuth Bearer Token. You'll paste this into SailPoint in Step Three. You can regenerate a new token later if needed.

Step 2: Create a new SCIM source in SailPoint

  1. In SailPoint ISC, go to Admin > Connections > Sources.

  2. Select Create New.

  3. Search for the SCIM 2.0 source type.

  4. Choose Standard Setup (select Configure, or Actions > Standard Setup).

    1. Use Standard Setup, not Express Setup. Express Setup creates a read-only connection and cannot be used for provisioning.

  5. Enter a unique Source Name and description so admins can tell this source apart from others (for example, "Envoy Directory Sync").

  6. Select a Source Owner responsible for the system. Employee matches display after you type two or more letters.

  7. Choose Direct connection to connect directly to Envoy.

    1. Select a virtual appliance (VA) cluster with connectivity to Envoy.

    2. Leave the Authoritative Source checkbox unchecked — see the Important notes section. Envoy is downstream of SailPoint, not your primary system of record.

  8. Do not enable this source yet.

  9. Select Continue to go to the source configuration page.

Step 3: Connection settings

Now that your source has been created, it's time to configure the connection settings and API connection.

  1. (Optional) Set the Connection Timeout in minutes — the duration of inactivity allowed before the connection terminates. Default is 1 minute.

  2. Enter the Host URL: https://app.envoy.com/scim/v2

  3. Set Authentication Type to API Token.

  4. In the API Token field, paste the OAuth Bearer Token you generated in Envoy (Step One). Only bearer tokens are supported.

  5. Select Save.

  6. Run Test Connection to confirm SailPoint can reach Envoy.

Step 4: Account schema and identity attribute mapping

Map SailPoint identity attributes to the SCIM attributes Envoy expects. At minimum:

Envoy field

SCIM attribute

Email (primary, used to match employees)

userName

First name

name.givenName

Last name

name.familyName

Display name

displayName

Phone number

phoneNumbers

Step 5: Enable Provisioning

By default, new SailPoint sources are read-only. To let SailPoint create, update, and deactivate employees in Envoy, you must enable provisioning:

  1. Open the source you created in SailPoint.

  2. In the Base Configuration page, select Enable Provisioning.

    1. This is one-way and cannot be undone. Converting a read-only source to a deep-governance (provisioning) source is permanent in SailPoint. Sources with the Quick Compliance badge are read-only and cannot be used for provisioning.

Step 6: Assign SailPoint identities/roles to provision into Envoy

Once provisioning is enabled, assign the identities, roles, or access profiles that should be created in Envoy. SailPoint will provision the matching accounts to the Envoy source.

  1. Create or identify the roles/access profiles that grant the Envoy source account.

  2. Assign the identities you want synced (for example, all employees, or a specific population).

  3. Run an account aggregation to load and reconcile accounts.

Navigate back to the Envoy Employee directory > All employees and refresh. Your employees should import automatically. (The first sync may take some time.)

Optional attributes

You can sync additional attributes by adding them to the account schema and mapping them.

Primary Location

Set a user's Primary location via SCIM to fill out occupancy data in Analytics.

  • Display name: Primary Location

  • Attribute name: defaultLocationName

  • External namespace: urn:scim:schemas:extension:envoy:core:1.0:User

  • Data type: string

Manager

Sets the manager field in the Employee Directory and Occupancy Analytics. Envoy only reads the managerDisplayName attribute.

The value mapped to managerDisplayName must be an email, and that person must also be an employee provisioned into Envoy via SCIM. It will not sync for a manually added user or anyone not in the synced population. Disregard the managerID attribute — Envoy does not currently use it.

Remote Status

Sets the Remote Status of the employee in the Employee Directory and Occupancy Analytics.

  • Display name: In person or remote

  • Attribute name: remoteStatus

  • External namespace: urn:scim:schemas:extension:envoy:core:1.0:User

  • Data type: string

Only certain values are accepted. We recommend Remote and In person.

Step 7: Sync Admin roles (Optional, but highly recommended)

Enterprise plans only

Envoy makes it easy to automatically provision admin users from their IdP using SCIM groups.

To sync admins:

  1. Create the groups you need in SailPoint and assign identities to them.

  2. Push those groups to Envoy via the source's group provisioning.

  3. After SailPoint is configured with Envoy, navigate to Employee directory > Admin roles in Envoy.

  4. Click Sync Settings at the top of the page. Under Sync admins, click Get started.

  5. Select the group you want to assign roles to.

  6. Select an Envoy role and one or more locations for each group you want to provision. (The group names are pulled from your IdP.) If the admin role is location-based, select the corresponding location.

  7. Click Add.

  8. Repeat for each group and admin role. Click Done once you've completed mapping.

Admin provisioning FAQ

  • Admins can only have one location role and one company role using SCIM.

    • Location roles:

      • Location admin

      • Front desk admin

      • Deliveries

      • Security admin

    • Company roles:

      • Global admin

      • Billing admin

  • Envoy gives admins the higher role assigned. If a user is in multiple groups mapped to different location roles (e.g., Front Desk Admin and Location Admin), they get Location Admin.

  • Non-custom roles always take priority over custom roles. Assign only one admin role per location.

  • If you already have manual entries in the directory and then sync via SCIM, the sync overwrites them.

  • Synced roles take priority over manual roles only if the synced role has higher-priority permissions.

  • If you disconnect SailPoint, roles convert to manual roles and stop syncing; mappings are not saved.

  • You cannot manually delete synced roles — remove the person from the group in SailPoint first.

Important notes

Token rotation

If you regenerate the OAuth Bearer Token in Envoy, the old token stops working immediately. You must paste the new token into the SailPoint source's connection settings and re-save the source. See the troubleshooting guide below.

Authoritative Source must stay unchecked

Leave the Authoritative Source checkbox unchecked when creating the source. Envoy is a downstream/managed system, not your primary system of record. Marking it authoritative would tell SailPoint to build identities from Envoy data.

Schema changes

If you add a new attribute to the account schema later and it isn't populated after aggregation/provisioning, perform a Discover Source operation and then run an unoptimized account aggregation so SailPoint picks up the change.

Adding / matching employees

When adding or updating employees, Envoy matches on the primary email address (userName). If the email isn't found in Envoy, a new employee is created. If an identity has no primary email, it will not sync.

Troubleshooting

Test Connection fails on /ServiceProviderConfig

Enable Non-Compliant Server mode on the source. When the Non-Compliant checkbox is enabled, the connector only calls /Users (for Test Connection, Preview, Aggregation, and Provisioning) and /Groups (for Aggregation and Provisioning). The /Schemas, /ResourceTypes, and /ServiceProviderConfigs endpoints are then not required. Note that enabling Non-Compliant mode uses the connector's default out-of-the-box schema; any new attribute must be added to the schema with a valid JSON path.

401 errors after regenerating a token

If you regenerated the Bearer Token in Envoy, the SailPoint source still has the old one. Re-paste the new token into the source's API Token field and save.

"ResourceObject is returned with null identity"

Check your identity attribute mapping. Verify that userName is mapped to the employee's email (the identity attribute), and that the identity attribute exists in the schema.

Related Articles
Delinea Integration (fka Centrify)
Okta
Microsoft Entra ID Integration
OneLogin
SCIM Groups for Emergency Notifications
Did this answer your question?