Laurel uses the Microsoft Graph API to capture email and calendar activity from Microsoft Exchange. This guide walks IT administrators through registering an application in Microsoft Entra and granting the required permissions.
Overview
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 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, you can scope the app's access using an Application Access Policy in Exchange Online.
This step is optional. If tenant-wide access is acceptable to your organization, you can skip this section.
⚠️ Note: Microsoft has designated Application Access Policies as a legacy feature, replaced by Role Based Access Control (RBAC) for Applications. Existing policies continue to work, but Microsoft recommends that new configurations use RBAC instead. Both methods are documented below — choose one.
Option A: 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. 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.
Option B: Application Access Policy (legacy method)
🔒 1. Create a Mail-Enabled Security Group
Follow the same group-creation steps as Option A, 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 Option A, 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 or more 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.