Script to Backup and Restore Distribution Group Members and Owners Using ImmutableId in Azure AD

This script facilitates the backup and restoration of Azure AD distribution group members and owners by ImmutableId across two different tenants. The script retrieves distribution groups from the source tenant, along with their members and owners, and exports them into XML files. It then restores the groups in the destination tenant, comparing and syncing members and owners based on their ImmutableId. The script also includes functions for renaming backup folders and replacing tenant-specific information in XML files during the migration process.

Here is the script:

This script restore the members by ImmutableId!!!

$backupFolder = “$home\Documents\GroupsBackup”

Source and destination tenant domain names

$sourceTenantDomain = "" $sourceTenantDomainName =@("", “oXXXclXud.works”) $destinationTenantDomain = "" $destinationTenantDomainName = "" function New-DirectoryIfNotExist { param( [string]$Path )

if (Test-Path -Path $Path -PathType Container) { $FolderProperty = Get-ItemProperty $Path $date = ($FolderProperty.CreationTime.ToString()).Split(’/’) $date += $date[2].Split(’ ’) $date += $date[4].Replace(’:’, ”)

$suffix = ’-’ + $date[3] + ’-’ + $date[1] + ’-’ + $date[5] $NewName = ‘GroupsBackup’ + $suffix Rename-Item -Path $Path -NewName $NewName }

New-Item -ItemType Directory -Path $Path | Out-Null Write-Output “Directory ‘$Path’ created.” } function Get-UserInfo ($UserId) { $User = $Script:UsersCache | Where-Object {$_.Id -eq $UserId} if ($null -eq $User) { $User = Get-MgUser -UserId $UserId -Property Id,UserPrincipalName,OnPremisesImmutableId | Select-Object Id,UserPrincipalName,OnPremisesImmutableId $Script:UsersCache += $User } return $User } function Backup-Groups { $Script:UsersCache = @() New-DirectoryIfNotExist -Path $backupFolder

try { Connect-ExchangeOnline -Organization $sourceTenantDomain -ErrorAction Stop Connect-MgGraph -TenantId “$sourceTenantDomain” -Scopes “User.Read.All”,“User.ReadBasic.All”,“Directory.Read.All” -ErrorAction Stop } catch { Write-Output “Failed to connect to the source tenant. Error: $($_.Exception.Message)” return }

try { $allGroups = Get-DistributionGroup | Where-Object {$false -eq $.IsDirSynced -and (“MailUniversalDistributionGroup” -eq $.RecipientTypeDetails -or “MailUniversalSecurityGroup” -eq $.RecipientTypeDetails)} } catch { Write-Output “Failed to retrieve groups. Error: $($.Exception.Message)” return }

foreach ($sourceGroup in $allGroups) { Write-Output “Backing up $($sourceGroup.DisplayName)” try { $sourceGroupMembers = @() $GroupMembers = Get-DistributionGroupMember -Identity $($sourceGroup.Guid) | Where-Object RecipientType -eq “UserMailbox” | Select-Object -ExpandProperty ExternalDirectoryObjectId -ErrorAction SilentlyContinue if ($GroupMembers){ $GroupMembers | ForEach-Object { $sourceGroupMembers += Get-UserInfo -UserId $_ } } if ($sourceGroup.ManagedBy){ $sourceGroupOwner = @() foreach ($GroupOwner in $($sourceGroup.ManagedBy)) { $sourceGroupOwner += Get-UserInfo -UserId $GroupOwner } }

$exportPath = Join-Path -Path $backupFolder -ChildPath ”$($sourceGroup.Guid)_$($sourceGroup.DisplayName)”

$xmlPath = $exportPath + ‘_Info.xml’ $sourceGroup | Export-Clixml -Path $xmlPath

$xmlPath = $exportPath + ‘_members.xml’ $sourceGroupMembers | Export-Clixml -Path $xmlPath

$xmlPath = $exportPath + ‘Owner.xml’ $sourceGroupOwner | Export-Clixml -Path $xmlPath } catch { Write-Output “Failed to backup group $($sourceGroup.DisplayName). Error: $($.Exception.Message)” } } } function Set-HashTableData ($Object){ $hash = @{} $Object.psobject.properties | ForEach-Object {$hash[$.Name] = $.Value } return $hash } function Restore-Groups { $Script:UsersCache = @() if (Test-Path -Path $backupFolder -PathType Container) { $AllGroups = @() $xmlFiles = Get-ChildItem -Path $backupFolder

$xmlFiles | Where-Object Name -Like “*Info.xml” | ForEach-Object { $AllGroups += Import-Clixml -Path $.FullName }

try { Connect-ExchangeOnline -Organization $destinationTenantDomain -ErrorAction Stop Connect-MgGraph -TenantId “$destinationTenantDomain” -Scopes “User.Read.All”,“User.ReadBasic.All”,“Directory.Read.All” -ErrorAction Stop } catch { Write-Output “Failed to connect to the destination tenant. Error: $($_.Exception.Message)” return }

$GroupsInfo = @()

foreach ($sourceGroup in $AllGroups) { try { $destinationGroup = Get-DistributionGroup -Filter “Alias -eq ’$($sourceGroup.Alias)’” -ErrorAction SilentlyContinue

if ($null -eq $destinationGroup) { if ($($sourceGroup.GroupType) -Like “SecurityEnabled”){ $sourceGroup | Add-Member -Name ‘Type’ -Value ‘Security’ -MemberType NoteProperty } #$sourceGroup = $sourceGroup |Select-Object -ExcludeProperty OrganizationalUnit,SamAccountName,Identity $NewGroupHash = Set-HashTableData -Object ($sourceGroup |Select-Object Alias,Name,BccBlocked,BypassNestedModerationEnabled,CopyOwnerToMember,Description,DisplayName,MemberDepartRestriction,MemberJoinRestriction,ModeratedBy,ModerationEnabled,Notes,PrimarySmtpAddress,RequireSenderAuthenticationEnabled,SendModerationNotifications,Type) Write-Output “Creating new group $($sourceGroup.Alias)” $destinationGroup = New-DistributionGroup @NewGroupHash -ErrorAction Stop }

$GroupsInfo += @{ sourceGroupID = $($sourceGroup.Guid); GroupDisplayName = $($sourceGroup.DisplayName); destinationGroupID = $($destinationGroup.Guid) }

$exportPath = Join-Path -Path $backupFolder -ChildPath ”$($sourceGroup.Guid)_$($sourceGroup.DisplayName)” $xmlPath = $exportPath + ‘members.xml’ $sourceGroupMembers = Import-Clixml -Path $xmlPath $destinationGroupMembers = @() $GroupMembers = Get-DistributionGroupMember -Identity $destinationGroup.Guid | Where-Object RecipientType -eq “UserMailbox” -ErrorAction SilentlyContinue | Select-Object -ExpandProperty ExternalDirectoryObjectId if ($GroupMembers){ $GroupMembers | ForEach-Object { $destinationGroupMembers += Get-UserInfo -UserId $ } }

foreach ($sourceMember in $sourceGroupMembers) { if ($sourceMember.OnPremisesImmutableId -notin $destinationGroupMembers.OnPremisesImmutableId) { $userToAdd = Get-MgUser -Filter “OnPremisesImmutableId eq ’$($sourceMember.OnPremisesImmutableId)’” -Property id,UserPrincipalName if ($userToAdd) { Add-DistributionGroupMember -Identity $destinationGroup.Guid -Member $userToAdd.UserPrincipalName } } }

foreach ($destinationMember in $destinationGroupMembers) { if ($destinationMember.OnPremisesImmutableId -notin $sourceGroupMembers.OnPremisesImmutableId) { Remove-DistributionGroupMember -Identity $destinationGroup.Guid -Member $destinationMember.UserPrincipalName } }

if($destinationGroup.ManagedBy){ $destinationGroupOwner =@() foreach ($GroupOwner in $destinationGroup.ManagedBy) { $destinationGroupOwner += Get-UserInfo -UserId $GroupOwner } }

$xmlPath = $exportPath + ‘_Owner.xml’ $sourceGroupOwner = Import-Clixml -Path $xmlPath foreach ($sourceOwner in $sourceGroupOwner) { if ($sourceOwner.OnPremisesImmutableId -notin $destinationGroupOwner.OnPremisesImmutableId) { $userToAdd = Get-MgUser -Filter “OnPremisesImmutableId eq ’$($sourceOwner.OnPremisesImmutableId)’” -Property Id,UserPrincipalName if ($userToAdd) { Set-DistributionGroup -Identity $destinationGroup.Guid -ManagedBy @{Add=”$($userToAdd.UserPrincipalName)”} } } }

foreach ($destinationOwner in $destinationGroupOwner) { if ($destinationOwner.ImmutableId -notin $sourceGroupOwner.ImmutableId) { $userToRemove = Get-MgUser -Filter “OnPremisesImmutableId eq ’$($sourceOwner.OnPremisesImmutableId)’” -Property Id,UserPrincipalName Set-DistributionGroup -Identity $destinationGroup.Guid -ManagedBy @{Remove=”$($userToRemove.UserPrincipalName)”} } }

} catch { Write-Output “Failed to restore group $($sourceGroup.DisplayName). Error: $($_.Exception.Message)” } }

$path = Join-Path -Path $backupFolder -ChildPath ”.GroupsInfo.csv” $GroupsInfo | Export-Csv -Path $path } }

Function to find and replace keywords in XML file

function FindAndReplaceKeywordsInXML { param ( [string]$FilePath, $Keywords )

# Read the content of the XML file $content = Get-Content -Path $FilePath -Raw

# Check if the file contains any of the specified keywords $foundKeywords = $Keywords | Where-Object { $content -match $_ }

if ($foundKeywords.Count -gt 0) { # Replace the keywords with “I_Find_U” $content = $content -replace ($Keywords -join ’|’), “$destinationTenantDomainName”

# Save the modified content back to the same file $content | Set-Content -Path $FilePath Write-Output “Keywords replaced in $FilePath” } else { Write-Output “No keywords found in $FilePath” } } function Convert-Domains { # Set the folder path where XML files are located $FolderPath = $backupFolder

# Set the keywords to search for $Keywords = $sourceTenantDomainName

# Get a list of all XML files in the folder $xmlFiles = Get-ChildItem -Path $FolderPath -Filter “*.xml” -File

# Process each XML file foreach ($file in $xmlFiles) { FindAndReplaceKeywordsInXML -FilePath $file.FullName -Keywords $Keywords } }

Uncomment the following lines to execute the backup or restore functions