Notifying Exchange Online Users When Administrators Update Mailbox Permissions

Making Sure Users Know Who Can Access Their Mailbox

A reader asks if it is possible to have Microsoft 365 notify users (through email) when administrators grant permissions for their mailbox to other people. Although a user could check themselves with PowerShell (see below), there’s no option in any Outlook client to highlight access by other users. But we can do some PowerShell magic to generate notifications about permission grants.

Granting Mailbox Permissions

To level set, let’s review how administrators grant permissions to a mailbox. The article is about permissions granted for user mailboxes, but Exchange Online also supports granting permissions for shared and group mailboxes. The Microsoft 365 admin center and Exchange admin center (EAC) both include GUI for this purpose. In the EAC, select the user mailbox and access mailbox permissions. Three permissions are available, all of which are well-known to Exchange administrators because they’ve been in the product for many years.

• Read and manage.
• Send as.
• Send on behalf of.

Collectively, these are known as delegate permissions because they allow users to delegate some email processing to other people. Select the desired permission and search for the user(s) to receive the permission (Figure 1), then click Save to make the assignment.

The PowerShell Option

The Microsoft 365 admin center interface is different but has the same effect. In both cases, the options are equivalent to using the Add-MailboxPermission cmdlet to grant full access (Read and Manage) to the mailbox, and the Add-RecipientPermission to allow someone to send email from the mailbox using SendAs (impersonate the mailbox owner) or Send on Behalf Of (marked as sent by the user assigned the permission).

To see what permissions are set for a mailbox, use the Get-ExoMailboxPermission and Get-RecipientPermission cmdlets:

Get-ExoMailboxPermission -Identity Terry.Hegarty@office365itpros.com

User                             AccessRights
----                             ------------
NT AUTHORITY\SELF                {FullAccess, ReadPermission}
Sean.Landy@office365itpros.com   {FullAccess}
Ken.Bowers@office365itpros.com   {FullAccess}
Chris.Bishop@office365itpros.com {FullAccess}
Jack.Carty@office365itpros.com   {FullAccess}

Get-RecipientPermission -Identity Terry.Hegarty@Office365itpros.com

Identity      Trustee                          AccessControlType AccessRights Inherited
--------      -------                          ----------------- ------------ ---------
Terry.Hegarty NT AUTHORITY\SELF                Allow             {SendAs}     False
Terry.Hegarty Chris.Bishop@office365itpros.com Allow             {SendAs}     False

Send on behalf of permission is set by running the Set-Mailbox cmdlet, so to retrieve this permission, we use the Get-ExoMailbox cmdlet.

Get-ExoMailbox -Properties GrantSendOnBehalfTo -Identity Tom.Tierney | Format-List GrantSendOnBehalfTo

GrantSendOnBehalfTo : {James.Ryan, Brian Weakliam, Andy.Ruth}

Now that we understand the assignment of mailbox permissions, let’s consider how to notify mailbox owners about added permissions.

Detecting Mailbox Permission Changes

It is possible to detect permission changes by checking mailboxes and comparing the set of permissions for the mailbox with what existed previously. Of course, you’d have to know what the previous permissions were, and tracking change over thousands of mailboxes would quickly become a nightmare. Another idea is to create a mailbox permissions report and check that to highlight issues. Neither approach scales well.

Use Audit Records

The most efficient way of detecting permission changes is to use the audit records captured in the Office 365 audit log. In this discussion, I focus on assignments of the full access and send as permissions because the audit data captured for these actions are similar. Exchange Online captures audit records for updates to the Send on Behalf Of permission for a mailbox, but the audit data doesn’t include the name of the users who receive the permission. Instead, it contains a list of those who have the permission after the latest assignment.

After checking the audit log to fetch relevant audit records for the last 90 days (you can go back 365 days if the tenant has Office 365 E5 licenses), it’s a matter of parsing the content to extract the information about the new assignee, the assigned permission, and the target mailbox. Some Add-MailboxPermission audit records must be discarded because they’re created by background processing to make sure that the correct permissions exist for system mailboxes. These records are identified by looking for NT AUTHORITY\SYSTEM as the user identifier.

Because assignments could relate to deleted mailboxes, some code is needed to handle this condition. After all, there’s no point in sending notifications to mailboxes which no longer exist.

Sending Notifications About Mailbox Permission Updates

Once we’ve processed the set of audit records for permission changes, the next step is to inform users about the updated permissions for their mailbox. Not wanting to do any more work than necessary, I repurposed the code used to demonstrate how to send email using the Microsoft Graph PowerShell SDK. Briefly, the steps to send email to each user are:

• Set up their email address.
• Customize the HTML content for the message to include details of the permission granted for their mailbox. Details of the current set of users with permission for a mailbox are obtained by running the Get-ExoMailboxPermission (full access) or Get-ExoRecipientPermission (send as) cmdlets.
• Create a draft message in the mailbox of the user who runs the script.
• Send the message.

The biggest code change is to include details of the permission update in the HTML content of the email. Figure 2 shows an example of the message sent to users. I think the text makes it obvious about what’s happened and who has access to their mailbox.

You can download a copy of the script from GitHub.

Enhancements

Like any script written to illustrate a principal, improvements can be made. The rudimentary error checking is an obvious example, but you could also investigate enhancements like:

• Send one message to a user containing details of all permission changes in the period instead of one message per permission update.
• Handle Send on Behalf Of assignments.
• Create a summary report for administrators and send it to them via email.
• Check if assigned permissions are in active use and remove them automatically if they are not (see this example for SendAs permissions).
• Update the code to run in an Azure Automation runbook. In fact, this kind of script is well suited to run using a scheduled runbook where the script might run every week and store its results in a SharePoint Online document library in addition to sending email.

I’ll leave it to the reader to decide what kind of enhancements they’d like to make to the code. Please let us know by adding a comment. You never know how much a shared idea can help others solve a problem they’ve been grappling with for ages.