Note: This was previously named "Azure AD."

How does Entra ID work with Envoy?

The Entra ID (formally known as Azure Active Directory) integration allows for real-time employee provisioning through Entra utilizing SCIM API.

With Envoy + Entra ID, Envoy will allow employee provisioning and Single Sign-On (SSO) by utilizing the Envoy Enterprise app within Entra ID's portal.

Entra ID is available on Microsoft GCC High (Government Community Cloud) accounts and GCC High is compatible with our Entra ID directory integration.

Please be aware that Entra ID does not support the assistant feature of Envoy. If you would like to use assistants in Envoy manually, please alert Support to whitelist your account.

Employee Provisioning

Entra ID account and employee setup

Make sure your Entra ID account is created and that you have added your employees to it. Create groups as needed in Entra and assign users to those groups.

To complete this installation, you’ll need to have admin privileges. Either become an admin or ask your admin for help before completing these steps.

Step 1: Enable Envoy + Entra ID

On the Envoy dashboard, go to your Integrations page.
Under Directory and SSO click on Directory Settings.
Click Install under Microsoft Entra AD.
Choose from one of the following options for syncing employees to your directory and click Save:
1. 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.
2. Sync specific users per location: Choose this option if you’d like to sync certain users to certain locations (i.e., creating different Envoy employee directories per location).
Copy the OAuth Bearer Token from Envoy and note to be entered into Entra later.

Step 2: Connect Entra ID to Envoy

Open the Entra portal and select Applications > Enterprise applications > New application > Add from the gallery > search for Envoy and select Add.
You should land on the Overview (preview) page. Under Create configuration, click on Connect your application.
Copy Envoy’s SCIM endpoint https://app.envoy.com/scim/v2 and paste it into the Tenant URL field.
Paste the OAuth Bearer Token copied from the Envoy Dashboard.
1. Note: Tenant URL above is for new instances; if existing, do not update.
Click on Test Connection, and once successful, click Create.

Step 3: Map user attributes

In addition to the required user attributes (name, email, phone number), Envoy uses optional user information to enhance the platform's functionality. For example, Emergency notifications uses primary location to send alerts to the employees who may be directly impacted by critical events.

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 reports and populate emergency notification recipient data.

Manager

This will set the manager field in the Employee Directory and Occupancy, and Attendance reports. Managers can also access their reports' attendance data without needing any admin permissions.

Remote Status

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

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 Entra user profiles.

Accepted Value in Entra	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

Example of Office location used for Remote status:

Adding Attributes

Each optional attribute will require the creation of a custom Envoy attribute within Entra ID.

Go to Enterprise Applications, search for your application > select Envoy.
In the left sidebar, go to Provisioning. Under Manage Provisioning, select Edit attribute mappings > expand the Mappings section > Provision Microsoft Entra ID Users.
Scroll down and select Show Advanced options.
Select Edit attribute list for Envoy.
1. Note: if this option is not available and instead, there are links to request additional attributes for Envoy and Microsoft Entra ID, restart the process from this link. More info here. You'll want to access the link in a new window after logging in or an incognito/private window.
Scroll down to the bottom of the list and create a new attribute. The name, type, and Referenced Object Attribute (only for Manager) must exactly match the descriptions below:
1. For Primary Location
  1. Name = urn:ietf:params:scim:schemas:extension:envoy:core:1.0:User:defaultLocationName
  2. Type = String
2. For Manager
  1. Name = urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.value
  2. Type = Reference
  3. Referenced Object Attribute: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
3. For Remote Status
  1. Name = remoteStatus
  2. Type = String
Click Save and confirm. Now that these additional attributes have been added, we can map them to their corresponding fields.

Entra ID will not include custom attributes on POST create user requests unless they are fully qualified with IETF-compliant URN (though they currently will send the custom attributes on subsequent PATCH update requests).

How to map attributes:

Navigate to Provisioning > Mappings > Microsoft Entra ID Users.

If you added custom directory fields (reccomended), now you can map them. If not, you can skip to confirming standard attribute mapping.

Mapping custom attributes

From the Provision Microsoft Entra ID Users mapping page, select Add New Mapping in the list of attribute mappings:
1. For Primary Location:
  1. Mapping type: Direct
  2. Source attribute: city (or whichever attribute you choose to map)
  3. Default value if null (optional): leave empty
  4. Target attribute: urn:ietf:params:scim:schemas:extension:envoy:core:1.0:User:defaultLocationName
  5. Match objects using this attribute: No
  6. Matching precedence: leave empty
  7. Apply this mapping: Always
2. For Manager
  1. Mapping type: Direct
  2. Source attribute: manager
  3. Default value if null (optional): leave empty
  4. Target attribute: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.value (this is the attribute just created in Envoy)
  5. Match objects using this attribute: No
  6. Matching precedence: leave empty
  7. Apply this mapping: Always
3. For Remote Status
  1. Mapping type: Direct
  2. Source attribute: {{whichever attribute you are choosing to use}}
    If using the Office location field in Entra, then it would be "physicalDeliveryOfficeName"
  3. Default value if null (optional): leave empty
  4. Target attribute: urn:ietf:params:scim:schemas:extension:envoy:core:1.0:User:remoteStatus
  5. Match objects using this attribute: No
  6. Matching precedence: leave empty
  7. Apply this mapping: Always
Click Ok > Save and confirm.

Confirm standard attribute mapping

In order to function as intended, Envoy relies on attributes to map correctly from Entra. Confirm the following match:

Envoy Attribute	Entra ID Attribute
userName	userPrincipalName
title	jobTitle
emails[type eq "work"].value	mail
addresses[type eq "work"].locality	city
locale	city

Step 4: Provision Users and groups

Now that you've connected Entra ID to Envoy, created and mapped attributes, you can provision users.

Click Users and groups on the left-hand side, then assign users or groups to the application.
1. Entra ID does not support nested groups for SCIM provisioning.
Once users are assigned, click on Provisioning on the left hand side and scroll down to the bottom and turn Provisioning Status On.
1. (Optional) To test provisioning on a single user, utilize the Provision on demand feature in Entra ID.

Mapping Custom Attributes

After you create the custom attributes, you'll need to add mappings.

From the Provision Microsoft Entra ID Users mapping page, select Add New Mapping in the list of attribute mappings:
1. For Primary Location:
  1. Mapping type: Direct
  2. Source attribute: city (or whichever attribute you choose to map)
  3. Default value if null (optional): leave empty
  4. Target attribute: urn:ietf:params:scim:schemas:extension:envoy:core:1.0:User:defaultLocationName
  5. Match objects using this attribute: No
  6. Matching precedence: leave empty
  7. Apply this mapping: Always
2. For Manager
  1. Mapping type: Direct
  2. Source attribute: manager
  3. Default value if null (optional): leave empty
  4. Target attribute: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.value (this is the attribute just created in Envoy)
  5. Match objects using this attribute: No
  6. Matching precedence: leave empty
  7. Apply this mapping: Always
3. For Remote Status
  1. Mapping type: Direct
  2. Source attribute: {{whichever attribute you are choosing to use}}
    If using the Office location field in Entra, then it would be "physicalDeliveryOfficeName"
  3. Default value if null (optional): leave empty
  4. Target attribute: urn:ietf:params:scim:schemas:extension:envoy:core:1.0:User:remoteStatus
  5. Match objects using this attribute: No
  6. Matching precedence: leave empty
  7. Apply this mapping: Always
Click Ok > Save and confirm.

Primary Location: Assigning location values in Envoy

After the SCIM attributes are set for Primary location, the location values must be assigned to specific locations in the Envoy Dashboard.

Location names that exactly match the name on the SCIM attribute will automatically map.

In Envoy, navigate to Employee Directory > Sync settings.
Next to Primary location, select Get started, then Start sync.
Once your Entra ID 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.
Click Save once you have appropriately defined primary locations.

✨ Note: Once a value is added through SCIM and is used to create primary location mapping, Envoy keeps the mapping even if no active users have it. If you need an old value removed, please reach out to Support at [email protected]. ✨

Important Notes:

Phone Number:

Envoy is in the process of updating our official documentation Envoy app within the Microsoft Entra ID store. If you want Mobile phone instead of Office phones please change the following within Entra ID.

Navigate to the Envoy Enterprise App > Provisioning > Mapping and click on Provision Entra Users.
Find and delete telephoneNumber from the mapping list.
Find mobile and click onto it so it brings up the editing pane.
Change the mapping to phoneNumbers[type eq "work"].value.

Configuring Single Sign On

In order for a user to log in to the Envoy dashboard via SSO, the UPN email address must match the email address in the Envoy employee directory.

In the Envoy dashboard go to Integrations > Directory and SSO and click Directory settings and then click Install on the SAML integration.
In the Entra ID portal, on the Envoy application page, select Single sign-on.
On the Select a Single sign-on method dialog, select SAML to enable single sign-on.
On the Set up Single Sign-On with SAML page, click the edit icon to open the Basic SAML Configuration dialog.
On the Basic SAML Configuration section, enter the following URLs:
1. Identifier (Entity ID)- https://app.envoy.com/a/saml/metadata
2. Reply URL (Assertion Consumer Service URL) - https://app.envoy.com/a/saml/consume
3. Sign on URL - https://app.envoy.com/a/saml/auth/xxxx, your specific sign on URL will be found in Apps > Directory and SSO > Configure SAML.
4. Relay State - https://dashboard.envoy.com/
Once all URL’s are entered correctly, hit “Save”.
In the SAML Signing Certificate section, click the edit icon to open SAML Signing Certificate dialog.
In the SAML Signing Certificate section, copy the Thumbprint and save it on your computer.
On the Set up Envoy section, copy the Login URL. This URL is what you will enter into the Envoy integrations page for SAML as your “IDENTITY PROVIDER HTTP SAML URL”.
Login to your Envoy dashboard and go to your Integrations page and “Install” SAML.
Take the Thumbprint from step 3 in Entra ID of the setup and enter that value into the Fingerprint field provided in Envoy.
Paste the Login URL value, which you have copied from the Entra ID portal into the IDENTITY PROVIDER HTTP SAML URL text box.
Choose whether you want SAML Required and toggle ON if needed, then Save.

Admin Provisioning

Envoy makes it easy for our Visitors Enterprise and Workplace Premium Plus customers to automatically provision their admin users using Entra ID.

Sync admins

Create groups as needed in Entra ID and assign users to those groups.
1. Assign the group to the Envoy app
  1. Navigate to Home → Enterprise applications → select Envoy app
  2. Click `Add user/group`
  3. Click the `None Selected` link under Users and groups
  4. Search for your group and select it
  5. Click `Assign`
2. Now provision the group to Envoy (Optional, do this if you want to have immediate access to the groups in Envoy. Otherwise the groups will get provisioned on the pre-defined schedule)
  1. Navigate to Home → Enterprise applications → select Envoy app
  2. Click provisioning
  3. Click provision on demand
  4. Search for and select your group, select the members you’d like to be included, then click the Provision button
3. Here’s additional information on how to create groups in Entra ID.
Sync your directory with Envoy. You can follow these instructions, if you have not already set up your integration with Envoy.
After you've configured Entra ID with Envoy, navigate to Employee directory > Admin roles.
Click on Sync Settings at the top of the page.
Under Sync admins, select the group you want to assign roles to.
Select an Envoy role and one or more location from the dropdown menu for each group. (The list of group names is pulled from Entra ID.)
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 Entra ID (fka Azure) 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 Entra ID, 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 Entra ID 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.

Troubleshooting

Users are not being synced into all Envoy locations or users are missing custom attributes

If your Entra ID users are not syncing into all locations as they should, try manually re-provisioning your users. Please note the order is important.

Unassign the users and groups from the Envoy app within Entra ID.
Go to the Envoy Dashboard > Employee directory > Sync Settings
Regenerate the secret token.
Go back to the Envoy app in Entra ID > Provisioning > Admin Credentials and enter the token in Secret Token field.
Test the token and make sure you get a success message.
Reassign the users and groups.

This should kick-start the provisioning of users and any new attributes assigned.

Delinea Integration (fka Centrify)

Okta

OneLogin

SCIM Groups for Emergency Notifications

Entra ID Auto Check-in for Workplace

Microsoft Entra ID Integration