Managing Outlook delegates via PowerShell

In another example of a small, but impactful change, Microsoft has started rolling out improvements to the PowerShell cmdlets responsible for folder permissions that will allow us to manage some of the delegate-related settings. Two parameters have been added to the *-MailboxFolderPermission cmdlets to facilitate those changes, namely the SendNotificationToUser and SharingPermissionFlags. We will take a look at them in a moment, but first, let’s try to explain what a delegate is and why the changes are important.

What is a delegate

In the Exchange world, a delegate is a person you have given some level of access to over your own mailbox. The access can range from being only able to read your messages, to being able to manage all your email as well as compose and send messages on your behalf. While you can set folder level permissions by right-clicking any of your folders in Outlook and selecting the corresponding menu item, the Delegates dialog under File -> Account settings -> Delegate access exposes some additional controls. It’s easy to use this method to grant permissions on commonly used folders, but more importantly it allows you to control access to Private items and to configure the handling of meeting responses. The corresponding settings are shown on the screenshot below:

Now, as the folder permissions are configurable via other means as well, what is usually referred to as Delegate is a user for which the “delegate receives a copy of meeting-related messages sent to me” setting is configured. This option only becomes available in the UI when the Calendar folder permissions are set to Editor. Once a Delegate is configured for your mailbox, in the sense of configuring the checkbox mentioned above, the “Deliver meeting requests addressed to me and responses to meeting requests where I am the organizer to” option becomes available, and you can decide whether you, the delegate, or both should receive those. In addition, a Delegate also receives Send on behalf of permissions to your mailbox. More information can be found in the official documentation.

Up until now, some of those settings were only configurable via Outlook, and we as administrators were not able to even see their corresponding values, let alone change them, as they were not exposed in the EAC or any of the underlying PowerShell cmdlets. This in turn created situations in which the admin or support person troubleshooting an issue had to “guess” what the related configuration was, or wait for the user to provide the required details. The only way to obtain this information outside of Outlook, or modify it, was via EWS, which required additional configuration and permissions, so it was far from ideal. Still, in some cases it was easier to use EWS instead of having to get to the user in order to check the settings from Outlook, thus administrators often used solutions such as the EWS delegate module.

Configuring a Delegate via PowerShell

With the recently introduced changes, all of this is now possible via PowerShell. To make things easier and to ensure compatibility with any custom scripts you might already be using, the team opted to not introduce any new cmdlets for delegate management. Instead, the familiar Add-/Get-/Remove-/Set-MailboxFolderPermission cmdlets have been updated to handle delegate scenarios.

You might have noticed that the output of the Get-MailboxFolderPermission changed few weeks back, and it now features one additional column, SharingPermissionFlags. So for example, you would see something like this:

Unfortunately, the SharingPermissionFlags property will not always reflect the correct status, but more on this later. Let’s now see how one can configure delegate settings via PowerShell, as in how we can use the Add-MailboxFolderPermission cmdlet with the new parameters. If I want to add myself as delegate for another user, in addition to the customary Identity, User and AccessRights parameters, I will need to also specify the “level” of delegate access via the SharingPermissionFlags parameter. The parameter is a bit quirky, as it requires you to specify multiple values separated with comma for some configurations. More importantly, the SharingPermissionFlags parameter will only work if you have set the AccessRights parameter value to Editor, so make sure to remember that. To specify the fact that the user need to be added as delegate, set the value of SharingPermissionFlags to Delegate. Here’s an example:

Once this option is set, the user (me) will receive the Editor level of access to the Calendar folder, and the mailbox will have the “delegate receives a copy of meeting-related messages sent to me” option enabled, just as described in the previous section. Note that the cmdlet does not expose any way to change the scope of meeting requests delivery controlled by the “Deliver meeting requests addressed to me and responses to meeting requests where I am the organizer to” option. The reasons being, this is a global option and not configurable per delegate, but you can still use Outlook or EWS to control it.

Other uses of the SharingPermissionFlags parameter

If we also want to make sure that the delegate will be able to see Private items, the SharingPermissionFlags parameter needs to include the corresponding CanViewPrivateItems value. This value can only be supplied if Delegate value is also present, and as already mentioned above, if the AccessRights parameter is set to Editor. As we already used the Add-MailboxFolderPermission cmdlet to create a permission entry for that user though, this time we will use the Set-MailboxFolderPermission cmdlet to update it:

To verify the permissions are applied, we can rerun the Get-MailboxFolderPermission cmdlet:

Note that the “Delegate can see my private items” option, corresponding to the CanViewPrivateItems value can technically be configured without requiring the user to be Delegate. This requirement is enforced by the parameter sets for the cmdlet, in order to reflect the “supported” configuration.

You can make additional changes at any point via the Set-MailboxFolderPermission cmdlet, for example, if you want to revoke the delegate-level permissions but still keep the user as Editor on the Calendar, specify the None value for the SharingPermissionFlags parameter:

Or you can remove the entry altogether via the Remove-MailboxFolderPermission cmdlet:

As with other folder level permissions, make sure that no existing entry exists before using the Add-MailboxFolderPermission cmdlet. Otherwise an error will be thrown, and you have to use the Set-MailboxFolderPermission cmdlet or simply remove the entry via the Remove-MailboxFolderPermission cmdlet first.

Using the SendNotificationToUser parameter

The other newly introduced parameter, SendNotificationToUser, serves to generate an email message summarizing the changes made into a “sharing invitation”. It’s the analog of the “Automatically send a message to delegate summarizing these permissions” checkbox in the Outlook Delegate dialog, shown above. The parameter can only be used when configuring permissions for Calendar folders, and only when one of the following AccessRights parameter values is specified: AvailabilityOnly, LimitedDetails, Reviewer or Editor.

Another important thing to note is that the SendNotificationToUser parameter is a Boolean, not a Switch. Thus, whenever you specify it, don’t forget to include the corresponding $true or $false value. I would personally prefer a switch, as it’s a cleaner and easier solution. I would also extend the same argument to the SharingPermissionFlags parameter, and have already left this feedback with Microsoft.

To complete our covering of the SendNotificationToUser parameter, here’s an example of what a “sharing invitation” will look like:

Summary

In this article, we took a quick look at the new parameters introduced to handle delegates in Exchange Online. While the changes to the *-MailboxFolderPermission can be classified as “minor”, they bring a welcome improvement to the way we can report on or set delegate permissions. With the changes discussed above, using EWS will no longer be necessary to accomplish this task, instead we can rely on the familiar PowerShell cmdlets, making the life of the admins easier.

It is important to understand that the new capabilities cannot account for every possible delegate scenario. In some cases, such as configuring the delivery scope of meeting requests, one might still need to resort to using Outlook or EWS. Another example is the requirement that the CanViewPrivateItems flag can only be used when the Delegate flag is set. Similarly, it’s also important to understand that the Get-MailboxFolderPermission might not correctly reflect on changes made via EWS or Outlook, as it only reflects the “supported” configuration.

Lastly, for folks still using on-premises Exchange – the changes detailed here are only available in Exchange Online. At least for the time being.