Improved handling of Mailbox permissions in Exchange Online

As I was making some changes to the Mailbox permissions inventory script, I noticed few new parameters made available for the Get-MailboxPermission cmdlet. So it was only natural to take them for a spin.

The parameters in question include -IncludeUnresolvedPermissions and -IncludeSoftDeletedUserPermissions, as well as the generic -SoftDeletedMailbox. Here are their corresponding descriptions from the online help document:

• IncludeSoftDeletedUserPermissions – returns permissions from soft-deleted mailbox users in the results. In other words, if you have granted access to a given user, and then soft-deleted his account, you can use the –IncludeSoftDeletedUserPermissions switch to return such entries in the Get-MailboxPermission cmdlet output. If you do not specify the switch, entries corresponding to soft-deleted mailboxes will be omitted.
• IncludeUnresolvedPermissions – returns unresolved permissions in the results. Those correspond to entries that no longer exist in the directory, aka orphaned entries.
• SoftDeletedMailbox – is required to return soft-deleted mailboxes in the results. This also includes any inactive mailboxes. Use the switch when you want to include soft-deleted/inactive mailboxes in your report, without it a “object not found” error will be thrown.

Since an example is worth a thousand words, here’s how the aforementioned parameters can be used. Let’s say we have a mailbox called “shared”, and we’ve granted few people Full access permissions over it. Here’s what the Get-MailboxPermission output looks like, with the NT AUTHORITY\SELF entries removed for brevity:

Let’s say we now remove the huku@pta.michev.info user, putting it into a soft-deleted state. What happens with the permissions? If we run the Get-MailboxPermission cmdlet again, we will notice that the entry is missing. If we specify the -IncludeSoftDeletedUserPermissions parameter as well however, we will see the entry is still present, as illustrated on the screenshot below.

And this is what the –IncludeSoftDeletedUserPermissions parameter is used for, in a nutshell. If at some point later you recover the soft-deleted mailbox, the permission entry will auto-appear in the “regular” Get-MailboxPermission output, and you no longer need to specify the switch. The –IncludeUnresolvedPermissions switch works in a similar fashion, but for “orphaned” entries. The biggest difference between the two is that you cannot “recover” orphaned entries.

Lastly, let’s also showcase how the -SoftDeletedMailbox switch works. Basically, you use it to force the Get-MailboxPermission cmdlet to return output for soft-deleted (and/or inactive) mailboxes. Without the parameter, an error will be thrown. With it, you can expect the regular output to appear:

An interesting thing to note in the output is that the identity of the soft-deleted object is prefixed with “Soft Deleted Objects”, which is the name of the Organizational Unit where such objects are stored. On the other hand, the User property value returned for permissions granted to soft-deleted mailboxes does not include the prefix, which makes it a bit harder to handle.

Speaking about the output, you might also note that the UserSid property is now returned. Unfortunately, the Get-Mailbox cmdlet does not resolve SID values, and while you can use the Get-User cmdlet instead, this one does not support the -SoftDeletedMailbox switch (whereas Get-Mailbox does). But, there is a workaround you can use here too – specify the –OrganizationalUnit parameter with value of “Soft Deleted Objects” and voila:

And while we’re discussing working/non-working parameters, it looks like the -Gr0upMailbox switch of the Get-MailboxPermission cmdlet cannot be used against any Unified group identifier. Which is fine I suppose, as we still don’t have a way of granting mailbox-level permissions on Group mailbox objects.

One more thing – we can now grant permissions to service principal objects too! To do this, you first need to “copy” the service principal object and create a representation of it within ExODS. Don’t ask me why Microsoft isn’t doing this automatically, it is what it is. Anyway, to create an (ExO) Service principal, use the New-ServicePrincipal cmdlet and provide values for the –AppId (clientID) and –ServiceId (objectId) parameters, and optional –DisplayName. For example:

Interestingly enough, NO validation is made for the values you provide, so you can create something at random. Which makes it that more important to carefully fetch the real values from either the Azure AD UI, PowerShell or the Graph API!

Once the Service principal object has been created, you can use it to delegate permissions. To obtain a list of service principal objects, use the Get-ServicePrincipal cmdlet. Even though a new value for RecipientTypeDetails seems to have been added, ServicePrinciple (note the different spelling!), it’s not currently possible to query service principal objects via Get-Recipient or any other cmdlet, only the Get-ServicePrincipal works. Anyway, to grant permissions, use the familiar syntax:

And you can of course query the permissions:

Only Full mailbox permissions seem to be supported at this point, you cannot delegate folder-level access to a service principal object.

Lastly, it’s worth mentioning that we can still use the –ReadFromDomainController parameter to force the full mailbox object to be returned. Unfortunately, this only works for the mailbox for which we’re querying the permissions, but still it’s a valuable way to peek behind the curtain of the Exchange Online directory.