Skip to main content

Okta

Use Okta to automatically sync employees into your Envoy directory.

Updated over 6 months ago

How does Okta work with Envoy?

If your team uses Okta for employee provisioning, you can use this app to keep your Envoy employee directory up to date automatically. The SCIM push-based system treats the Okta directory as your source of truth. When changes are made in Okta, they push immediately to Envoy, so you don’t have to worry about the Envoy employee directory being out of sync with Okta.

You can manually create new employees or add employees from other locations while maintaining your directory sync. This feature is helpful for contractors, temps, or other people who may host visitors/receive deliveries but are not core team members. Learn more about manually adding employees.

To learn more about single sign-on, read our SAML guide.

The SCIM standard enables advanced provisioning in order to automate user lifecycle management for an application, including account creation, profile updates, authorization settings, and account deactivation.

Supported Features

  • Create users

  • Update user attributes

  • Deactivate users

  • Group push

  • Optional attributes: Manager, Primary Location, In-person/remote

Envoy + Okta Configuration

You’ll need to be an admin on your Okta account and a Global Admin in Envoy to complete this setup.
​
To learn more about Okta’s administrator role structure, please view their admin guide. Either become an admin or ask your admin in IT for help before completing these steps.
​
​Warning: If configuring the Envoy app in the EU or any other region using Envoy.com, please only select your region as "US" to utilize OKTA. Provisioning and SAML functionality will not work if EU is selected in the Envoy app within OKTA.

Setting up your Envoy.eu instance? Please see our EU documentation.

Employee provisioning

Step One: LCM

Make sure you have LCM in Okta and your employees are setup to use it as a directory application in Envoy.
​

You’ll also need to have Okta application administrator privileges or higher to complete this setup.

Step Two: Prepare to enable Envoy with Okta

Decide whether you’d like to sync all users to all locations or sync specific users per location. This will impact how you set up the app.

  • Sync all users: This is good for companies with one location, or if you prefer to have the same master Envoy employee directory at all locations within your company.

  • Sync specific users per location: Choose this option if you’d like to sync certain Okta users to certain locations (i.e., creating different Envoy employee directories per location). You can filter employees by location in Envoy based on available filters sent from Okta, which are currently “city” and “locale.”

Step Three: Enable Envoy + Okta

  1. On the Envoy dashboard, go to your Apps page.

  2. Under Directory and SSO, click Directory settings.

  3. Click Install under Okta.

  4. Choose from one of the two following options for syncing employees to your directory.

    1. Sync all users:

    2. Sync specific users per location:

  5. Take note of your OAuth Bearer Token. You will need to add this to Okta in the next step. You can always Regenerate a new token if needed.

Step Four: Configure Okta settings

The bearer token must be pasted into Okta before provisioning groups/users to the Envoy application! If you assign groups and users to Envoy before pasting the token, the initial sync will not run. You can resolve this by unassigning and re-assigning the users and groups.

  1. In your Okta account, request a new application for Envoy. To do this, you’ll need to be an Okta admin.  Navigate to Applications > Applications > Browse App Catalog.
    ​

  2. Select the latest version of the Envoy Application

  3. Click Add Integration

  4. General Settings:

    1. ✨Only choose the US region even if located in the EU or the SCIM integration will not work.✨

    2. You can also change the label or manage application visibility here
      ​

  5. Select Done

  6. From the Envoy application, go to the Okta provisioning page, and click Configure API Integration.
    ​

  7. Copy the OAuth Bearer Token from Envoy and enter it in the API Token field in Okta.

  8. Check the Enable API Integration

  9. Test API connect > Save.

    1. Make sure that “Create Users,” “Update User Attributes,” and “Deactivate Users” are all set to enable (box checked).

    1. Click “Save” at the bottom of the Okta provisioning page. 

      1. ✨Paste the bearer token into Okta before provisioning groups/users to the Envoy application!✨

  10. ​Go to the Okta groups page.

  11. Click “Assignments,” and select all employees or groups you’d like to sync to the Envoy employee directory.

    1. We recommend selecting “Everyone,” but you can also assign individual employees from the Okta people page.

  12. Navigate back to the Envoy Employee directory > All employees and refresh. Your employees should have imported automatically. (This can take ~30 minutes for the first sync)

Optional Attributes:

Primary Location

Set a user's Primary location via SCIM. Setting a user's primary location will help fill out valuable occupancy data in the Analytics section.

Primary location does not affect which location the employee will first see when logging in. It is for analytic purposes only.

Manager

This will set the manager field in the Employee Directory and Occupancy Analytics.
​

Remote Status

Set the Remote Status of the employee within the Employee Directory and Occupancy Analytics.
​


Adding the Attributes (Primary Location and Remote Status):

  1. Select Applications from the left sidebar, then select Envoy (SCIM 2.0). Under the Provisioning tab, scroll to Envoy (SCIM 2.0) Attribute Mappings and select Go to Profile Editor.

  2. Select Add Attribute:

    1. For Primary Location

      1. Data type = string

        1. Display name: Primary Location

        2. Variable name: defaultLocationName

        3. External name: defaultLocationName

        4. External namespace: urn:scim:schemas:extension:envoy:core:1.0:User
          ​

  3. Click Save or Save and Add Another for Remote Status

    1. For Remote Status

      1. Data type = string

      2. Display name = In person or remote

      3. Variable name = remoteStatus

      4. External name = remoteStatus

      5. External namespace = urn:scim:schemas:extension:envoy:core:1.0:User

  4. Click Save
    ​

Manager will already be added and mapped. However, the mappings must be changed in order for manager to function correctly. Envoy only looks at the managerDisplayName attribute. You can choose whichever field in Okta you wish to map to managerDisplayName, but the mapped value must be an email and must also be an employee who is also assigned the Envoy app in Okta.

Disregard the managerID attribute in Envoy. This field is not currently used by Envoy.

Add mappings

  1. In the Envoy enterprise application in OKTA, go to Provisioning

  2. Scroll down to Envoy (SCIM 2.0) Attribute Mappings


    ​

  3. At the bottom of the list, click Show Unmapped Attributes

Primary Location Mapping

  1. Select the edit (pencil) option next the Primary Location attribute

    1. Attribute value = Map from Okta Profile

    2. In the new dropdown, select whichever field from the employee profile you wish to map to Primary location. This must be a string.

      1. In the example below, we mapped the city field in OKTA.

    3. In Apply on, select Create and update

    4. Click Save

Manager Mapping

  1. In the list of attributes, locate the attribute managerDisplayName

  2. The attribute will already be mapped. Please change the mapping to the desired field (string) on the Okta profile. This value must be an email and must also be an employee who is also assigned the Envoy app in Okta.
    ​

The Manager field in Envoy can only be mapped to a user that is being synced via SCIM. It will not sync if you use the email of a manually added user or a user that is not added to the employee directory via Okta.

Remote Status Mapping

  1. In the list of attributes, locate the remoteStatus field.

  2. Add a mapping to the attribute of your choice. The value of the mapped attribute must match the remoteStatus accepted values listed below.
    ​

Only certain values will be accepted for remote status - we encourage using Remote and In person. Please see the following table for other values that can be used to map Remote status. We recommend using the "Office location" field if this is not already populated in OKTA user profiles.

Accepted Value in OKTA

Envoy

remote

working from home

wfh

Remote

in person

telecommuting

in-office, in office

on-site, on site, onsite

office-based, office based

hybrid

flexible

blended

In person
​

Defining Primary Locations in Envoy

  1. In Envoy, navigate to Employee Directory > Sync settings.

  2. Next to Primary location, select Get started, then Start sync.

  3. Once your Okta instance syncs with Envoy, you'll need to define which locations are mapped to which defaultLocationName attribute. Exact location matches will automatically be assigned to the corresponding Envoy location.

  5. Click Save once you have appropriately defined primary locations.

In order to sync the new attributes to Envoy, please click the "Force Sync" button at the top of the mapping section under the Provisioning tab.
​

Important notes:

Adding employees

  • When updating or adding employees, Envoy will match based on the primary email address listed for the Okta user. If the primary email address is not found in Envoy, a new employee will be added to the Envoy employee directory.

Employee contact information

  • The primary email address and phone number listed in Okta will be the email address and phone number listed in the Envoy employee directory.

  • If an Okta user does not have a primary email address, they will not be synced to the Envoy employee directory.

Syncing Per Location

  • Envoy can sync employees to certain locations. Employees can by sorted by Locale (<locale>) or City (<locality>)

  • The locality attribute in Envoy refers to City within the Envoy dashboard.

    • For example, in the OKTA mappings, <user.city> in OKTA would map to <locality> in Envoy (see screenshot below)

  • The <user.locale> attribute would map to <locale> in Envoy.

Locale has specific naming conventions in Okta. To map locale to Envoy, the locale attribute in Okta profile should be in the proper format. Valid values for the 'locale' property are a concatenation of the ISO 639-1 two-letter language code, an underscore, and the ISO 3166-1 2 letter country code (e.g., en_US).

Adding Envoy Assistants from Okta

  1. Go to your Okta Directory.

  2. Select the employee to which you’d like to assign an assistant.

  3. Go to their Profile tab and click “edit.”

  4. Scroll all the way to the bottom; find Assistants, and click “Add another.”
    ​

✨If the Assistants field isn’t already part of your Okta user profile, you must add this field to support syncing assistants via user provisioning. Here’s how: In Okta, go to Directory > Profile Editor > Okta and click Profile. Click Add attribute. Set up the Assistants profile attribute as a string array, as depicted below. ✨
​

  1. Type in the assistant’s email address, and click Save.

    1. If you need to add multiple assistants, repeat steps four and five.

  2. Go to the Applications tab and select Envoy application.

  3. Click Provisioning and scroll down to Show Unmapped Attributes.

  4. Select pen to edit assistants, set Attribute value equal to "Expression," enter user.assistants into text field, and assign radio button to “create and update” for Apply On.

  5. Check your Envoy employee directory, and your assistants should be automatically assigned.

Note: If you plan to assign assistants manually within the web dashboard, please reach out to Envoy Support prior to setting up SCIM syncing to configure this on your account.


Troubleshooting Okta

Viewing your system logs

The System Log contains details of all logged events for your org. These are super helpful when troubleshooting any issues you might have when attempting to sync your directory with Envoy.

  1. In the Admin Console, go to Reports > System Log.

    1. For a description of System Log event types, see Event Types (Okta resource).

The events table lists all events and includes information about time, actor, target, and more.
​
​Okta documentation for viewing logs

Users not pulling through

If you notice that your users are not syncing to the Envoy Employee Directory, go to the Assignments tab, remove all groups/users assigned, then add them back.
​
​This will kickstart the sync and you should start to see users within ~5 minutes.

Still not syncing

  1. Go into your Okta Envoy application instance and remove all users/groups from the Provisioning tab

  2. Then, on the Envoy web dashboard, go to Envoy Apps > Directory & SSO > Click Configure on Okta > Click Regenerate token

  3. Go back to Okta's Envoy application > Provisioning tab > Integration section > Edit > and paste the new bearer token.

  4. Go into "To App" and re-add all users/groups

✨You should see your employees in Envoy's Employee directory within 30 minutes.✨

Assistants do not appear in Envoy even though they are mapped

  1. Ensure that the assistant is also in the users being provisioned into Envoy

  2. Go to the Profile editor on Okta's provisioning page and click the pencil icon on the Assistants expression, it should look as follows:
    ​

  3. You will want to be sure that the Variable name and the External namespace look like the above screenshot.

    1. The Variable name will be slightly different but be in the format of envoy_xxxxxx.assistants

  4. If the Variable name does not look like the above screenshot, your assistant mapping will not send assistants to Envoy. Please de-activate Envoy in Okta and re-generate your OAuth Bearer Token in Envoy (Apps > Directory and SSO > Configure on Okta > Regenerate token)

  5. Follow the steps listed here to set up a new instance of Envoy in Okta.

Admin Provisioning

Envoy makes it easy for Enterprise customers to automatically provision their admin users from Okta using SCIM groups.

IMPORTANT NOTES:

  1. If you are not using Envoy (SCIM 2.0) in Okta, please upgrade the application.

  2. To check which version of Envoy you are using or to upgrade your app, navigate to Applications > Browse app catalog in your Okta account and search for Envoy (SCIM 2.0).

  3. Click Add Integration in the top right (if you do not have this installed already.

  4. Be sure to configure the Envoy (SCIM 2.0) app in exactly the following order:

    1. General settings

      1. Set the application label and click next.

    2. Sign-On Options

      1. Click SAML 2.0.

      2. Click view setup instructions.

      3. Follow the setup instructions. Note: this will prevent users from signing in until provisioning and assignment is complete.

    3. Set up provisioning (BEFORE assigning any users and/or groups to app)

      1. Click the Provisioning tab.

      2. Click Configure API integration.

      3. Enable the API integration checkbox.

      4. Go to the Envoy dashboard to get the OAuth bearer token with the following steps.

        • Go to envoy dashboard → Click Apps in the left nav → Click the Directory/SSO tab → Click ‘configure’ under the Okta app.

        • Copy OAuth Bearer Token.

      5. Paste in OAuth Bearer Token in Okta.

      6. Click ‘Test API credentials’.

      7. If successful, click Save.

      8. Click the Edit button (to the right of ‘Provisioning to App’ header)

      9. Click enable for Create, Update and Deactivate checkboxes and then click save.

    4. Set up assignments

      1. Click the Assignments tab.

      2. Click Assign.

      3. Assign people or groups.

    5. Deactivate previous Envoy 1.1 app in Applications/Applications

      1. On old app instance, go to Provisioning tab → Settings → API.

      2. Click on Edit and uncheck Enable API Integration. Click Save.

      3. Go ahead and deactivate the old AppName app instance.

Sync admins

  1. Create groups as needed in Okta and assign users to those groups. Here’s additional information on how to create groups in Okta.

  2. Use Group Push to push the Okta groups to Envoy. Here’s additional information on how to push groups in Okta.

  3. Sync your directory with Envoy. You can follow these instructions, if you have not already set up your integration with Envoy.

  4. After you've configured Okta with Envoy, navigate to Employee directory > Admin roles.

  5. Click on Sync Settings at the top of the page.

  6. Under Sync admins, select the group you want to assign roles to.

  7. Select an Envoy role and one or more location from the dropdown menu for each group you want to provision. (The list of group names are pulled from Okta.)

  8. Click Add > Done.

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 will give admins the higher role assigned. For example, If a user is in multiple groups in Okta and each group is mapped to two different location roles (Front Desk Admin and Location Admin), then the admin will be assigned the Location Admin role.

  • Non-custom roles will always take priority over custom roles. Employees should only be assigned one admin role per location. If multiple admin roles are assigned to one employee, the non-custom role will take priority.

    • For example, if an employee is assigned a Front Desk admin role, but then also assigned a custom role with more permissions than a Front Desk Admin, the employee will retain only the original Front Desk Admin permissions.

  • If you already have manual entries in the directory and sync with a SCIM, this will take over and delete the manual entries.

  • Synced roles will take priority over manual only if the synced role has higher priority permissions. If you have a front desk admin role (manual) and you are SCIM mapped to the security admin role, you will still have a manual front desk admin role for that location.

  • If you disconnect Okta, your roles will turn into manual roles and will stop syncing. Your mappings won't be saved and you will start from scratch the next time you sync with a SCIM.

  • You cannot manually delete synced roles. You must remove that person from the Okta group first.

  • If you are not seeing the roles you are looking for, be sure to check the filters at the top of the page.

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