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

Hi !

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
 .\Export-MailboxFASAPermissions.ps1 -CheckVersion

There is one other use which is just launching the script without options:

 .\Export-MailboxFASAPermissions.ps1

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

 

CLICK HERE TO GO TO THE TECHNET GALLERY TO DOWNLOAD THIS SCRIPT...