Laurel connects to Microsoft 365 through Microsoft Graph to capture email and calendar activity. This guide is for the IT administrators responsible for configuring that connection.
Application permissions are Laurel’s standard setup for most firms. Your IT team manages access centrally and can restrict it to selected mailboxes.
For Exchange Server installations hosted by your firm, use Exchange Server (on-premises) Configuration for Laurel.
Standard setup: application permissions
You will complete 4 steps in Entra via your Azure Portal (https://entra.microsoft.com):
Create an App Registration
Generate a client secret
Grant required API permissions
Share credentials securely with your Laurel Implementation team, or enter them directly within Laurel's Admin settings
Step 1: Create an App Registration
Sign in to https://entra.microsoft.com.
In the left-hand Entra ID menu, click App registrations.
In the top menu, click + New registration.
Name the application
Laurel - Exchangeand click Register.
Step 2: Generate a Client Secret
In your new app registration, go to Certificates & secrets
Click +New client secret and set the following values:
Description:
laurel-secret-1Expires:
24 months
Click Add.
Immediately copy and securely store the secret value — it will not be visible again after you leave this page.
⚠️ Important: Note the expiration date and add a reminder to your calendar. If the secret expires before it is renewed, your users will lose time data that cannot be recovered even after the connection is restored.
Step 3: Grant Required API Permissions
In your app registration, go to API permissions > Add a permission > Microsoft Graph > Application permissions.
Search for and select each of the following permissions:
Permission | Type | Purpose |
| Application | Capture email activity |
| Application | Capture calendar events |
| Application | Identify users in your tenant |
3. Click Add permissions.
4. Click Grant admin consent for [your organization] and confirm. All permissions should show a green Granted status.
Note: If you are not an Entra admin, you will need to request that an admin grants consent.
Step 4: Share Credentials with Laurel
Once configuration is complete, either:
Share securely with your Laurel Implementation team, or
Enter directly in Laurel's Customer Integration settings after you've been assigned Super Customer Admin or System Admin permissions.
You will need to provide the following credentials to activate the integration (found under the Overview tab of your app registration):
Application (client) ID
Directory (tenant) ID
Client secret value
Client secret expiration date
Optional: Restricting Laurel's Access to Specific Users
By default, the Application permissions granted in Step 3 (Mail.Read, Calendars.Read) allow the Laurel app to access all mailboxes in your tenant. If you'd like to limit Laurel's access to only the users whose activity should be collected, there are two supported methods — choose one:
RBAC for Applications — Microsoft's recommended method. ⚠️ RBAC grants are additive to the Entra permissions from Step 3: this method only takes effect once you also remove the Mail.Read and Calendars.Read Application permissions from the Entra app (Step 6 below). See Microsoft's FAQ.
Application Access Policy — a legacy method that Microsoft is replacing with RBAC. Existing policies keep working, and unlike RBAC, a policy restricts access even while the Step 3 permissions remain granted.
This step is optional. If tenant-wide access is acceptable to your organization, you can skip this section.
RBAC for Applications (Microsoft's recommended method)
🔒 1. Create a Mail-Enabled Security Group
Browse to https://admin.microsoft.com and go to Teams & groups > Active teams and groups.
Select the Mail-enabled security tab and click Add a mail-enabled security group.
Name the group LaurelExchangeAccess, assign an owner, and add the users whose email and calendar activity Laurel should collect.
Note: The group must be mail-enabled. A standard security group will not work for scoping Exchange access.
🔧 2. Connect to Exchange Online PowerShell
Open PowerShell as Administrator and run:
powershell
Install-Module ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline
Sign in with an account that holds the Exchange Administrator or Global Administrator role.
🧩 3. Register the Service Principal in Exchange Online
You'll need two values from the Laurel app: the Application (client) ID (from the app registration's Overview tab) and the Object ID of the Enterprise Application (found in Entra under Enterprise applications > Laurel - Exchange — note this is different from the app registration's Object ID).
powershell
New-ServicePrincipal -AppId "<Application (client) ID>" -ObjectId "<Enterprise Application Object ID>" -DisplayName "Laurel - Exchange"
🎯 4. Create a Management Scope for the Group
powershell
$group = Get-DistributionGroup "LaurelExchangeAccess"
New-ManagementScope -Name "LaurelUsersScope" -RecipientRestrictionFilter "MemberOfGroup -eq '$($group.DistinguishedName)'"
🔑 5. Assign the Scoped Roles to the App
powershell
New-ManagementRoleAssignment -App "<Application (client) ID>" -Role "Application Mail.Read" -CustomResourceScope "LaurelUsersScope"
New-ManagementRoleAssignment -App "<Application (client) ID>" -Role "Application Calendars.Read" -CustomResourceScope "LaurelUsersScope"
🧹 6. Remove the Tenant-Wide Permissions from Entra (required)
In Entra, go to App registrations > your Laurel app > API permissions and remove Mail.Read and Calendars.Read (keep User.Read.All). The Entra permissions and the RBAC roles act as a union: while Mail.Read and Calendars.Read remain admin-consented, the scope from Step 5 has no effect and Laurel can still access every mailbox. Removing them doesn't interrupt access for group members — the role assignments from Step 5 carry it.
After removing them, check the Other permissions granted for [your tenant] section on the same API permissions page. If Mail.Read and Calendars.Read still appear there, the admin consent is still active — revoke it from that section (⋯ menu > Revoke admin consent). Both permissions must be gone from both lists before the scope takes effect.
✅ 7. Verify
powershell
Test-ServicePrincipalAuthorization -Identity "<Application (client) ID>" -Resource "user@yourdomain.com"
The output shows whether the app's access to that mailbox is InScope.
Note: Test-ServicePrincipalAuthorization checks only the Exchange RBAC assignment — it reports InScope: False for a non-group user even while the Step 3 Entra permissions still grant access. It also bypasses the propagation cache, so confirm actual behavior (e.g. a test email from an excluded user) after allowing up to 2 hours.
Application Access Policy (legacy method)
🔒 1. Create a Mail-Enabled Security Group
Follow the same group-creation steps as RBAC for Applications, Step 1. The group must be mail-enabled — Application Access Policies cannot be scoped to standard security groups.
🔧 2. Connect to Exchange Online PowerShell
Follow RBAC for Applications, Step 2.
🧩 3. Create the Application Access Policy
This policy restricts which mailboxes the Laurel app can access via Microsoft Graph. With RestrictAccess, the app can only access mailboxes belonging to members of the group — all other mailboxes in the tenant are denied.
powershell
New-ApplicationAccessPolicy -AppId "<Application (client) ID>" -PolicyScopeGroupId LaurelExchangeAccess@yourdomain.onmicrosoft.com -AccessRight RestrictAccess -Description "Restrict Laurel access to members of LaurelExchangeAccess"
Parameters:
-AppId → The Application (client) ID of the Laurel - Exchange app registration (from Step 1 of this article).
-PolicyScopeGroupId → The email address of the mail-enabled security group.
-AccessRight → Use RestrictAccess to grant access only to group members and deny all others.
-Description → Optional note describing the policy.
✅ 4. Verify the Policy
powershell
Test-ApplicationAccessPolicy -Identity user@yourdomain.com -AppId "<Application (client) ID>"
The AccessCheckResult field will show Granted for group members and Denied for everyone else.
👤 5. Manage Access Going Forward
Laurel will only have access to the email and calendar data of users in the security group. Adding or removing users from LaurelExchangeAccess grants or revokes Laurel's access to their data — no further PowerShell changes are needed.
🧠 Notes & Tips
Policy and role-assignment changes can take 30 minutes to 2 hours to propagate. If a test shows unexpected results immediately after setup, wait and re-test before troubleshooting.
Both methods scope access to Exchange data (email and calendar) only. The User.Read.All permission used to identify users in your tenant is not affected.
If you use the group-based scoping above, make sure every user whose time data should be captured is in the group before their activity begins — Laurel cannot retroactively collect data from periods when it had no access.
If you copy commands from this article, ensure your editor doesn't convert straight quotes (") into curly quotes (" "), which will cause PowerShell errors.