Diagram from Microsoft Learn: a role assignment links an application, an application role and a resource scope, with a room booking example

  • Aug 6, 2025

RBAC for Applications: Limit Mail.Read and Mail.Send

Give an app only the mailboxes it needs. A step-by-step guide to Exchange Online RBAC for Applications: scopes, role assignments, testing, and the Entra consent step most guides forget.

In short: when you grant an app the Microsoft Graph application permission Mail.Read or Mail.Send in Microsoft Entra ID, it can reach every mailbox in your organization. Exchange Online RBAC for Applications lets you grant the same permissions, but only over the mailboxes you choose. It replaces the older Application Access Policies. This guide shows the full setup, and the one step that most tutorials leave out: removing the organization-wide grant in Entra, because without that step your scope does nothing.

Why this matters

Application permissions run without a signed-in user. Microsoft Graph documents that, by default, an app with a permission such as Mail.Read can access all mailboxes in the organization. The same is true for mailbox settings, contacts and calendars. A leaked client secret or a compromised vendor integration therefore exposes every mailbox, not just the one the app was built for.

Scoping fixes the blast radius:

  • Limit data exposure. A reporting app that reads one shared mailbox shouldn't be able to read the CEO's.

  • Limit write and send abuse. Mail.Send as an application permission lets an app send mail as any user. Scoped, it can send only as the mailboxes in scope.

  • Make audits easier. A role assignment has a name, a role and a scope you can list, instead of a tenant-wide consent that nobody remembers.

  • Scale. Microsoft states a limit of 10,000 applications per organization for RBAC for Applications. The older Application Access Policy feature was limited to 300 apps per tenant in Microsoft's preview announcement.

How RBAC for Applications works

A role assignment ties together three things: an application (a service principal), an application role such as Application Mail.Read, and a resource scope that says which mailboxes the role applies to.

Diagram from Microsoft Learn: a role assignment links an application, an application role and a resource scope, with a room booking example

Source: Microsoft Learn, Role Based Access Control for Applications in Exchange Online

Key facts from the documentation:

  • It replaces Application Access Policies, and works with Microsoft Graph and Exchange Web Services (EWS).

  • You can scope with a management scope (a filter on mailbox properties) or with a Microsoft Entra administrative unit.

  • Exchange keeps a pointer to the app's service principal in Entra. You create the app in Entra; Exchange can't.

  • Exchange permissions and Entra permissions are separate and additive. Each authority acts independently.

Application Access Policies are described by Microsoft as a legacy feature that has been replaced. Microsoft says not to use them for new configurations because a deprecation will be announced in the future. We found no published retirement date, so plan the migration rather than waiting for one.

Before you begin

Modules and connections

  • Microsoft Graph PowerShell (Microsoft.Graph), to find the app's IDs and, later, to review and remove its Entra permissions. The old AzureAD and MSOnline modules are retired; don't use them.

  • Exchange Online PowerShell (ExchangeOnlineManagement), for the RBAC cmdlets.

Permissions to assign RBAC for Applications

  • Membership of the Organization Management role group in Exchange Online (it holds the delegating role assignment for the application roles), or a custom Exchange role assignment that delegates it.

  • In Microsoft Entra ID, the Exchange Administrator role, per Microsoft's documentation.

  • To change the app's Entra permissions or consent in step 6, a role that can manage app permissions, such as Cloud Application Administrator or Application Administrator, plus the Graph scopes shown in that step.

Information to collect

  • The app's Application (client) ID and the Object ID of its service principal (enterprise application). These are different values. Don't take them from the App registrations page, which shows different values.

  • The mailbox, group or filter that defines the scope.

  • The application role(s) you need.

Choose the right application role

Pick the narrowest role that does the job. A few of the supported application roles and the Graph permissions they map to:

  • Application Mail.ReadBasic: read mail except body, preview, attachments and extended properties.

  • Application Mail.Read: read mail.

  • Application Mail.ReadWrite: create, read, update and delete mail. Does not include sending.

  • Application Mail.Send: send mail as users in scope.

  • Application Mail Full Access: Mail.ReadWrite plus Mail.Send.

  • Application MailboxSettings.Read, Application Calendars.Read, Application Contacts.Read: the matching read-only roles.

  • Application Exchange Full Access: mail, mailbox settings, calendars and contacts. Avoid it unless the app truly needs all of these.

List the roles available in your tenant (Microsoft says the application roles can be enumerated with Get-ManagementRole):

Get-ManagementRole -Identity "Application*"

Step-by-step setup

Step 1: Find the service principal IDs

Search by the application (client) ID rather than the display name. Display names aren't unique, and a server-side filter is faster than downloading every service principal.

Connect-MgGraph -Scopes "Application.Read.All"

$clientId = "<APPLICATION_CLIENT_ID>"

$sp = Get-MgServicePrincipal `
    -Filter "appId eq '$clientId'"

$sp.Id
$sp.AppId
$sp.DisplayName
Screenshot from Microsoft Learn of an enterprise application's Overview page with the Application ID and Object ID outlined in red

Source: Microsoft Learn, Role Based Access Control for Applications in Exchange Online. The portal styling in this screenshot is older; the two fields are in the same place on the enterprise application's Overview page.

$sp.Id is the service principal object ID. $sp.AppId is the application (client) ID. You can also read both in the Microsoft Entra admin center: Entra ID > Enterprise apps > select the app > Overview (Application ID and Object ID).

Step 2: Create the service principal pointer in Exchange

Connect-ExchangeOnline -UserPrincipalName "<ADMIN_UPN>"

$pointer = @{
    AppId       = $sp.AppId
    ObjectId    = $sp.Id
    DisplayName = $sp.DisplayName
}
New-ServicePrincipal @pointer

# Confirm the pointer exists
Get-ServicePrincipal -Identity $sp.Id

This creates only a reference to the Entra service principal. It grants no access by itself. Exchange also removes the pointer automatically if the service principal is deleted in Entra, which deletes its role assignments but leaves the management scopes in place.

Step 3: Define the scope

You have three practical choices.

Option A: a single mailbox (matches the original example in this post, but with the property Microsoft recommends):

$scopeName = "ReportingApp-Scope"

New-ManagementScope `
    -Name $scopeName `
    -RecipientRestrictionFilter `
    "EmailAddresses -eq 'reports@contoso.com'"

Get-ManagementScope -Identity $scopeName

Option B: a set of mailboxes selected by an attribute. This is the pattern used in Microsoft's example and scales better, because adding a mailbox to scope is just setting the attribute:

New-ManagementScope `
    -Name "Canadian users" `
    -RecipientRestrictionFilter `
    "CustomAttribute1 -eq '012332'"

Option C: a Microsoft Entra administrative unit. Microsoft recommends using the native administrative unit parameter on the role assignment instead of creating a scope as an intermediary. See step 4.

Scope notes:

  • The original version of this post filtered on PrimarySmtpAddress. Microsoft's filterable-properties page now says not to use that property and to use EmailAddresses instead. Any filter on PrimarySmtpAddress also matches the mailbox's other proxy (alias) addresses, so an alias can bring a mailbox into scope you didn't expect. A complete address in an EmailAddresses -eq filter doesn't need the smtp: prefix; wildcard filters do.

  • Filter values go in single quotes inside the double-quoted filter. Variables inside the filter are expanded by PowerShell, so be careful with quoting.

  • The filter can use recipient properties documented in "Filterable properties for the -RecipientFilter parameter".

  • Exclusive scopes don't restrict app access. Don't use the -Exclusive switch expecting to lock an app down.

Step 4: Assign the role with the scope

Use the object ID of the service principal for -App. Microsoft's cmdlet reference for New-ManagementRoleAssignment specifies the ObjectId GUID from Get-ServicePrincipal for this parameter. (The original version of this post passed the client ID; use the object ID to match the documentation.)

$read = @{
    App                 = $sp.Id
    Role                = "Application Mail.Read"
    CustomResourceScope = $scopeName
}
New-ManagementRoleAssignment @read

$send = @{
    App                 = $sp.Id
    Role                = "Application Mail.Send"
    CustomResourceScope = $scopeName
}
New-ManagementRoleAssignment @send

Using an administrative unit instead of a management scope:

$au = @{
    App  = $sp.Id
    Role = "Application Mail.Read"
    RecipientAdministrativeUnitScope = "<ADMIN_UNIT_ID>"
}
New-ManagementRoleAssignment @au

Only grant the roles the app actually uses. If it only reads mail, skip Application Mail.Send.

Step 5: Test the Exchange side

Test-ServicePrincipalAuthorization simulates what the RBAC assignments allow. Pass -Resource to check a specific mailbox. InScope is True if the permission applies to that mailbox, and False if the app holds the permission but not over that mailbox. Without -Resource, InScope shows "Not Run".

# A mailbox that should be allowed
Test-ServicePrincipalAuthorization `
    -Identity $sp.Id `
    -Resource "reports@contoso.com" |
    Format-Table

# A mailbox that should NOT be allowed
Test-ServicePrincipalAuthorization `
    -Identity $sp.Id `
    -Resource "ceo@contoso.com" |
    Format-Table

Expected result: InScope = True for the first mailbox and False for the second.

Important: this test excludes permissions that are granted separately in Microsoft Entra ID. A clean result here doesn't prove the app is locked down. That is what step 6 is for.

Step 6: Remove the organization-wide grant in Entra ID

This is the step the original post omitted, and the one that decides whether scoping works.

Microsoft's FAQ is explicit: permissions from Entra ID and from Exchange RBAC are a union. If the app already has Mail.Read consented in Entra ID and you add a scoped Mail.Read in Exchange, "the union of an unscoped Mail.Read grant from Microsoft Entra and a resource-scoped Mail.Read grant in Application RBAC results in no effective resource scoping." You must remove the Entra assignment.

Review what the app has today. In the admin center, open Entra ID > Enterprise apps > select the app > Permissions. Or with PowerShell:

Connect-MgGraph -Scopes @(
    "Application.Read.All",
    "AppRoleAssignment.ReadWrite.All"
)

# Application permissions granted to this app
$grants = Get-MgServicePrincipalAppRoleAssignment `
    -ServicePrincipalId $sp.Id `
    -All

# Look up the names of the Microsoft Graph app roles
$graphSp = Get-MgServicePrincipal `
    -Filter "appId eq '00000003-0000-0000-c000-000000000000'"

$roleNames = @{}
foreach ($r in $graphSp.AppRoles) {
    $roleNames[$r.Id] = $r.Value
}

$grants | Select-Object AppRoleId, ResourceDisplayName,
    @{ Name = "Permission"
       Expression = { $roleNames[$_.AppRoleId] } }

Before you remove anything, make sure the Exchange role assignment works (step 5) and plan a short change window. Microsoft's migration guidance orders it this way: create the scope and assignment first, then remove consent in Entra, so the app is never without access.

Remove only the mail permissions you replaced:

$remove = $grants | Where-Object {
    $roleNames[$_.AppRoleId] -in @("Mail.Read", "Mail.Send")
}

foreach ($g in $remove) {
    Remove-MgServicePrincipalAppRoleAssignment `
        -ServicePrincipalId $sp.Id `
        -AppRoleAssignmentId $g.Id
}

Also remove the permission from the app registration's requested API permissions in Entra ID > App registrations > the app > API permissions, so a future admin consent doesn't quietly add it back. Don't remove the app's other permissions (for example User.Read).

Step 7: Test with the real app, and wait for the cache

Exchange caches app permissions. Microsoft documents that changes can take 30 minutes to 2 hours to apply, depending on how recently the app was used, while the test cmdlet bypasses that cache. So a successful test followed by a failing app can simply be timing.

After the wait, test as the app. For example, with a certificate and Microsoft Graph PowerShell:

$app = @{
    ClientId              = $sp.AppId
    TenantId              = "<TENANT_ID>"
    CertificateThumbprint = "<THUMBPRINT>"
}
Connect-MgGraph @app -NoWelcome

# Should return a message
Get-MgUserMessage -UserId "reports@contoso.com" -Top 1

# Should be denied
Get-MgUserMessage -UserId "ceo@contoso.com" -Top 1

You should see mail for the in-scope mailbox and an authorization error (typically HTTP 403) for the other. Treat anything else as a failed rollout and check step 6 first. The exact error text can vary by API, so rely on the result, not the wording.

All steps in one script

# --- Inputs ---
$clientId   = "<APPLICATION_CLIENT_ID>"
$mailbox    = "reports@contoso.com"
$scopeName  = "ReportingApp-Scope"
$adminUpn   = "<ADMIN_UPN>"

# --- Find the service principal ---
Connect-MgGraph -Scopes "Application.Read.All"
$sp = Get-MgServicePrincipal -Filter "appId eq '$clientId'"

# --- Exchange: pointer, scope, assignments ---
Connect-ExchangeOnline -UserPrincipalName $adminUpn

New-ServicePrincipal `
    -AppId $sp.AppId `
    -ObjectId $sp.Id `
    -DisplayName $sp.DisplayName

New-ManagementScope `
    -Name $scopeName `
    -RecipientRestrictionFilter `
    "EmailAddresses -eq '$mailbox'"

foreach ($role in "Application Mail.Read", "Application Mail.Send") {
    New-ManagementRoleAssignment `
        -App $sp.Id `
        -Role $role `
        -CustomResourceScope $scopeName
}

# --- Test (does not include Entra grants) ---
Test-ServicePrincipalAuthorization `
    -Identity $sp.Id `
    -Resource $mailbox |
    Format-Table

# Next: remove Mail.Read / Mail.Send from Entra (step 6),
# then test with the real app after the cache window.

Migrating from Application Access Policies

If you already use New-ApplicationAccessPolicy, Microsoft's documented migration reuses your existing mail-enabled security group as the scope, with no interruption to the app:

  1. Create a management scope that points to the group used by the policy.

  2. Create the service principal pointer.

  3. Assign the needed roles to the service principal with that scope.

  4. Remove the consent in Entra ID.

  5. Remove the Application Access Policy.

For step 1, the filter uses MemberOfGroup with the group's distinguished name:

$dn = (Get-Group -Identity "<GROUP_NAME>").DistinguishedName

New-ManagementScope `
    -Name "Migrated-ReportingApp" `
    -RecipientRestrictionFilter "MemberOfGroup -eq '$dn'"

Group limits from the documentation: only direct members count (nested group members are out of scope), and Microsoft 365 groups, mail-enabled security groups and distribution lists are supported.

Inventory what you have first:

Get-ApplicationAccessPolicy

Remove a policy only after the replacement is tested and the Entra consent has been handled:

Remove-ApplicationAccessPolicy -Identity "<POLICY_IDENTITY>"

Microsoft notes that Application Access Policies constrain only the permissions assigned in Entra ID. The two systems can coexist, for example an app with organization-wide Mail.Read in Entra and scoped Mail.Send in RBAC for Applications, but combining them produces surprising unions. Microsoft's recommendation: assign organization-wide permissions in Entra ID and resource-scoped permissions through RBAC for Applications.

Tradeoffs and limitations

  • Two places to look. Effective access is Entra consent plus Exchange RBAC. Audit both. Microsoft says a consolidated view of Exchange-granted permissions in the Entra admin experience was "upcoming" in its documentation; don't assume it exists in your tenant.

  • Propagation delay. Plan for 30 minutes to 2 hours.

  • Autodiscover. Microsoft documents that Autodiscover currently can't be accessed when using RBAC application roles. Clients that depend on it need testing.

  • Protocols. Microsoft Graph and EWS are supported. Check the supported roles list for your scenario.

  • Group scopes are direct-membership only. Nested groups won't work.

  • Role assignments are not a replacement for secret hygiene. A scoped app can still read or send as the in-scope mailboxes if its secret leaks. Prefer certificates, rotate credentials and monitor sign-ins for the service principal.

  • Application roles can't be copied or derived, can only be assigned to service principals, and apps can't be members of a role group.

Troubleshooting

The app can still read other mailboxes. Almost always the unscoped Mail.Read / Mail.Send grant is still in Entra ID (step 6). Check Enterprise apps > the app > Permissions, and remember the permissions are additive. Also check for an Entra directory role assigned to the app that has broad access.

New-ServicePrincipal fails. Confirm you used the service principal object ID, not the app registration's object ID, and that the service principal exists in this tenant.

New-ManagementRoleAssignment fails with a permission error. You need Organization Management membership or a delegating assignment (see "Before you begin").

Test says InScope = False for a mailbox you expected. Check the scope filter against the mailbox's real properties. Compare: Get-ManagementScope -Identity $scopeName | Format-List and the mailbox's property you filter on, for example Get-Mailbox reports@contoso.com | Format-List EmailAddresses.

The test passes but the app fails (or the reverse). Wait out the cache window first (30 minutes to 2 hours), then retest with the real app.

Scope name mismatch. Role assignments reference the scope by name. A typo gives an error at assignment time. Use a variable for the name as in the examples.

Need to remove access. List the assignments, then remove them:

Get-ManagementRoleAssignment -RoleAssigneeType ServicePrincipal |
    Where-Object { $_.RoleAssigneeName -like "*$($sp.Id)*" } |
    Format-Table Name,Role

Remove-ManagementRoleAssignment `
    -Identity "<ASSIGNMENT_NAME>" `
    -Confirm:$false

(Check the output on your tenant first: the property that holds the service principal identity can display as the object ID.)

Key takeaways

  • App-only Mail.* permissions granted in Entra ID cover all mailboxes. RBAC for Applications scopes them to chosen mailboxes.

  • It replaces Application Access Policies. Don't build new ones.

  • Exchange and Entra permissions are additive. Remove the organization-wide grant in Entra, or your scope has no effect.

  • Use the service principal object ID with -App, and test with Test-ServicePrincipalAuthorization -Resource for both an allowed and a denied mailbox.

  • Allow 30 minutes to 2 hours for changes to take effect, then test with the real app.

  • Pick the narrowest role: Mail.ReadBasic or Mail.Read before Mail Full Access.

Official sources

About IAMPathway

IAMPathway publishes practical guides on Identity & Access Management: Microsoft Entra ID, governance, identity threats, Application Governance and AI Governance. Browse all topics or read the glossary.