Office 365 – migrating accounts with special characters in UPN and email addresses

Exchange logo

This is a workaround in order to identify and migrate mailboxes to Office 365 which have special characters in UPNs and email addresses. There is a PowerShell script at the end of this post which you can use to identify problem accounts before migration.

You may run into an issue migrating mailboxes from on premise Exchange to Office 365, where some accounts fail due to illegal characters in email addresses or UPNs. These are not detected by idfix. Having spoken to Microsoft about this, the official line is that no special characters are supported, therefore you should remove them if at all possible. However, we found during a large migration that in some cases they can be retained.

Note that the Microsoft article linked below does not mention UPNs, however we found that special characters in UPNs will cause users and shared mailbox migrations to fail.

The result of our testing was as follows:

  • Distribution Lists don’t require any changes and will still work
  • User accounts and shared mailboxes need any illegal characters removing from UPN, mail and primary SMTP address in proxyaddresses attribute, but these can be added back in as SMTP aliases, and should then be retained once the account is migrated.

Note: I would suggest that special characters are simply removed, rather than replaced with anything else. There are different types of characters, so removing them works for anything. It is not required to change the Display Name in the GAL, only the email address and whilst that is what people will see if they reply to an email, and they will still receive emails on the old address. This will be very difficult to manage if we have different rules for different areas of the business, different characters etc.

You can follow the process below to make changes to affected accounts in your on premise Active Directory before they can be migrated. To be clear, the process is as follows (for users and shared mailboxes):

  1. Remove any special characters from UPN, mail, and primary SMTP address
  2. Add back the primary SMTP address as an alias (if still required)
  3. All other aliases and attributes can remain as-is, including display name.

Example

Display name: R&D Team Mailbox – leave as-is

UPN: Change R&DTeamMailbox to RDTeamMailbox

Change Primary SMTP: From R&DTeamMailbox.com to RDTeamMailbox@domain.com

Add back the old primary address as an alias: R&DTeamMailbox@domain.com

Note that the full list of special characters is as below, from https://support.microsoft.com/en-us/help/2001616/a-user-s-office-365-email-address-unexpectedly-contains-an-underscore

Note that there is a typo in the Microsoft list, black slash is listed as pipe, so it may be best to remove both.

space character
` apostrophe
( opening parenthesis
) closing parenthesis
single quotation mark
& ampersand
\ pipe
= equal sign
? question mark
/ forward slash
% percent

Identify accounts with illegal characters

Here is a PowerShell script you can use to identify any problem accounts.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
# list of illegal characters for regex match
$pattern = "[``''&()&\=?/% ]"

#AD locations to search
$ou = "DC=cloudrun,DC=co,DC=uk"
$dc = "cloudrun.co.uk"

if (Get-Module -ListAvailable -Name ActiveDirectory) {}
else {
Write-error " ActiveDirectory module does not exist, exiting"
exit
}
#Get all users with an email address
$users = Get-ADUser -Filter {EmailAddress -like "*@*"} -Properties mail -searchbase $ou
write-host "Total number of users with email address:" $users.length
#Create a hash table to store the results
$hits= $null #empty the hash table
$hits = @()

foreach ($user in $users)
{
$username = $user.Name
$dn = $user.DistinguishedName
$mail = $user.mail
if ($user.mail -match $pattern)
{
$char = '{0}' -f $matches[0]
$hits += [pscustomobject]@{
mail = $mail
Character = $char
Username = $username
dn = $dn
}
}
}

write-host "Total number of hits:" $hits.length

$hits
#$hits | export-csv c:\temp\illegal_chars.csv #Export to CSV
Posted in Exchange Online, Office 365

Related Posts

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: