PowerShell scripts to Migrate Exchange Mailbox and Distribution Group Send As, Full Access and Send On Behalf Permissions into a CSV file–Part I : Export Script
This post is to introduce a script to export Mailbox Send As, Full Access and Send On Behalf permissions, and also Distribution Group Send As and Send On Behalf permissions into a CSV file, to help you achieve the following objectives:
- You wish to audit the permissions globally set to your mailboxes across the whole organization –> export the permissions, and analyze these within Excel with the power of “Format As Table”, filtering, pivot tables, … and why not, make executive reports of these permissions with our powerful PowerBI ! I'll also blog later on this one for a couple of examples...
- You wish to migrate your mailboxes and your Distribution Groups to another forest, and you wish to keep the Send As, Full Access and Send On Behalf permissions. That’s in case you’re migrating your mailboxes cross forest not using the New-MoveRequest cmdlet cross forest, because these will keep those permissions (see this older but still accurate post from the Exchange Product Team for more information)
This is the Part I which introduces and gives you the script to export the Mailbox / Distribution Groups permissions, named Export-MailboxFASAPermissions.ps1 ("FASA" stands for Full Access and Send As - although the scripts include the export/import of the Send On Behalf permissions as well). I'll refer to that script as to EXPORT script in this articles quick series (Export/Import - a bit equivalent to Migrate).
The Part II will come later and introduce the Import-MailboxFASAPermissions.ps1. I’ll refer to this Import-MailboxFASAPermissions.ps1 as to “IMPORT script”.
NOTE 1: in the case of permissions "migration", which is nothing else than an Export of the permissions from an environment, to later import these to a target environment. The key used to match users between the source forest and the target forest will be the user SMTP address for the mailboxes to re-populate with permissions – because an SMTP address uniquely identifies a mailbox.
NOTE 2: When exported with Get-ADPermission or Get-MailboxPermission, the Send As and Full Access permissions are referenced with DOMAIN\Alias of the users. When exported with Get-Mailbox, GrandSendOnBehalfTo permissions are referenced with the DOMAIN/OU1/SUB-OU/Alias type notation.
The EXPORT script exports the Send As and Full Access permissions in the form DOMAIN\Alias. If you import in a different forest, the IMPORT script will let you specify a domain to populate these permissions in the form of TARGET_DOMAIN\Alias - easily achieved by splitting the SOURCE_DOMAIN\alias string using the "\" as a separator, and concatenating the "alias" with the "TARGET_DOMAIN" using PowerShell's "-Join" of "$MyArray.Join("\")" method (by default the IMPORT Script will import these permissions as they were on the source environment, using SOURCE_DOMAIN\Alias).
NOTE 3: GrantSendOnBehalfTo can only be given to Mailbox-Enabled users, Mail-Enabled Users, or Mail-Enabled Security Groups. These are exported in the notation indicated in NOTE 2, but the script converts these to their SMTP Address – remember the GrantSendOnBehalfTo can only contain Mailbox-Enabled users, Mail-enabled users or mail-enabled security groups => that way, the Get-Recipient cmdlet resolves the DOMAIN/OU1/SUB-OU/…/Alias into an SMTP address => since an SMTP address uniquely identify a recipient, converting the DOMAIN/OU/…/Alias notation to an SMTP address in the CSV file simplifies the Import as well, as we will just use Set-Mailbox <MailboxSMTPAddress> –GrantSendOnBehalfTo “User1SMTPAddress”, “User2SMTPAddress”, “…” which will work provided the UserxSMTPAddress exist in the target environment.
As an important usage note, you'll notice on the Get-Help dump below that the script has 3 syntaxes:
- One that exports Shared and Resource mailboxes only
.\Export-MailboxFASAPermissions.ps1 -SharedMailboxes -ResourceMailboxes
- One that exports Distribution group with the option to Include or not the Dynamic Distribution groups
.\Export-MailboxFASAPermissions.ps1 -DistributionGroupsOnly -IncludeDynamic $true/$false
- One that checks the script version
There is one other use which is just launching the script without options:
This will export all the Mailboxes permissions.
Here’s the help of the EXPORT script – the download link is at the very end of the help dump:
PS>get-help .\Export-MailboxFASAPermissions.ps1 -full NAME .\Export-MailboxFASAPermissions.ps1 SYNOPSIS Export Exchange Mailbox Send As, Full Access, and Send On Behalf permissions in a CSV file in order to later import them in another environment using the output CSV file. SYNTAX .\Export-MailboxFASAPermissions.ps1 [[-SharedMailboxes]] [[-ResourceMailboxes]] [[-OutputFile] <String>] [<CommonParameters>] .\Export-MailboxFASAPermissions.ps1 [[-DistributionGroupsOnly]] [[-IncludeDynamic] <Boolean>] [<CommonParameters>] .\Export-MailboxFASAPermissions.ps1 [[-CheckVersion]] [<CommonParameters>] DESCRIPTION This script requires the Exchange tools to run. It exports the following Exchange Mailbox permissions in a CSV file - Send As - Full Access - Send On Behalf To in order to be able to import them later in another environment using the output CSV file. The Output CSV file will contain the following information for each mailbox permissions information exported: Display Name, Primary SMTP Address, Full Access permissions, Send As permissions, Send On Behalf permissions The permissions can have one or more entries, which will be separated by semicolons (";") To import back the permissions if needed , you can use the associated Import-MailboxFASAPermissions.ps1 script. Since the Send As and Full Access permissions can be granted to non-mailbox or non-mail enabled users, these are stored in the CSV in the form of DOMAIN\Alias. On the other hand, the Send On Behalf permission can be granted only to mailbox-enabled users, mail-enabled users and/or mail-enabled security groups only. For some reason, it is stored in the form of DOMAIN\OU1\Sub-OU1\...\Name - then, the script is designed to convert these - actually the script resolve these using Get-Mailbox -Identity DOMAIN\OU\...\Name to get and store the PrimarySMTPAddress of these users so that we have two advantages: > Not only we are sure that each SMTP address represents a unique user > Also it will be way easier for the IMPORT script to import these permissions back, wherever OU the target user will be located ! This is because the IMPORT script uses Set-Mailbox with the -SendOnBehalfTo, where we can specify an SMTP address, which will be converted to the corresponding DOMAIN\OU\Name of the corresponding user in the target environment. In other words, the SMTP address will be the KEY to match the SendOnBehalfTo permission to the right users and mailboxes on the target environments. PARAMETERS -SharedMailboxes [<SwitchParameter>] This indicates the script to export the SharedMailboxes only When combined with the -ResourceMailboxes, the script will export the Shared Mailboxes, and the Room and Equipment Mailboxes as well ! To export ALL mailboxes, just don't specify neither the SharedMailboxes nor the ResourceMailboxes parameter. Required? false Position? 1 Default value False Accept pipeline input? false Accept wildcard characters? false -ResourceMailboxes [<SwitchParameter>] This indicates the script to export the ResourceMailboxes only which consist of the Room and the Equipment Mailboxes. When combined with the -SharedMailboxes, the script will export the Shared Mailboxes, the Room and the Equipment mailboxes as well ! To export ALL mailboxes, just don't specify neither the SharedMailboxes nor the ResourceMailboxes parameter. Required? false Position? 2 Default value False Accept pipeline input? false Accept wildcard characters? false -DistributionGroupsOnly [<SwitchParameter>] Required? false Position? 4 Default value False Accept pipeline input? false Accept wildcard characters? false -IncludeDynamic <Boolean> Required? false Position? 5 Default value True Accept pipeline input? false Accept wildcard characters? false -OutputFile <String> Sets the file to which we want to store the results. By default, the script will generate a CSV report with the name of the script, with the date and time appended to it. Required? false Position? 6 Default value Accept pipeline input? false Accept wildcard characters? false -CheckVersion [<SwitchParameter>] This parameter just dumps the script version. Required? false Position? 7 Default value False Accept pipeline input? false Accept wildcard characters? false <CommonParameters> This cmdlet supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer, PipelineVariable, and OutVariable. For more information, see about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216). INPUTS The script will scan all the mailboxes, but database by database to avoid to use all the RAM of the machine from which it's executed. OUTPUTS A CSV file with either a name that you specify with the OutputFile parameter, or if not, the name of the script, containing the users Display Names, primary SMTP addresses, and the list of Send-As, Full Access and SendOnBehalfTo for each of these mailboxes. If the Send-As, Full Access and SendOnBehalfTo are multi-values, they are stored in the columns as semi-colon separated values, like Value1;value2;value3;... => when processing each permissions set, just use something like $ImportedCSV.SendAsPermissions -split ";" or $ImportedCSV.SendAsPermissions.Split(";") ... NOTES This script can be use alone to export a permissions map, but the output is designed so that it can be used with the Import-MailboxFASAPermissions.ps1 script to migrate permissions to another environment such as a LAB or a brand new one with the same users (Inter-Forest migration for example or move from an On-Prem to an outsourced environment such as Office 365) Some simple facts about the permissions exported on this script: "Sens As" permissions . Stored in the form of "DOMAIN\Alias" . Is set with Add-ADPermission . https://docs.microsoft.com/en-us/powershell/module/exchange/active-directory/Add-ADPermission?view=exchange-ps "Full Access" Permissions . Stored in the form of "DOMAIN\Alias" as well . Is set with Add-MailboxPermission . https://docs.microsoft.com/en-us/powershell/module/exchange/mailboxes/Add-MailboxPermission?view=exchange-ps "Send On Behalf Of" permissions . Stored in the form of "Domain.com/OU_Name/Sub_OU/Name" . Is set with Set-Mailbox . https://docs.microsoft.com/en-us/powershell/module/exchange/mailboxes/Set-Mailbox?view=exchange-ps . -GrantSendOnBehalfTo parameter accepts one or more values from the below : Display name Alias Distinguished name (DN) Canonical DN <domain name>\<account name> Email address GUID LegacyExchangeDN SamAccountName User ID or user principal name (UPN) -------------------------- EXAMPLE 1 -------------------------- PS C:\>.\Export-MailboxFASAPermissions.ps1 Will run the script and export the mailbox Display Names, primary SMTP Addresses, and all the Send As, Full Access and Send On Behalf To permissions on a CSV file. -------------------------- EXAMPLE 2 -------------------------- PS C:\>.\Export-MailboxFASAPermissions.ps1 -OutputFile C:\temp\EnvironmentPermissions.csv Will run the script and export permissions for all mailboxes, in the file specified on the OutputFile parameter : C:\temp\EnvironmentPermissions.csv -------------------------- EXAMPLE 3 -------------------------- PS C:\>.\Export-MailboxFASA.ps1 -SharedMailboxes Will run the script and export the Shared Mailboxes permissions as well as the Room and Equipment Mailboxes permissions, and store the result on the default CSV file named after the script, appended with the date and time of the execution, on the script directory -------------------------- EXAMPLE 4 -------------------------- PS C:\>.\Export-MailboxFASA.ps1 -ResourceMailboxes c:\temp\ResourceMailboxPermissions.csv Will run the script and export only the Room and Equipment Mailboxes permissions, and store the results in a CSV file c:\temp\ResourceMailboxPermissions.csv -------------------------- EXAMPLE 5 -------------------------- PS C:\>.\Export-MailboxFASA.ps1 -DistributionGroupsOnly Will run the script and export only the Distribugion Group permissions (Send As, GrantSendOnBehalfTo) in the default Output file format (Script_Name_Date_time.csv). This includes the Dynamic Distribution Groups. -------------------------- EXAMPLE 6 -------------------------- PS C:\>.\Export-MailboxFASA.ps1 -DistributionGroupsOnly -IncludeDynamic $false Will run the script to export permissions of Distribution Groups, excluding the Dynamic Distribugion Groups. RELATED LINKS https://technet.microsoft.com/en-ca/library/jj919240(v=exchg.150).aspx https://docs.microsoft.com/en-us/powershell/module/exchange/active-directory/add-adpermission?view=exchange-ps https://technet.microsoft.com/en-us/library/jj919240(v=exchg.150).aspx https://github.com/SammyKrosoft