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.
The Real Person!
The Real Person!
Hi Tony
how can I get report on Audit mailbox permission changes for past 90 days?
Please let me know.
The Real Person!
The Real Person!
For these operations “Add-RecipientPermission,Remove-RecipientPermission,Set-mailbox,Add-MailboxPermission,Remove-MailboxPermission”
Search the audit log for those operations for the last 90 days, then use PowerShell to format the audit events into a report.
The Real Person!
The Real Person!
Do you have any script ready similar to this request?
I could say that you should buy a copy of the Office 365 for IT Pros eBook and learn how to extract information from the audit log because that knowledge will be of benefit to you in the future… That’s the logical course of action to take. Any script that you find on the internet might not work because you don’t understand how the code functions.
But if you insist, try https://office365itpros.com/2024/11/15/file-operations-audit-events/
The Real Person!
The Real Person!
Hi Tony
I am regular subscriber of your Office 365 for IT Pros eBook. Did not find any related to this. What is the page number?
Regards
Chapter 20 for information about the audit log.
Is there a similar script for capturing & notifying OneDrive permission changes as well?
I haven’t written one, but feel free to create a script!
Hello Tony,
An unusual question: How can I color code Granted to: $($User.GrantedTo)
Display name of the user? that means color code the variable.
Thank you
Use the font color tag. https://www.javatpoint.com/how-to-change-text-color-in-html
I figured it out.
Thank you
We considered implementing something like this a while ago. We didn’t go through with it as the person being given the rights could well have permission to delete the notification message from the mailbox.
If you’re aware of a way to force a message to persist in a mailbox for X days, we’re all ears!
I wonder if I assigned a sensitivity label to the message that prevented its deletion…and then cleaned things up automatically with a background job…