Skip to main content
Systems Engineering

Scope Microsoft Graph Mail Access to Specific Mailboxes with Exchange Online RBAC for Applications

Scope an app's Graph mail access to specific mailboxes with RBAC for Applications in Exchange Online, test it, remove the unscoped Entra grant and keep a tested rollback.

A row of sleek red mailboxes with metallic number panels and keyholes against a red background.

In this guide

Share

To limit an app that reads mail through Microsoft Graph to a defined set of mailboxes, use RBAC for Applications in Exchange Online. In Exchange Online PowerShell, register the app’s service principal with New-ServicePrincipal, describe the allowed mailboxes with a management scope (New-ManagementScope) or a Microsoft Entra administrative unit, and assign an application role such as Application Mail.Read with New-ManagementRoleAssignment -App … -CustomResourceScope …. Prove the result with Test-ServicePrincipalAuthorization -Resource, which reports InScope as True or False for a given mailbox. The key constraint is that Exchange and Microsoft Entra permissions are added together: while the app still holds the unscoped Mail.Read application permission in Microsoft Entra ID, the scope changes nothing. Removing that Entra grant is the step that actually narrows access, so capture it first and keep the re-grant ready as your rollback. Expect permission changes to reach a running app after 30 minutes to 2 hours.

#Context: why application mail permissions need a boundary

A Microsoft Graph application permission such as Mail.Read is granted without a signed-in user, and Microsoft describes it as allowing the app to read email in all mailboxes. That suits a tenant-wide archiving or compliance tool. It is far too broad for the common case: a ticketing connector that reads one shared support mailbox, a room-booking system that needs calendars in one region, or an invoice processor that reads a finance mailbox.

Exchange Online previously answered this with Application Access Policies, which constrain the permissions an app holds in Microsoft Entra ID. Microsoft now states that RBAC for Applications replaces Application Access Policies. Instead of filtering an Entra grant after the fact, the permission itself is granted inside Exchange Online with a resource scope attached. The supported protocols are Microsoft Graph and EWS; the EWS role matters only for the time EWS remains available, so check the Exchange Web Services retirement deadline in Exchange Online before you build anything new on it.

This walkthrough assumes an app that reads mail with app-only Microsoft Graph access, currently holds the Entra Mail.Read application permission, and should keep access only to mailboxes that share an attribute value. Test it first against a non-production app and a small set of test mailboxes.

#Architecture: three Exchange objects and one Entra grant

A role assignment ties together a principal, a role and a resource scope. For applications, each part is a distinct object:

  • Service principal pointer. Exchange holds a reference to the service principal that already exists in Microsoft Entra ID. Exchange cannot create the service principal itself, refuses an invalid pointer, and removes the pointer, with its role assignments, when the Entra service principal is deleted. Management scopes are left in place.
  • Application role. A special management role that can only be assigned to a service principal, cannot be copied or derived, and maps to a Microsoft Graph or EWS permission. Examples are Application Mail.Read, Application Mail.ReadBasic, Application Mail.Send and Application Calendars.Read. List them with Get-ManagementRole.
  • Resource scope. Either a management scope, which selects mailboxes with an OPATH recipient filter, or a Microsoft Entra administrative unit passed with -RecipientAdministrativeUnitScope.

The fourth element sits outside Exchange: whatever application permissions the app already holds in Microsoft Entra ID. Microsoft documents the effective permission as the union of the Entra grants and the Exchange RBAC grants, with each authority acting independently. An unscoped Entra Mail.Read plus a scoped Exchange Mail.Read therefore equals unscoped access. A Graph call that needs two permissions only succeeds against a mailbox where the app holds both; holding one permission on mailbox A and the other on mailbox B fails against both.

Choosing a resource scope for an application role assignment
Scope typeHow mailboxes are selectedPoints to watch
Management scopeOPATH filter on mailbox properties, for example CustomAttribute1 or MemberOfGroupA MemberOfGroup filter uses the group’s distinguished name and counts direct members only; nested members are out of scope
Administrative unitMembership of a Microsoft Entra administrative unit, passed by its IDMicrosoft recommends the native parameter rather than a scope that wraps an administrative unit
Exclusive management scopeNot usable as an app boundaryMicrosoft states that exclusive scopes do not restrict app access
Scope Microsoft Graph Mail Access to Specific Mailboxes with Exchange Online RBAC for Applications architecture diagram 1
Photo by Stephen Andrews on Pexels

#Implementation: grant the scoped role, then remove the unscoped grant

You need membership of the Exchange Online Organization Management role group, which holds the delegating assignment for the application roles, and the Exchange Administrator role in Microsoft Entra ID. Removing and restoring the Entra grant needs the delegated Graph permissions Application.Read.All and AppRoleAssignment.ReadWrite.All. The app’s service principal ID and application ID come from Enterprise applications, not from App registrations, which shows different values.

  1. Capture the current state (read-only). Record the app’s existing Graph application permissions and the Graph resource’s role IDs. This export is your rollback.

    1Connect-ExchangeOnline -UserPrincipalName admin@contoso.com
    2Connect-MgGraph -Scopes "Application.Read.All", "AppRoleAssignment.ReadWrite.All"
    3$sp    = Get-MgServicePrincipal -Filter "appId eq '<client-app-id>'"
    4$graph = Get-MgServicePrincipal -Filter "appId eq '00000003-0000-0000-c000-000000000000'" -Property "id,displayName,appId,appRoles"
    5$mailReadId = ($graph.AppRoles | Where-Object { $_.Value -eq 'Mail.Read' -and $_.AllowedMemberTypes -contains 'Application' }).Id
    6Get-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $sp.Id | Export-Csv .\app-role-assignments-before.csv -NoTypeInformation

    Each row shows AppRoleId, PrincipalId, ResourceDisplayName and ResourceId. Stop here if no row has ResourceId equal to $graph.Id and AppRoleId equal to $mailReadId: the app’s mail access comes from somewhere else and this plan does not fit it. Also stop if the export shows another Graph mail application permission, such as Mail.ReadWrite or Mail.ReadBasic.All: it is unscoped too, and removing only Mail.Read would leave tenant-wide access in place.

  2. Create the resource scope. This example assumes the target mailboxes already carry the value FinanceAutomation in CustomAttribute1; check the filter matches only those mailboxes before you rely on it.

    1New-ManagementScope -Name "Finance automation mailboxes" -RecipientRestrictionFilter "CustomAttribute1 -eq 'FinanceAutomation'"

    The output shows ScopeRestrictionType RecipientScope and Exclusive False. To reuse a group from an existing Application Access Policy instead, filter on MemberOfGroup -eq '<group distinguished name>', finding the name with Get-Group.

  3. Create the service principal pointer.

    1New-ServicePrincipal -AppId <client-app-id> -ObjectId <service-principal-object-id> -DisplayName "Invoice processor"

    The output lists DisplayName, ObjectId and AppId. Confirm them with Get-ServicePrincipal -Identity <service-principal-object-id> | Format-List.

  4. Assign the application role to the scope. Choose the narrowest role the app needs; Application Mail.ReadBasic excludes the body, preview body, attachments and extended properties.

    1New-ManagementRoleAssignment -Name "Invoice processor Mail.Read finance" -App <service-principal-object-id> -Role "Application Mail.Read" -CustomResourceScope "Finance automation mailboxes"

    The new assignment shows RoleAssigneeType ServicePrincipal and AssignmentMethod Direct. Assignment names are limited to 64 characters.

  5. Test before you remove anything. The test cmdlet bypasses the permission cache and ignores Entra grants, so it shows exactly what Exchange RBAC allows.

    1Test-ServicePrincipalAuthorization -Identity <service-principal-object-id> -Resource "<in-scope mailbox>" | Format-Table
    2Test-ServicePrincipalAuthorization -Identity <service-principal-object-id> -Resource "<out-of-scope mailbox>" | Format-Table

    Expect RoleName Application Mail.Read, AllowedResourceScope naming your scope, ScopeType CustomRecipientScope, and InScope True for the first mailbox and False for the second. Without -Resource, InScope reads Not Run.

  6. Remove the unscoped Entra grant (state-changing). Before you run anything here, confirm that step 5 returned True for every mailbox the app must keep and that the step 1 export is saved. Then select the grant and inspect it.

    1$grant = Get-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $sp.Id | Where-Object { $_.ResourceId -eq $graph.Id -and $_.AppRoleId -eq $mailReadId }
    2@($grant).Count
    3$grant | Format-List Id, AppRoleId, ResourceDisplayName

    Stop if the count is anything other than 1. Otherwise preview the removal with -WhatIf, then run it. Removing an app role assignment revokes the app-only permission.

    1Remove-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $sp.Id -AppRoleAssignmentId $grant.Id -WhatIf
    2Remove-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $sp.Id -AppRoleAssignmentId $grant.Id

If the app was constrained by an Application Access Policy, Microsoft’s migration order is the same: create the scope, create the pointer, assign the scoped role, remove the Entra consent, then remove the Application Access Policy. Microsoft states that this order causes no interruption for the app.

#Validation: prove the boundary from both sides

  • Run Test-ServicePrincipalAuthorization with no -Resource and confirm the only roles listed are the ones you assigned, each with the intended AllowedResourceScope. A row with ScopeType Organization means an unscoped assignment exists.
  • Run it against a sample of in-scope and out-of-scope mailboxes, including one that is only a nested member of a scoping group if you used MemberOfGroup. Nested members should report False.
  • Read Get-MgServicePrincipalAppRoleAssignment again and confirm no row remains for Microsoft Graph Mail.Read or any other Graph mail application permission.
  • After the cache window, which Microsoft gives as 30 minutes for an app with no recent calls and up to 2 hours for an active one, have the app read an in-scope mailbox, which should succeed, and an out-of-scope mailbox, which should now be refused. Record both results in the change record.

#Failure modes

  • The app still reads every mailbox. An unscoped Entra grant remains, or the cache has not expired. Check Get-MgServicePrincipalAppRoleAssignment, then wait out the 2-hour ceiling before concluding the scope failed.
  • The app loses an in-scope mailbox. The mailbox does not match the filter, or it is a nested group member. Test-ServicePrincipalAuthorization -Resource on that mailbox shows InScope False; fix the attribute or membership rather than widening the scope.
  • A Graph call needing two permissions fails. The app holds each permission on a different set of mailboxes. Assign both roles to the same scope.
  • Autodiscover stops working for the app. Microsoft states that Autodiscover cannot currently be accessed with RBAC application roles; an EWS client that depends on it needs its endpoint configured another way before cutover.
  • New-ServicePrincipal rejects the IDs or the pointer targets the wrong object. The values came from App registrations. Use the Enterprise applications values or Get-MgServicePrincipal.
  • Assignments disappear. The Entra service principal was deleted, which removes its Exchange assignments automatically. Recreate the pointer and assignments once the app is registered again.
A close-up shot of vintage metal mailboxes indoors with a soft blur effect.
Photo by Andrea Piacquadio on Pexels

#Security: least privilege and residual risk

A resource scope limits which mailboxes an app reaches, not what it can do inside them. Choose the role first: Application Mail.ReadBasic instead of Application Mail.Read where headers are enough, and avoid Application Mail Full Access and Application Exchange Full Access, which bundle send and read-write rights. Application Mail.Send lets an app send as any user in its scope, so give a sending app a scope as narrow as a reading one.

The scope is only as trustworthy as the attribute or group behind it. Anyone who can set CustomAttribute1 on a mailbox, or add members to a scoping group, can move a mailbox into the app’s reach. Treat those rights as part of the boundary, in the same way that restricting Microsoft 365 group creation to an approved security group treats group membership as a control.

The delegated AppRoleAssignment.ReadWrite.All permission used for the Entra change lets its holder grant app permissions, and Microsoft warns that grants made through Graph take effect immediately without review. Use it only for the change window. Remember that a new Entra application permission added later by another administrator silently restores tenant-wide access, because the two systems combine.

#Recovery: restore access without widening it for good

The most likely incident is the app losing a mailbox it needs after step 6. The fastest safe recovery restores the previous state, which you exported in step 1:

  1. Re-grant the Entra permission:
    1New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $sp.Id -BodyParameter @{ principalId = $sp.Id; resourceId = $graph.Id; appRoleId = $mailReadId }

    This puts back the original tenant-wide access; Microsoft states that grants made through Microsoft Graph take effect immediately. If $graph or $mailReadId are no longer set, take ResourceId and AppRoleId from the CSV.

  2. Confirm the row is back with Get-MgServicePrincipalAppRoleAssignment and compare it with app-role-assignments-before.csv.
  3. Diagnose the missing mailbox with Test-ServicePrincipalAuthorization -Resource, fix the scope or the mailbox attribute, and repeat step 6 later.
  4. To back out RBAC for Applications entirely, preview and then remove the assignment with Remove-ManagementRoleAssignment "Invoice processor Mail.Read finance" -WhatIf, then without -WhatIf. The management scope and the service principal pointer can stay; they grant nothing on their own.

Do not remove the Exchange assignment before the Entra grant is back in place, or the app will be left with no mail access at all.

#Operating scoped mailbox access after cutover

  • Monthly, run Test-ServicePrincipalAuthorization for each scoped app and compare the roles and scopes with the change record.
  • Re-read Get-MgServicePrincipalAppRoleAssignment for the same apps; any returning Graph mail permission undoes the boundary.
  • Review who can change the scoping attribute or group, and audit changes to it.
  • Remember the limit of 10,000 applications per organisation using RBAC for Applications when you plan wider adoption.

The next safe decision is which app to move next: start with the one holding the broadest Graph mail permission against the smallest real set of mailboxes, because that is where a scope removes the most exposure.

About this page

Credited to

Dates

Published

Sources

This page lists no external sources.

Corrections

No corrections are listed for this page. Some review sweeps corrected pages without naming each one; those are in the corrections log.

Reader Interaction

Comments

Add a thoughtful note on Scope Microsoft Graph Mail Access to Specific Mailboxes with Exchange Online RBAC for Applications. Comments are checked for spam and held for moderation before appearing.

Loading comments...

Discover more

Was this useful?

Reports go to the site owner and are used to correct pages. Corrections are listed at /corrections.

Engineering insights, direct to you.

Receive the latest Systems Engineering tutorials, production guides, Engineering Labs and operational best practices.