imper.ai

Appearance

Scoping Microsoft 365 Calendar Access to a Security Group

This guide applies to imper.ai for Hiring, where interviews are scheduled in Microsoft 365 or Outlook.

To secure an interview, imper.ai needs Calendars.ReadWrite on your tenant - to see the scheduled interview, and to attach the candidate's verification link to it. Granted through the standard consent flow, it applies to every mailbox in your tenant, and Microsoft offers no way to narrow it at consent time.

This guide shows how to restrict that permission to a specific set of users, using a security group that you control. Once configured, the group's membership is the access list: adding an interviewer grants access, removing them revokes it, and no further changes to the configuration are needed.

NOTE

This is optional. If you are comfortable granting tenant-wide calendar access during the standard consent flow, no additional configuration is required and you can skip this guide.

Who Should Use This ​

  • Hiring teams where only recruiters and interviewers should be visible to imper.ai, not the whole organization

  • Organizations with data-access policies that require application permissions to be scoped

  • Pilots and phased rollouts, where only a subset of interviewers should be covered initially

What You Will Need ​

  1. An account with the Exchange Administrator role, or membership in the Organization Management role group

  2. An account with the Global Administrator or Privileged Role Administrator role, to adjust the tenant-wide permission at the end

  3. PowerShell 7 or later, on Windows, macOS, or Linux

  4. Two values supplied by your imper.ai contact:

    • The imper.ai Application ID

    • The imper.ai Object ID

NOTE

The Object ID must be the one shown under Enterprise applications in the Azure portal. The App registrations page displays a different Object ID for the same application, and it will not work here.

How It Works ​

The configuration has two halves, and both are required:

  1. You define which mailboxes imper.ai may access by creating a security group and granting imper.ai calendar access limited to that group.

  2. You remove the tenant-wide calendar permission that was granted during the original consent flow.

Microsoft treats these two grants as additive. If the tenant-wide permission is left in place, it continues to allow access to every mailbox and the group restriction has no effect. Step 7 is therefore not optional.

Step 1 - Connect to Exchange Online ​

powershell
Install-Module ExchangeOnlineManagement -Scope CurrentUser
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline

What this does: Installs and loads Microsoft's Exchange Online management module, then signs you in.

Expected result: A browser window opens for sign-in. Sign in with your Exchange Administrator account. The Exchange commands used in the following steps become available only after this sign-in completes.

Step 2 - Create the security group ​

powershell
New-DistributionGroup -Name "imper-calendar-access" `
  -Alias "imper-calendar-access" `
  -Type Security `
  -PrimarySmtpAddress "imper-calendar-access@yourdomain.com"

What this does: Creates a mail-enabled security group. This group is the access list - imper.ai will be able to see the calendars of its members, and no one else.

Expected result: The group is created and appears in the Exchange admin center under Recipients > Groups.

NOTE

-Type Security is required. A standard distribution list or a Microsoft 365 Group cannot be used for this purpose. Replace yourdomain.com with a domain accepted by your tenant.

Step 3 - Add the users to be covered ​

powershell
Add-DistributionGroupMember -Identity "imper-calendar-access" `
  -Member "recruiter@yourdomain.com"

What this does: Adds one user to the group, granting imper.ai access to that user's calendar. Repeat for each user.

Expected result: No output. Confirm the membership with:

powershell
Get-DistributionGroupMember -Identity "imper-calendar-access"

IMPORTANT

Only direct members of the group are covered. If you add another group as a member, that nested group's users are not included, and no warning is shown. Add users individually, or ask your imper.ai contact about scoping to an administrative unit instead.

Step 4 - Retrieve the group's identifier ​

powershell
(Get-Group -Identity "imper-calendar-access").DistinguishedName

What this does: Returns the group's full internal identifier, which the next step requires.

Expected result: A long string beginning with CN=imper-calendar-access,OU=.... Copy the whole value.

Step 5 - Create the access rule ​

powershell
New-ManagementScope -Name "imper calendar scope" `
  -RecipientRestrictionFilter "MemberOfGroup -eq '<paste the value from Step 4>'"

What this does: Creates a rule that resolves to "the current members of this group", checked each time access is attempted.

Expected result: The rule is created and its name is echoed back.

Because the rule is evaluated in real time, you never need to revisit it. Changing who imper.ai can see is done entirely through group membership from this point on.

Step 6 - Grant imper.ai access, limited to the group ​

powershell
New-ServicePrincipal -AppId "<imper.ai Application ID>" `
  -ObjectId "<imper.ai Object ID>" `
  -DisplayName "imper.ai"

New-ManagementRoleAssignment -Name "imper calendar access" `
  -App "<imper.ai Application ID>" `
  -Role "Application Calendars.ReadWrite" `
  -CustomResourceScope "imper calendar scope"

What this does: The first command registers imper.ai's identity within Exchange. The second grants calendar access, restricted to the group from Step 2.

Expected result: Both commands echo back the object they created.

NOTE

One role covers both needs. Calendars.ReadWrite permits creating, reading, updating and deleting calendar events, so it already includes everything Calendars.Read allows. A separate Application Calendars.Read assignment would be redundant.

Step 7 - Remove the tenant-wide permission ​

This step is what makes the restriction take effect. In the Azure portal:

  1. Go to Microsoft Entra ID > Enterprise applications

  2. Select the imper.ai application

  3. Open Permissions

  4. Locate Calendars.ReadWrite, granted during the original consent flow

  5. Revoke it

Expected result: No calendar permission appears in the application's granted permissions any more. The scoped grant created in Step 6 does not appear on this page - it is held in Exchange, not in Entra ID, so an empty calendar-permission list is the correct outcome.

IMPORTANT

If this permission is left in place, imper.ai retains calendar access to every mailbox in the tenant and Steps 1 through 6 have no practical effect.

Verify the Result ​

powershell
Test-ServicePrincipalAuthorization -Identity "<imper.ai Application ID>" `
  -Resource "recruiter@yourdomain.com" | Format-Table

What this does: Reports whether imper.ai is permitted to access the calendar of the mailbox you name.

Expected result:

  • InScope: True for a user who is a member of the group

  • InScope: False for a user who is not

Run it against one member and one non-member to confirm both outcomes.

NOTE

This command reports your configuration immediately. The live permission change takes longer to apply - see Timing below.

Timing ​

Microsoft caches application permissions. After any change in this guide, allow:

  • Up to 30 minutes if the application has been idle

  • Up to 2 hours if the application has been active

During this window, imper.ai may still reach a mailbox you have just excluded, or be unable to reach one you have just added. Test-ServicePrincipalAuthorization bypasses this cache, so it can report the new state while the old state is still in force. This is expected, and resolves without intervention.

Changing Who Is Covered ​

Add or remove group members. Nothing else needs to change.

powershell
Add-DistributionGroupMember    -Identity "imper-calendar-access" -Member "newuser@yourdomain.com"
Remove-DistributionGroupMember -Identity "imper-calendar-access" -Member "olduser@yourdomain.com"

Allow for the caching window above before the change takes effect.

What imper.ai Can and Cannot See ​

Once configured:

Scope
Calendars of group members - read and updateAccessible
Calendars of everyone else in the tenantNot accessible
Mailbox contents, emailNot accessible unless separately granted
ContactsNot accessible unless separately granted

Attempts to reach a calendar outside the group are refused by Microsoft, not by imper.ai. The restriction is enforced by your tenant, so it holds regardless of what imper.ai requests.

Removing the Configuration ​

To return to the standard tenant-wide arrangement, remove the objects in this order, then re-grant the calendar permission in the Azure portal.

powershell
Remove-ManagementRoleAssignment -Identity "imper calendar access"
Remove-ManagementScope          -Identity "imper calendar scope"
Remove-DistributionGroup        -Identity "imper-calendar-access"
Remove-ServicePrincipal         -Identity "<imper.ai Object ID>"

The order matters - a rule cannot be removed while a grant still refers to it, so the grant comes first.

Troubleshooting ​

"The term 'New-DistributionGroup' is not recognized" ​

The Exchange commands are added to your session by the sign-in in Step 1. Run Connect-ExchangeOnline first.

imper.ai still reaches mailboxes outside the group ​

Either the caching window has not elapsed, or the tenant-wide permission in Step 7 is still granted. Check the application's Permissions page in the Azure portal.

A user in the group cannot be reached ​

Confirm they are a direct member with Get-DistributionGroupMember. Users belonging to a nested group are not covered.

"Insufficient permissions" when running a command ​

Steps 1 through 6 require the Exchange Administrator role or Organization Management membership. Step 7 requires Global Administrator or Privileged Role Administrator.

Copyright © Imper AI