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:

Get-MailboxFolderPermission HuKu:\Calendar

FolderName           User                 AccessRights          SharingPermissionFlags
----------           ----                 ------------          ----------------------
Calendar             Default              {LimitedDetails}
Calendar             Anonymous            {None}

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:

Add-MailboxFolderPermission huku:\calendar -User vasil -AccessRights Editor -SharingPermissionFlags Delegate

FolderName           User                 AccessRights         SharingPermissionFlags
----------           ----                 ------------         ----------------------
Calendar             Vasil Michev         {Editor}             Delegate

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:

Set-MailboxFolderPermission huku:\calendar -User vasil -AccessRights Editor -SharingPermissionFlags Delegate,CanViewPrivateItems

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

Get-MailboxFolderPermission HuKu:\Calendar

FolderName           User                 AccessRights           SharingPermissionFlags
----------           ----                 ------------           ----------------------
Calendar             Default              {LimitedDetails}
Calendar             Anonymous            {None}
Calendar             Vasil Michev         {Editor}               Delegate, CanViewPrivateItems

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:

Set-MailboxFolderPermission huku:\calendar -User vasil -AccessRights Editor -SharingPermissionFlags None

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

Remove-MailboxFolderPermission huku:\calendar -User vasil

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.

This entry was posted in Exchange Online, Office 365, PowerShell. Bookmark the permalink.

21 Responses to Managing Outlook delegates via PowerShell

  1. Robert says:

    Doesn’t the resource delegate option in Get-CalenderProcessing show the delegates for the mailbox?

  2. Robert says:

    One last question how does the (Get-CalendaProcessing Delegate Column) relate to the options you discussed in this blog post?

    I seem to have some confusion between the Delegate Column and the Options described by you.

    • Vasil Michev says:

      Simply ignore the Get-CalendaProcessing output, the ResourceDelegates attribute shown there can be set independently of the options detailed here (and the Outlook delegate settings). Or let me rephrase that, if you use the cmdlets above or the Outlook delegate setting, it should set the ResourceDelegates attribute as well, but there are other scenarios where this is not true.

      They have made some changes recently that limit the ways to modify ResourceDelegates (https://www.michev.info/Blog/Post/1744/controlling-resource-delegates-for-user-mailboxes), but there are still some “workarounds” left. The SharingPermissionFlags value is what you should be looking at, or the actual ReceiveCopiesOfMeetingMessages property that’s exposed via EWS.

      For example, I can add a “delegate” in Outlook that doesn’t have access to my Calendar folder at all, and it can still show up in ResourceDelegates. However, the SharingPermissionFlags will be empty.

      • Robert says:

        OK I see Thanks. I have always been confused to some degree by the way resource delegates are set and how the setting in outlook corresponds to the setting on the users mailbox.

        Thanks for the clarification.

  3. Jose Byron Gonzalez says:

    Thank you for writing this! It answers my question and it would resolve my problem except that my PS doesn’t want to play ball:

    A parameter cannot be found that matches parameter name ‘SharingPermissionsFlags’.
    + CategoryInfo : InvalidArgument: (:) [Add-MailboxFolderPermission], ParameterBindingException
    + FullyQualifiedErrorId : NamedParameterNotFound,Add-MailboxFolderPermission

    Do I need to update something, since it doesn’t show the new column in the output for Get-MalboxFolder Permission?

    • Vasil Michev says:

      This only works against Office 365, more specifically the Multi-tenant version of O365. If you are using on-premises Exchange or any of the other variations of O365, you will have to wait until the feature is released there.

  4. Asger says:

    Thanks for a lot of great tips.
    I have one question related to this post.

    We have a user who needs full access to a shared mailbox (not a user’s mailbox) including all subfolders, sent, drafts etc. but only reviewer rights to the calendar including private items.
    I’ve tried to use the above mentioned commands, but he still can edit the calendar.
    Delegate access has been granted from EAC.
    Any suggestions?

  5. Asger says:

    Thanks so very much!
    Much appreciated.

    Funny that “allows” (delegation) overrules “Denies” (reviewer limitations)
    On Windows server, deny will always overrule allow..

  6. Lars says:

    The following painful method allows sharing a calendar giving the same access as would be achieved in Office 365 by using the -SharingPermissionFlags Delegate,CanViewPrivateItems:
    Logon as the calendar user. Start Outlook in Online Mode. Manually share the calendar with editor permissions + allow Viewing Private items.

  7. Ricardo says:

    Thank you for writing this. I was waiting for this for a while. I used the PowerShell command you provided to setup a delegate, but the option of who should be receiving the meeting requests is set to “My delegates only”. Is there a way to change this with PowerShell to any of the other two options? thanks

  8. Filipe Araujo says:

    How do I get this update? I need to achieve “CanViewPrivateItems” but my PS does not currently recognize the expressions. Thanks!

  9. tonakis says:

    Hi,
    related to “delegate receives a copy of meeting-related messages sent to me” option – could that be changed via PS using Set-CalendarProcessing cmdlet ? Thanks!

    • Vasil Michev says:

      The -Delegate flag for Add/Set-MailboxFolderPermissions corresponds to the “delegate receives a copy of meeting-related messages sent to me” (“receivecopiesofmeetingmessages”) option. It’s not the same as the -ForwardRequestsToDelegates parameter we can see/set via Set-CalendarProcessing – this one is global, not configurable per delegate.

      The “Deliver meeting requests addressed to me and responses to meeting requests where I am the organizer to” option (“MeetingRequestsDeliveryScope”) is also a different flag/setting, this one is only controllable via EWS or the Outlook client.

      • tonakis says:

        Thanks for the reply
        I was referring more to the switch – [-RemoveForwardedMeetingNotifications ] set via Set-CalendarProcessing cmdlet which corresponds to “delegate receives a copy of meeting-related messages sent to me”.

Leave a Reply

Your email address will not be published. Required fields are marked *