Bulk Set Exchange Online Mailbox Calendar Permissions via PowerShell

Managing calendar permissions in Exchange Online can become a repetitive and time-consuming task if you need to update them for multiple mailboxes at once. Whether you want to assign “LimitedDetails,” “AvailabilityOnly,” or other custom access rights to a security group or the default user, PowerShell provides a fast and scalable solution. In this article, I’ll show you how to bulk set mailbox folder permissions (e.g., Calendar/Agenda) across all mailboxes in your domain with a single script, and we’ll also explore the various types of folder permissions you can set.

Why Bulk Update Permissions?

• Consistency: Ensure uniform permissions across all users’ mailboxes.
• Time-Saving: Automate repetitive tasks for large environments.
• Scalability: Easily adapt to multiple Exchange Online tenants or on-premises Exchange environments.
• Control & Security: Quickly apply or adjust access to meet organizational or compliance requirements.

Prerequisites

1. Install and Connect to Exchange Online PowerShell
   You need the latest Exchange Online PowerShell module.
   • Open PowerShell as an administrator and install it (if not already installed):
     Install-Module ExchangeOnlineManagement
   • Connect to your Exchange Online environment:
     Connect-ExchangeOnline -UserPrincipalName [email protected]
2. Required Permissions
   Make sure you have sufficient permissions (e.g., Global Administrator or Exchange Administrator) to set mailbox folder permissions across the organization.
3. Script Execution Policy
   Ensure that your PowerShell execution policy allows running scripts. For most cases, you can run:
   Set-ExecutionPolicy RemoteSigned -Scope Process
   This ensures you can execute local scripts within the current PowerShell session.

Common Calendar Folder Permission Levels

Exchange Online (and on-premises Exchange) supports various permission levels for mailbox folders. Below is a quick reference for commonly used permissions you might set on the Calendar folder:

• Owner
  Full rights to the folder, including assigning permissions and deleting all items.
• PublishingEditor
  Create, read, edit, and delete all items; also create subfolders.
• Editor
  Create, read, edit, and delete all items.
• PublishingAuthor
  Create and read items; create subfolders; modify and delete items created by the user.
• Author
  Create and read items; modify and delete items created by the user.
• NonEditingAuthor
  Create items, but cannot edit anything. Can delete items created by themselves.
• Reviewer
  Read items only.
• Contributor
  Create items only; cannot read or modify existing items.
• None
  No permissions to access the folder.
• AvailabilityOnly (sometimes labeled as “FreeBusyTimeOnly”)
  Only shows whether the user is free or busy.
• LimitedDetails (sometimes labeled as “FreeBusyTimeAndSubjectAndLocation”)
  Shows free/busy status as well as subject and location of appointments.

Note: In localized environments, such as Dutch, you might see “Agenda” instead of “Calendar,” or alternative naming for the AccessRights values. Adjust accordingly.

The PowerShell Script

Below is a generic script you can use to bulk assign calendar permissions for all mailboxes matching a specific domain (e.g., @contoso.com).

Note: In an English environment, the default folder name for the calendar is Calendar. In a Dutch environment, the folder might be named Agenda. Customize the script parameters to fit your language and access requirements.

<#
.SYNOPSIS
Bulk sets mailbox folder permissions for all mailboxes in a specified domain.

.DESCRIPTION
- Retrieves all mailboxes with Get-Mailbox -ResultSize Unlimited.
- Filters for mailboxes matching the specified domain.
- Iterates over each mailbox, setting folder permissions for:
   1) A specified user/security group
   2) The default user
- Uses try/catch to handle errors gracefully.
#>

param(
    [Parameter(Mandatory=$true)]
    [string]$Domain,   # e.g. "contoso.com"
    
    [string]$SecurityPrincipal = "YourSecurityGroupOrUser",    # The group or user to grant permissions
    [string]$SecurityPrincipalAccessRights = "LimitedDetails", # Access rights for the above group/user
    
    [string]$DefaultAccessRights = "FreeBusyTimeOnly",         # Access rights for the 'Default' user
    [string]$CalendarFolderName = "Calendar"                   # Usually "Calendar" in English, "Agenda" in Dutch
)

function Set-PermissionSafe {
    param(
        [string]$Identity,
        [string]$User,
        [string[]]$AccessRights
    )

    try {
        Set-MailboxFolderPermission -Identity $Identity -User $User -AccessRights $AccessRights -ErrorAction Stop
        Write-Host "  Success: Set $($AccessRights -join ', ') for '$User' on '$Identity'." -ForegroundColor Green
    }
    catch {
        Write-Host "  Error setting permissions for '$User' on '$Identity':" -ForegroundColor Yellow
        Write-Host "    $($_.Exception.Message)" -ForegroundColor Red
    }
}

Get-Mailbox -ResultSize Unlimited |
    Where-Object { $_.PrimarySmtpAddress -like "*@$Domain" } |
    ForEach-Object {
        $mailboxId = $_.PrimarySmtpAddress
        Write-Host "Processing mailbox: $mailboxId" -ForegroundColor Cyan

        # 1) Set calendar permissions for the specified security group or user
        Set-PermissionSafe -Identity "$mailboxId:\$CalendarFolderName" -User $SecurityPrincipal -AccessRights $SecurityPrincipalAccessRights

        # 2) Set the default permissions
        Set-PermissionSafe -Identity "$mailboxId:\$CalendarFolderName" -User "Default" -AccessRights $DefaultAccessRights

        Write-Host ("-" * 50) -ForegroundColor DarkGray
    }

How to Run This Script

• Save this script as Set-CalendarPermissions.ps1.
• Open a new PowerShell window and connect to Exchange Online using:
  Connect-ExchangeOnline -UserPrincipalName [email protected]
• Execute the script with the required parameters:

.\Set-CalendarPermissions.ps1 -Domain "contoso.com" `
                              -SecurityPrincipal "MySecurityGroup" `
                              -SecurityPrincipalAccessRights "LimitedDetails" `
                              -DefaultAccessRights "FreeBusyTimeOnly" `
                              -CalendarFolderName "Calendar"

• Verify the permissions. For a single mailbox, you can run:
  Get-MailboxFolderPermission -Identity [email protected]:\Calendar

Adapting for On-Premises Exchange

If you’re using Exchange on-premises, you do not need to install the Exchange Online Management module. Instead, open the Exchange Management Shell on the server or use PowerShell remoting to connect to your on-premises Exchange environment. The rest of the script logic remains the same.

Troubleshooting

• Folder Not Found: Ensure you’re using the correct folder name (e.g., “Calendar” vs. “Agenda”).
• Insufficient Permissions: Make sure your admin account has the proper role to run Set-MailboxFolderPermission.
• Script Execution Policy: Adjust the policy if you receive errors about unsigned scripts.
• Double-Check Usernames/Groups: Typos in security group names or email addresses can lead to permission errors.

Bulk-modifying mailbox folder permissions in Exchange Online (or on-premises) doesn’t have to be a tedious task. By leveraging PowerShell and a simple script, you can save time, maintain consistency, and streamline your Microsoft 365 administration. Feel free to customize the script to your organizational needs—such as different folder paths, user or group names, and AccessRights—and share it with your colleagues to simplify Exchange management tasks.