Understand and Modify Office 365 users ImmutableID

Understand Office 365 ImmutableID

ImmutableID is a specific attribute for an Office 365 object that is synchronized from on prem Active Directory. When we install AAD Sync with the default settings on “Uniquely Identifying your users”, the Active Directory “objectGUID” is used as ImmutableID. It’s important to consider and understand the importance of ImmutableID when we are planning for office 365 directory integration that involves multiple active directory forest company merger etc.

Modify Office 365 users ImmutableID

Poor planning of ImmutableID can cause significant issues with your deployment and service interruption. AAD Sync Metaverse stored the value of ImmutableID as “SourceAnchor”

It’s important to understand that ImmutableID of Office 365 synced object is not the same as of ObjectGUID. Office 365 uses a special method to convert on prem user ObjectGUID to another string and save the string as ImmutableID. However, ImmutableID is also unique in Office 365 and can be mapped with the corresponding unique ObjectGUID in the local AD.

Modify Office 365 users ImmutableID?

You cannot change the ImmutableID of synchronized object without having a maintenance window or downtime. Modifying the ImmutableID of office 365 object will cause significant impact on your services and requires proper planning. The only way you can modify the ImmutableID is by turning off Directory Synchronization, allowing the users to be converted from Synced AD Object to cloud identities, performing the modification, and then re-enabling directory synchronization.

Microsoft authentication platform for federated user doesn’t support special character “@”in ImmutableID which means you can’t use mail or UPN as ImmutableID in AADSync when using AD FS SSO.

Steps to manually change the ImmutableID for few users are:

  • Create a new OU in local AD and move the user temporarily.
  • Go to MIIS Console –> On Prem AD Connector –> Containers –> filter out this temporarily OU to soft delete synced users.
  • Run the full Sync.
  • Temporarily pause the Sync from Windows Task Scheduler.
  • Go to Office 365 Portal and restore soft deleted users, so the old synced status changes to in cloud status. You can only change the ImmutableID once the user status in Office 365 is “In Cloud”
  • Change the UPN of each user with “Set-MsolUserPrincipalName -UserPrincipalName user@domain.com -NewUserPrincipalName user@tenantname.onmicrosoft.com“.

2

  • After changing the UPN for the user, run the Cmdlet Set-Msoluser -UserPrincipalName user@tenantname.onmicrosoft.com -ImmutableID ObjectGUIDBase64
  • After changing the ImmutableID, change back user’s UPN with “Set-MsolUserPrincipalName -UserPrincipalName user@tenantname.onmicrosoft.com -NewUserPrincipalName user@domain.com“.
  • Test the authentication process.
  • Setup sync mechanism to use ObjectGUID as Source Anchor and perform Full Sync.

If we’ve to change the ImmutableID of all the users then the above mentioned steps will cause a lot of delay and a single typing mistake can cause significant issue with the user account. We’ve created a PowerShell script that requires a CSV file as input which contains the UPN of all the users and this script will change the UPN of all the users to @tenantname.onmicrosoft.com and change the ImmutableID to ObjectGUID. Once the ImmutableID is changed to ObjectGUID, it will change the user UPN back to @domain.com.

#Import Active Directory Module in PowerShell

Import-Module ActiveDirectory
Import-Csv “D:O365.csv” | ForEach-Object {
$upn = $_.”UPN”
$user = $upn.IndexOf(“@”)
$left = $upn.Substring(0,$user)
$upn1 = “$left” + “@tenantname.onmicrosoft.com”
Restore-MsolUser -UserPrincipalName $upn
Set-MsolUserPrincipalName -UserPrincipalName $upn -NewUserPrincipalName $upn1
Set-Msoluser -UserPrincipalName $upn1 -ImmutableID “$Null”
$id=(Get-ADUser -Filter {UserPrincipalName -like $upn } -Properties ObjectGUID | select ObjectGUID | foreach {[system.convert]::ToBase64String(([GUID]($_.ObjectGUID)).tobytearray())})
Set-MSOLUser –UserPrincipalName $upn1 –ImmutableID $id
Set-MsolUserPrincipalName -UserPrincipalName $upn1 -NewUserPrincipalName $upn
}

You can also download this script from Microsoft TechNet Gallery. More information on ImmutableID can be found on following URLs.

17 comments

  • Joe Heikenfeld

    These are great write-ups Riaz….. Joe

  • Hi Riaz, I’m hoping you can help.

    In my environment it is a simple small on-premise AD being synced to Office365 after a cutover migration. It appears many accounts did not link properly so I am trying to manually update the Immutable ID, but receive this error through powershell: “A parameter cannot be found that matches parameter name ‘ImmutableID’ ”

    It appears the system seems to believe this parameter does not exist for users. Hopefully you can let me know what you think.

    Thanks!

  • Riaz

    Thanks for the post. we have a multi-domain/forest environment so would like to use the employeeID as the immutable ID instead of the ObjectGUID. Do I need to reinstall the AAD tool on my dirSync server to make this happen ? is there a way to change the SourceAnchor field once the tool is installed.. sorry new to this product so might be a stupid question.

  • Hello,

    We are trying to migrate 900+ users from few sub domain to one of the sub domain in the same forest. We are using Dell quest MMAD tool which create new object in target domain and due to that ObjectGUID changed and mailbox which is in O365 get disconnected
    Is it possible to connect soft deleted mailbox to target domain account?
    We have DirSync and aDFS in place

  • Hello.

    I am planning to migrate 900 subdomain users to another subdomain users in the same forest

    when we migrate users from one subdomain to another subdomain ObjectGUID get changed and O365 mailbox get disconnected. Do you know how we can connect mailbox to target domain account instead of source Domain account or any other way?

    Regards,
    Swapnil

  • Hi,

    Thanks for this great article!

    Why does the UserPrincipalName need to be changed and changed back? After the recovery to In-Cloud can’t you just change the ImmutableID?

    Thanks,
    Kevin

  • Shalini Prasad

    Will the users created in cloud have a Immutable ID or the Source Anchor in cloud?

  • We want to break the sync of scope for one subset of users and change them from syned with ad to cloud only. I have excluded their particular OU, reinstated after soft delet, but upon subsequent syncs users are deleted again because they are no longer in the sync of scope. I found removing the immutableid prevents them from being deleted upon subsequent syncs. Are there implications down the line for cloud users that have a blank immutableid?

  • Hi Riaz,
    I need to change the SourceAnchor from objectGUID to employeeID to more than 5000 users. I’m planning to turn off Directory Synchronization and change all values with PowerShell. The users on O365 are using only SharePoint Online, will there be any loss of data/access to resources?
    Con you confirm me that downtime will be up to 72h (time for the synch to “release” the objects on cloud, depending on the number of objects)? Thanks!!

    • Hi Elisa,

      Yes you can do that and it will not impact user access to SP resource. The downtime will be up to 72 Hrs or depends for how long you disable your synchronization.