Soft-matching mechanism for dirsync and ‘mail’ attribute

Well, apparently you can (now?) use the ‘mail’ attribute to do a soft-match between an on-prem user object and a cloud one. Am I the only one that never knew this? ūüôā

I cannot actually recall testing this in the past, but all the documentation we have about the soft-match functionality talks about the Primary STMP address. That is, until you look into step 3 of the “How to use SMTP matching to match on-premises user accounts to Office 365 user accounts for directory synchronization” article. Here’s the relevant part:

Set the primary SMTP address of the new user account to match the primary SMTP address that you noted in step 1D.

To do this by using Exchange Management tools, go to the following Microsoft websites:

If Exchange isn’t installed on-premises, you can manage the SMTP address value by using Active Directory Users and Computers:

  1. Right-click the user object, and then click Properties.
  2. On the general tab, update the E-mail field, and then click OK.

Note how it says ‘the E-mail field’, the one that corresponds to the ‘mail’ attribute? Well I have never noticed this before ūüôā The important part is, this actually works. Here are the steps I used to verify it. First, I took an already existing object in my test O365 tenant and made sure it has no ImmutableID (i.e. can be soft-matched), but does have a proxy address (another requirement in order to be able to soft-match it):

PS C:\> Get-MsolUser -UserPrincipalName nov@michevb.onmicrosoft.com | ft Userp*,Imm*,Proxy*

UserPrincipalName                                           ImmutableId                                                 ProxyAddresses
-----------------                                           -----------                                                 --------------
nov@michevb.onmicrosoft.com                                                                                             {SMTP:nov@michevb.onmicrosoft.com}

Next step was to create a new account in my test AD, pick a random name for it, make sure no proxyaddresses are configured and that the mail attribute matches the value above:

PS C:\> Get-ADUser novnov -Properties mail,ProxyAddresses,WhenCreated | select mail,*Name,WhenCreated,ProxyAddresses

mail              : nov@michevb.onmicrosoft.com
DistinguishedName : CN=novnov,CN=Users,DC=michev,DC=info
GivenName         : novnov
Name              : novnov
SamAccountName    : novnov
Surname           :
UserPrincipalName : novnov@michev.info
WhenCreated       : 4/30/2015 5:45:53 AM
ProxyAddresses    : {}

In other words, I only populated the E-Mail field for that account:


The next steps was to force Dirsync, and a minute later the result was:

PS C:\> Get-MsolUser -UserPrincipalName nov@michevb.onmicrosoft.com| ft Userp*,Imm*,Proxy*,DisplayName

UserPrincipalName                            ImmutableId                                  ProxyAddresses                               DisplayName
-----------------                            -----------                                  --------------                               -----------
nov@michevb.onmicrosoft.com                  nTMIIWta60W84k07TMw//g==                     {SMTP:nov@michevb.onmicrosoft.com}           novnov

The ImmutableID above is of course a match of the GUID of the on-prem object. So yes, soft-matching based on the ‘mail’ attribute does work. It does NOT take precedence over Primary SMTP address however – if you have a Primary STMP address configured for the on-prem object and it does not match the primary SMTP in the cloud, soft-match will never even look at the ‘mail’ attribute and will fail. In result, a new object will be provisioned instead. For example, take this object I created in the cloud:

PS C:\> Get-MsolUser -UserPrincipalName huku@michevb.onmicrosoft.com| fl Userp*,Imm*,Proxy*

UserPrincipalName : huku@michevb.onmicrosoft.com
ImmutableId       :
ProxyAddresses    : {SMTP:huku@michevb.onmicrosoft.com}

The corresponding object I created on-prem had the following attributes:

PS C:\> Get-ADUser huku -Properties mail,ProxyAddresses,WhenCreated | select mail,*Name,WhenCreated,ProxyAddresses

mail              : huku@michevb.onmicrosoft.com
DistinguishedName : CN=huku,CN=Users,DC=michev,DC=info
GivenName         : huku
Name              : huku
SamAccountName    : huku
Surname           :
UserPrincipalName : huku@michev.info
WhenCreated       : 4/30/2015 7:32:33 AM
ProxyAddresses    : {SMTP:huku5555@michevb.onmicrosoft.com}

So, we had matching ‘mail’¬†attributes, but as the primary SMTP addresses didn’t match, nothing interesting happened. Instead, the dirsync service checked that the objectGUIDs didn’t match, moved to checking the Primary SMTP and since¬†they didn’t match as well, went on creating a new object in the cloud. As a matching UPN was already in place however, it had to use a different value for the new object:

PS C:\> Get-MsolUser -UserPrincipalName huku5555@michevb.onmicrosoft.com | fl Userp*,Imm*,Proxy*

UserPrincipalName : huku5555@michevb.onmicrosoft.com
ImmutableId       : F+2QcOy0Ck2KgnthUn6i0Q==
ProxyAddresses    : {SMTP:huku5555@michevb.onmicrosoft.com}

To recap – you can now use the ‘mail’ address as means to match on-prem and cloud accounts, at least in some cases. Come to think of it, it makes sense – back in the BPOS days the provisioning process worked a bit differently and when creating the cloud object, the ‘mail’ attribute was of importance when determining the UPN value (you can read more about it here). On the other hand however, it might get you in trouble, as this additional soft-match option might trigger unexpectedly if an on-prem object has ‘mail’ configured but is missing any proxyaddresses.

This entry was posted in Office 365, PowerShell. Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *