ImmutableID mismatches disrupt Microsoft 365 federation authentication. This article provides the necessary steps for multiple scenarios to correct these mismatches and restore proper authentication.

• Single Sign-On (SSO)
• Federation (WS-FED)
• Microsoft Office 365
• Entra ID

Missing ImmutableID in Okta or Microsoft 365 can prevent successful authentication.

On-premises Active Directory users without ImmutableID in Entra ID

1. Launch PowerShell as an administrator.
2. Convert the user's Active Directory (AD) objectGUID binary value to a Base64-encoded string for use as the ImmutableID by running the following commands:
   

   # Import the Active Directory module
   Import-Module ActiveDirectory
   
   # Set the User Principal Name (UPN) of the user
   $userUPN = "user@example.com" # Replace with the actual UPN
   
   # Retrieve the user object from Active Directory
   $adUser = Get-ADUser -Filter "UserPrincipalName -eq '$userUPN'"
   
   # Get the objectGUID of the user
   $guid = $adUser.objectGUID
   
   # Convert the GUID to a Base64-encoded string
   $immutableId = [System.Convert]::ToBase64String($guid.ToByteArray())

3. Run the following command to update the ImmutableID in Entra ID:
   

   # 1. Connect to Microsoft Graph
   Install-Module Microsoft.Graph -Scope CurrentUser -Force
   Connect-MgGraph -Scopes Directory.AccessAsUser.All
   
   # 2. Get the Entra ID User Object
   $azureADUser = Get-MgUser -Filter "UserPrincipalName eq '$userUPN'"
   
   # 3. Unfederate the user. 
   # User must be unfederated before the Immutable ID can be updated.
   # Assumes cloud.example.com is a non-federated domain in your tenant.
   $newUPN = $userUPN.Replace("example.com", "cloud.example.com")
   
   Update-MgUser -UserId $azureADUser.Id -UserPrincipalName $newUPN
   
   # 4. Re-fetch the Entra ID user after unfederation
   $azureADUser = Get-MgUser -Filter "UserPrincipalName eq '$newUPN'"
   
   # 5. Update OnPremisesImmutableId
   Update-MgUser -UserId $azureADUser.Id -OnPremisesImmutableId $immutableId
   
   # 6. Re-establish federation
   #  Change UPN back to original domain.
   Update-MgUser -UserId $azureADUser.Id -UserPrincipalName $userUPN

4. If the users were already assigned and shown under the Assignments tab before the ImmutableID population, the O365 assignments need to be removed in order to be reimported. Before proceeding, verify that "Deactivate Users" is unchecked for the O365 app under Provisioning > To App. If there are pending assignments under the Imports tab for O365, Clear Unconfirmed Users.
5. After the ImmutableID is populated for all required accounts in Entra, run the O365 import to bring the existing users' profile assignments back into Okta. Reenable "Deactivate Users" if unchecked in the previous step.

NOTE: Ensure that the users are created in O365/Entra ID with the domain federated with Okta (for example, users created under other domains, then the federated one will not be able to log in). Change the domain for a user using the Entra ID interface. There will be a need for the ImmutableID to be set before changes can be made (it serves as SourceAnchor as well, and it is required to perform the change).

After the new import and assignment confirmation, if the users have the correct domain in their username/UPN, the users will be able to log in using the federation tile in their Okta Dashboard.

Entra ID users without an ImmutableID who are not sourced from on-premises Active Directory

1. Assign the users to the Microsoft Office 365 app in Okta to have an AppUser ID generated for the user. It will begin with the prefix 0ua.
2. Obtain this AppUser ID for the O365 app for each user, which can be accomplished in a number of ways, including List Application Users API, the community Rockstar Chrome extension, or System Log Add User to App Membership events (Okta System Log search expression: eventType eq "application.user_membership.add").
3. Run the following command to update the ImmutableID with the obtained AppUser ID for each account:
   

   $userUPN = "user@example.com"      # Replace with the user's UPN
   $externalImmutableId = "YOUR_OKTA_APPUSER_ID" # Replace with appuser ID for the user with 0ua prefix.
   
   # 1. Connect to Microsoft Graph
   Install-Module Microsoft.Graph -Scope CurrentUser -Force
   Connect-MgGraph -Scopes Directory.AccessAsUser.All
   
   # 2. Get the Entra ID User Object
   $azureADUser = Get-MgUser -Filter "UserPrincipalName eq '$userUPN'"
   
   # 3. Unfederate the user.
   # User must be unfederated before the Immutable ID can be updated.
   # Assumes cloud.example.com is a non-federated domain in your tenant.
   $newUPN = $userUPN.Replace("example.com", "cloud.example.com")
   
   Update-MgUser -UserId $azureADUser.Id -UserPrincipalName $newUPN
   
   # 4. Re-fetch the Entra ID user after unfederation
   $azureADUser = Get-MgUser -Filter "UserPrincipalName eq '$newUPN'"
   
   # 5. Update OnPremisesImmutableId with the Okta value.
   Update-MgUser -UserId $azureADUser.Id -OnPremisesImmutableId $externalImmutableId
   
   # 6. Re-establish federation
   # Change UPN back to original domain.
   Update-MgUser -UserId $azureADUser.Id -UserPrincipalName $userUPN

4. After the ImmutableID is populated, verify in the Okta O365 app that "Deactivate Users" is unchecked under Provisioning > To App before proceeding.
5. Unassign all users assigned from step 1 (this may take a few minutes depending on how many users were assigned), remove the assignment of the app from the users imported, and import the users again. They will be imported with the new ImmutableID which will serve for SSO.

NOTE: Ensure that the users are created in O365/Entra ID with the domain federated with Okta (for example, users created under other domains, then the federated one will not be able to log in). Change the domain for a user using the Entra ID interface. There will be a need for the ImmutableID to be set before changes can be made (it serves as SourceAnchor as well, and it is required to perform the change).

After the new import and assignment confirmation, if the users have the correct domain in their username/UPN, the users will be able to log in using the federation tile in their Okta Dashboard.

Users who do not yet exist in Entra ID and are not sourced from on-premises Active Directory 

If some or all of the Okta users to be assigned to the O365 app do not have an on-prem AD source and are not yet pushed to O365/Entra ID, set the Okta to App profile mapping for ImmutableID to Apply mapping on user create only and use the following expression for the attribute:

hasDirectoryUser()?findDirectoryUser().externalId:user.getInternalProperty("id")

See Handling Immutable ID Issues in Okta for Microsoft 365 Assignments.

This expression first checks if an on-prem AD source is present for each User and sets the ImmutableID based on the AD profile External ID (ObjectGUID) only if the user has exactly one on-prem AD source. Otherwise, the mapping sets the ImmutableID value to the Okta App User ID. Users already assigned to O365 will not have the ImmutableID update as long as the mapping is configured to apply on Create Only.

The scripts provided above are examples of the PowerShell commands and the order in which they should be run. It is up to customers to ensure that:

Related References

• Microsoft Entra Connect: Design concepts
• Error During Microsoft Office 365 Single Sign-On "AADSTS51004 The user account does not exist in the directory"