When creating App Registrations in Entra to grant Graph based applications permission to resources, it is very easy to over permission. The default behaviour when you grant a permission is that the permission is for all of that particular object, for example read/write over all users or all groups etc. When the resource that you need to access in an Exchange Online mailbox, this would mean that the application would have read or read/write over all the mailboxes in your tenant – do you trust your developers that much to give them such wide ranging access, and even if you do trust them – they typically are not writing applications that need to be able to access all mailboxes.
Exchange Online has provided “Application Access Policies” in the past to restrict the mailboxes that the application would have access too, even if they had a permission such as Mail.ReadWrite, but this is now replaced with “Role-Based Access (RBAC) for Applications”. So this blog post will walk through the steps to create an Application Registration for an application to access a few mailboxes and not all the tenants mailboxes and the data they contain.
This is not delegate permissions though. Delegate permissions are used when a user logs into their own account and needs to access other resources via Graph. In that case, just grant mailbox access in Exchange Online as you would for a user accessing another mailbox in Outlook (Add-MailboxPermission).
Application permissions are used when an application logs in directly (using the secrets/certificates etc on the Application Registration) and not when running as a user and expecting the user to login before the application functions.
So how do we go about granting Exchange Online resources to an application (via an Enterprise Application object) using Role-Based Access Control (RBAC) for Applications. We need to do the following:
- Create the Application Registration and associated Enterprise App unless these exist already
- Remove any Exchange Online permissions from this application (if the app already exists) or for a new app, add the permissions for everything else but not Exchange Online.
- Create a new resource scope (optional) if you want to scope the applications access to some and not all mailboxes or other Exchange Online resources
- Select the appropriate application role
- Create a New Role assignment
- Test the New Service principal
- Hand the Application ID, Object ID, Tenant ID and any secrets to the developer to add to their application. Their application should now be able to access the specified mailboxes and only those mailboxes for the permissions provided by the selected application role.
Lets start.
To use Microsoft Graph to connect to Exchange Online mailboxes, and to do that securely, requires a number of steps. These steps are as follows and then the process you need is detailed below:
- Create a mailbox (if you don’t have that already), and for these steps this can be a shared mailbox as well as a regular mailbox, as a security principal is no longer required as we are no longer needing to use New-ApplicationAccessPolicy.
- Create an Application Registration in Entra ID
- Restrict application so it can only access the mailbox
- Test it all out
Creating the mailbox
There is nothing special about the Exchange Online mailbox you create for Graph access. And with “RBAC for Applications” (which replaces Application Access Policies) you can use Shared Mailboxes, Room or Resource mailboxes as well.
The mailbox does not need a licence if it is a shared mailbox. Though this means it will not support archives and is limited to 50GB of storage. If you need either of these then you need an Exchange Online Plan 2 licence assigned to the shared mailbox. If the mailbox fills up and you don’t delete content from it then use a Retention Policy to auto delete email older than x days/years from the mailbox instead of doing this programmatically.
Creating the application
Complete these steps from https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps and create a new App Registration.
Give the application a suitable name and choose Single Tenant. Click the Register button.
Once the application is created DO NOT ADD the required API Permissions that are related to Exchange Online, but add any others (i.e. Teams or SharePoint) that you need. The ones you need for the app are your choice, but for Exchange RBAC for Applications, the permissions are added to the Management Role Assignment in Exchange Online and not in Entra ID. Permissions like “Application Mail.Send” and “Application Mail.ReadWrite” might be what you want, and these are what we need to avoid adding in Entra ID. There are other permissions, but these are all “Application” permissions which means they run as the application and not the logged in user (which would be “Delegate” permissions).
Note that if your application needs permissions outside of Exchange Online then you would grant them here unless that service also works like RBAC for Applications. If you add the Exchange Online permissions in Entra then they will apply to all mailboxes even if you have an exclusive scope in place.
Remove the User.Read delegated permission (confirm that you want to remove this even though it says you should not) and grant admin consent for all permissions that remain.
Change to the “Branding & Properties” page and add “Internal Notes” to record the purpose of the application and who is the application sponsor (so you can tidy up apps later, as they grow like weeds). Add Owners via the Enterprise App that has also just been created for you. These people, if they have Application Administrator role, can view and change the settings of this application without other admin permissions.
Finally for the application, create a new secret and communicate it securely with the owners (secrets can only be viewed once). Use a short duration for a secret. Record Application (Client) ID, Tenant ID and provide them to the app owners as well.
You also need the Object ID of the Enterprise App (not the App Registration). To get this visit App Registration > Overview > click Managed Application in Local Directory link. Copy ObjectID from here (the Enterprise App Object ID).
You will end up with something like the following; and the secret which you would store elsewhere:
- Application Name: shared_mailbox_access
- Application (Client) ID: d90043ed-xxxx-xxxx-xxxx-xxxxxxxxxx87
- Enterprise App Object ID: 8de799a2-xxxx-xxxx-xxxx-xxxxxxxxxxa1
- Tenant ID: 1c48ea50-xxxx-xxxx-xxxx-xxxxxxxxxx63
- Client Secret: Stored encrypted elsewhere
- Permissions: Mail.ReadWrite
Restrict mailbox access to the application
By default the Graph API Exchange Online permissions (such as Mail.Read) allow access to all mailboxes in the tenant. Via Exchange Online PowerShell create a new Service Principal for the application (ClientID and Enterprise App ObjectID are needed for this). This is used to restrict the application (by ID) to a mailbox (the one created above) via the New-ManagementScope (here named after the AppID for clarity and using the GUID of the shared mailbox). It is then all tied together with the New-ManagementRoleAssignment using the App ID, the role (Application Mail.ReadWrite) and the RBAC scope created in the third PowerShell cmdlet below. This is tied to the shared mailbox only in this first example, other roles and targets are possible such as all the members of a distribution security group, and we cover that in the second example of RecipientRestrictionFilters.
For convenience in the later PowerShell snippets, I am going to store the object ID etc in variables and refer to the variables in the code further down:
$AppName = "shared_mailbox_access"
$AppID= "d90043ed-xxxx-xxxx-xxxx-xxxxxxxxxx87"
$EnterpriseAppObjectID = "8de799a2-xxxx-xxxx-xxxx-xxxxxxxxxxa1"
$TenantID = "1c48ea50-xxxx-xxxx-xxxx-xxxxxxxxxx63"
New-ServicePrincipal -AppID $AppID -ObjectID $EnterpriseAppObjectID -DisplayName "$AppName RBAC for Exchange Online"
The service principal can be optionally scoped to selected mailboxes. There are a few ways to do it, all with RecipientRestrictionFilters. I have shown two examples below, one for “mailbox = GUID” and another for “Distribution Group = Name”. The second of these is trickier than the first as it only seems to work if you use the DistinguishedName of the group!
$TargetMailbox = Get-Mailbox shared_app@domain.com
New-ManagementScope -Name "rbac_$AppID" -RecipientRestrictionFilter "GUID -eq '$($TargetMailbox.GUID)'"
If you want to scope the application to the members of a distribution group then you have a slightly different set of cmdlets. This is because I have found scoping to a DL is somewhat tricky – the following works, including making the DL and adding members to it:
New-DistributionGroup "$AppName Access" -Type Security
Add-DistributionGroupMember "$AppName Access" -Member MailboxAppCanAccess
$TargetDL = Get-DistributionGroup "$AppName Access"
New-ManagementScope -Identity $AppID -RecipientRestrictionFilter "MemberOfGroup -eq '$($TargetDL.DistinguishedName)'"
Once the optional management scope is created, you create the role assignment. This cmdlet includes the optional scope named in the CustomResourceScope property:
New-ManagementRoleAssignment -App $AppID -Role "Application Mail.ReadWrite" -CustomResourceScope "rbac_$AppID"
The “Role” values listed in the last cmdlet above can be determined by running “Get-ManagementRole | ? {$_.IsServicePrincipalRole} | select Name,IsServicePrincipalRole,Description | sort Name“, and at the time of writing there are 14 such “Application” roles. If you need to grant more than one Application Role, run “New-ManagementRoleAssignment” more than once, naming a single role each time.
Check your existing service principal management role assignments using:
Get-ManagementRoleAssignment -RoleAssigneeType ServicePrincipal
The secret generated when you created a new secret on the app and the above info should allow you to write your application and access the shared mailbox or a Distribution Group of objects.
Use Add-MailboxPermission shared_mailbox -User devUsername -AccessRights FullAccess to grant your developer access to the mailbox in Outlook as well if they need this.
Testing
To test that your scopes for RBAC are set up correctly, use Test-ServicePrincipalAuthorization and include both the AppId (the Identity property) and the mailbox that the application should have access too (the Resource property). Repeat using another user and see that InScope should show “false” for the other user.
Test-ServicePrincipalAuthorization -Identity $AppID -Resource $TargetMailbox
To test all this out use the following PowerShell. This then becomes the crux of the code that you write for your actual application that accesses the mailbox as the application registration in the directory:
$ClientSecretCredential = Get-Credential -Credential $AppID
You will be prompted for the client secret you obtained earlier.
Connect-MgGraph -TenantId $TenantID -ClientSecretCredential $ClientSecretCredential
$URI = "https://graph.microsoft.com/v1.0/users/$TargetMailbox/messages"
$messages = Invoke-mgGraphRequest -Method GET $URI
And the following, if you have had no errors by now, will return the last ten subjects in the target mailbox:
$messages.values.subject
Leave a Reply