For the next article in our “permissions inventory” series, we will cover mailbox folder permissions. The PowerShell script included in this article will help you generate a detailed report on all (or some) folders across all (or some) mailboxes in the company, along with their permissions. While similar to the previous scenario we covered, namely Calendar permissions, the number of entries we will have to deal in this case is much larger, thus some additional optimizations to the script must be made. Let’s dive right in.
To get the folder level permissions, we will of course again use the Get-MailboxFolderPermission cmdlet. We will also utilize the Get-MailboxFolderStatistics cmdlet to get the list of folders. As this time around the number of folders is much greater, we will wrap the execution via Invoke-Command and only get a minimal set of data back in order to optimize the script execution time.
To further reduce the output, we only cover the “user accessible” folders. Their corresponding folder types are added to the $includedfolders array you can find on line 53. The list is still big enough, so feel free to remove some of the entries you don’t care about from it, such as the Outbox folder. A trimmed down version is provided on line 54, but you can also input your own list.
Similarly, an $excludedfolders array is used to filter out unwanted non-default (or “user created”) folders. The array can be found on line 58 and lists the folder names, not the folder type. Examples include folders such as the “News feeds” or “Suggested Contacts”, but as before, feel free to add to the list. The more folders you exclude here, the faster the script will run!
The following script block illustrates the logic described above – get the list of all the folders with a minimal set of properties, then filter it out to only return folders we are interested in:
Any user-created (sub)folder will still be present in the output after the filtering operation, unless you have explicitly included its name in the $excludedfolders array as detailed above.
As customary, the script includes several parameters to control the recipient types included in the output. By default, only User mailboxes are included (the –IncludeUserMailboxes switch), but you can also opt to include Shared (-IncludeSharedMailboxes), Room and Equipment (-IncludeRoomMailboxes) or All of the above types of mailboxes (-IncludeAll). Team, Discovery and Group mailboxes are not included, but the script can easily be amended to account for them if needed.
For the actual output, you can choose between the default one-line per permission entry or the “condensed” output, which reduces the output to one line per folder. This is controlled via the –CondensedOutput switch. Examples of the two types of output are depicted below:
As seen from the screenshots, the number of entries in the “condensed” output will be smaller, however filtering the permissions entries will require additional steps. Do let us know which method you prefer!
To finish up on the output topic, the script will automatically generate a CSV file and will also store the output in the global $varPermissions variable if you want to transform it before saving. You can specify another variable name using the –OutVariable parameter.
Next, a parameter is provided in order to control the inclusion of the Default permission entries for folders, namely the –IncludeDefaultPermissions switch. This can be important in situations where you are troubleshooting folder access, for example a common scenario is for people to forget to grant permissions on the Root folder when sharing Inbox or another folder. For that reason, some companies choose to pre-configure the Default level of permissions on the Root folder. Of course, the Default level applies to all users in the company, so if there are any permissions set on it, you might want to know about them. However, those permissions are not included unless you run the script with the aforementioned switch, as they substantially increase the number of entries in the output.
Lastly, the –ExcludeUsers parameter is provided in order to allow you to exclude permission entries for certain accounts from the output. For example, an administrative account that has been granted permissions to all or a group of mailboxes, or a service account that needs to access particular folder(s). The parameter requires you to provide the SMTP address of the user you want to exclude and accepts multiple entries separated by comma. Here’s an example usage:
.\Mailbox_Folder_Permissions_inventory.ps1 -ExcludeUsers admin@domain.com,serviceaccount@domain.com
Additional examples on the script usage can be found in the built-in help. It’s worth mentioning that the script does not include any code to handle Exchange Online connectivity, you will have to take care of this part yourself. If no valid Exchange Online session is detected, the script will fail.
The script file can be downloaded from the TechNet Gallery here: https://github.com/michevnew/PowerShell/blob/master/Mailbox_Folder_Permissions_inventory.ps1
Now, some additional warnings are due. Running the script against a large number of mailboxes can take hours to complete – not only the script is cycling over each mailbox, but for each mailbox 15 folders or so are covered. And that’s by default, not accounting for any user-created folders. Make sure to adjust the $includedfolders and $excludedfolders arrays to only cover folders you are interested in!
Even with a reduced set of folders to check, it’s likely that you run into some throttling issues or broken PowerShell sessions. The script offers a very basic way to overcome such issues, by adding some delay between cmdlet execution (line 101), which you can adjust as necessary. In addition, you can uncomment line 145/170 to make sure the script writes output to the CSV file after each iteration. For a proper solution, refer to this article for tips on how to run PowerShell scripts against large number of objects in Exchange Online.
3 thoughts on “Office 365 Permission Inventory: Mailbox folder permissions”