Why PowerShell Scripts Might Need Updates After Microsoft Changes the Name Property for New Mailboxes

Good and Bad in Every Change

Last month, I discussed the change Microsoft will make to the composition of the Name and Distinguished Name properties for new mailboxes. According to MC365786 (April 30), deployment of the change will start at the end of May to finish in late July. It’s important to emphasize that the Exchange Online Name change applies only to new mailboxes: the properties of existing mailboxes remain intact unless you decide to update them.

Update 30 November 2022: Microsoft continues to push out the deployment date for this change. The earliest date is now January 2023.

Like any change, there are good and bad points to consider. Microsoft likes the change because the use of the external directory object identifier (EDOID) guarantees uniqueness for the Name and Distinguished Name properties. The EDOID is the GUID for the Azure AD object which owns a mail-enabled object in the Exchange Online Directory.

It’s worth noting that the Microsoft 365 and Exchange Online (Figure 1) admin centers do not expose the Name or Distinguished Name properties. If you want to apply the Exchange Online name change to pre-existing mailboxes, you must do this through PowerShell by running the Set-Mailbox cmdlet.

Care Needed with PowerShell Scripts

In my previous post, I gave some examples of where PowerShell developers might need to be careful about dealing with the output returned by an Exchange Online cmdlet, such as the owners of a distribution list. I ran into such a situation when looking at the script that creates the Microsoft 365 Groups and Teams membership report.

The report includes the owners of each group. The original code referenced the group owners using the ManagedBy property returned by the Get-UnifiedGroup cmdlet. This is an array list containing the Name property of each of the group owners. This was fine when EDOIDs are not involved, but when these values are present, a list of owners might look something like this:

$Group.ManagedBy

bff4cd58-1bb8-4899-94de-795f656b4a18
Sean.Landy
Ben.James

The EDOID is unique, but it’s hard for humans to understand.

The updated code loops through the array returned by Get-UnifiedGroup and then calls the Get-Recipient cmdlet to return the display name of each owner. Finally, we join the list of owners together into a value that goes into the report:

[array]$Owners = $Null
ForEach ($Owner in $Group.ManagedBy) { # Unpack the owners and retrieve a display name that's usable.
        $OwnerDisplayName = (Get-Recipient -Identity $Owner.trim()).DisplayName
        $Owners += $OwnerDisplayName }
     [string]$OwnersOutput = $Owners -join ", "

$Owners
Tony Redmond
Sean Landy
Ben James

The change doesn’t affect Microsoft Graph queries executed through PowerShell because the Graph returns full details of group owners, and you can pick what properties to use. This is a typical query to return the owners of a group (identified by the EDOID passed in $Group.Id):

$Uri = "https://graph.microsoft.com/v1.0/groups/" + $Group.Id + "/owners?"
If you use the Microsoft Graph PowerShell SDK, the solution is:
[array]$ManagedBy= Get-MgGroupOwner -GroupId $Group.ExternalDirectoryObjectId
[array]$Owners = $Null
ForEach ($Owner in $ManagedBy) {
    $OwnerDisplayName = (Get-MgUser -UserId $Owner.Id).DisplayName
    $Owners += $OwnerDisplayName }

an update to return human-friendly values. Sometimes (as when Get-Recipient lists mailboxes), Exchange Online tells you when it uses the Name property. Sometimes (as in checking the holders of the Send on behalf of permission for a mailbox), it doesn’t.

The Problem with Special Characters in Distinguished Names

Updating the Name property to use the EDOID has a knock-on effect on the DistinguishedName property. After updating the Name property, Exchange Online rewrites the DistinguishedName property with the new Name value. One advantage from this change is that you’ll no longer need to deal with distinguished names containing special characters.

For example, the surname for this guest account is O’Malley, and some of the account properties are as follows:

Get-Recipient -Identity 388d29d7-4c72-476d-be96-53060043122e | fl Name, DisplayName, DistinguishedName, Name

Name              : o'Malley.Linda_contoso.com#EXT#
DisplayName       : Linda O'Malley
DistinguishedName : CN=o'Malley.Linda_contoso.com\#EXT\#,OU=office365itpros.onmicrosoft.com,OU=Microsoft Exchange Hosted Organizations,DC=EURPR04A002,DC=prod,DC=outlook,DC=com
Name              : o'Malley.Linda_contoso.com#EXT#

You can see that Exchange derives the first part of the DistinguishedName from the Name property.

Using Distinguished Names in Scripts

It’s common to use the DistinguishedName to find the groups that an account belongs to in code like this:

[string]$DN = (Get-Recipient -Identity $User.ExternalDirectoryObjectId).DistinguishedName
[array]$Groups = (Get-Recipient -ResultSize Unlimited -RecipientTypeDetails GroupMailbox -Filter "Members -eq '$DN'"

Running the code for the Linda O’Malley account generates this error:

Cannot bind parameter 'Filter' to the target. Exception setting "Filter": "Invalid filter syntax. For a description of
the filter parameter syntax see the command help.
"Members -eq 'CN=o'Malley.Linda_contoso.com\#EXT\#,OU=Office365ITPros.onmicrosoft.com,OU=Microsoft Exchange Hosted
Organizations,DC=EURPR04A002,DC=prod,DC=outlook,DC=com'" at position 19."

One solution is to adjust the filter to handle mailboxes with special characters in distinguished names. A check for apostrophes invokes special processing to “escape” the character before performing the check.

$DN = (Get-Recipient -Identity $Guest.Id).DistinguishedName 
#    The distinguished name for some accounts might contain an apostrophe, so we need to handle this
     If ($Dn -like "*'*")  {
       $DNNew = "'" + "$($dn.Replace("'","''''"))" + "'"
       $Cmd = "Get-Recipient -Filter 'Members -eq '$DNnew'' -RecipientTypeDetails GroupMailbox | Select DisplayName, ExternalDirectoryObjectId"
       $GuestGroups = Invoke-Expression $Cmd }
     Else {
       $GuestGroups = (Get-Recipient -Filter "Members -eq '$Dn'" -RecipientTypeDetails GroupMailbox | Select DisplayName, ExternalDirectoryObjectId) }

Updating Mail User Objects

Using the EDOID for the Name property removes the need write code to accommodate accounts with special characters in their names. The downside is that Microsoft’s change only affects new mailboxes. However, there’s nothing to stop us updating the Name property for mail user objects for guest accounts to eliminate special characters. Here’s how to make the change for all mail users in a tenant:

[Array]$MailUsers = Get-MailUser -ResultSize Unlimited
ForEach ($Mu in $MailUsers) {
 Write-Host ("Updating mail user object for {0}" -f $Mu.DisplayName)
 Set-MailUser -Identity $Mu.ExternalDirectoryObjectId -Name $Mu.ExternalDirectoryObjectId }

I haven’t run into any problems with scripts after updating all the mail user objects for guest accounts in my tenant.

Pause for Thought

I’m not advocating that organizations should rush out to update the name property of every mail-enabled object. It’s better to wait and see if Microsoft updates their code to use the EDOID for the Name and DistinguishedName properties of all mail-enabled objects in Exchange Online. However, if your tenant has some mail-enabled objects with special characters in their name, you can simplify PowerShell scripts by applying a quick and simple change to those objects. And that’s a nice thing.