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.

Employee Provisioning

Entra ID account and employees setup

Make sure you have your Entra ID account created, and you have added your employees to your account. 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 Apps 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: Configure Entra ID

Open the Entra portal and select Applications > Enterprise applications > New application > Add from the gallery > search for Envoy and select Add.
Open the Provisioning tab and set Provisioning Mode as Automatic.
Copy Envoy’s SCIM endpoint https://app.envoy.com/scim/v2 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 Save.
Click on Users and groups on the left hand side and then assign users or groups to the application.
1. Entra ID does not support nested groups for SCIM provisioning.
2. Configure any optional attributes (primary location, manager, remote status) before assigning users and groups.
Once users are assigned, click on Provisioning on the left hand side and scroll down to the bottom and turn Provisioning Status On.
(Optional) To test provisioning on a single user, utilize the Provision on demand feature in Entra ID.

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

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.

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:

Adding the Attributes

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

Go to Microsoft 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 = 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.

Azure AD 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).

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.

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 the Envoy dashboard go to Apps > 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 Apps 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.

Configuring assistants

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.

Admin Provisioning

Envoy makes it easy for our Visitors Enterprise and Workplace Premium Plus customers to automatically provision their admin users using Entra ID (formerly known as Azure).

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 token.
Go back to the Envoy app in Entra ID > Provisioning > Enter and enter the token in Admin Credentials
Test the token and make sure you get a success message.
Reassign the users and groups.