A missing ImmutableID in Okta or Microsoft 365 prevents successful authentication and disrupts Microsoft 365 federation. Correct these mismatches by updating the ImmutableID in Microsoft Entra ID or configuring the Okta to App profile mapping to restore proper authentication.

• Okta Identity Engine (OIE)
• Okta Classic Engine
• Single Sign-On (SSO)
• Federation (WS-FED)
• Microsoft Office 365
• Microsoft Entra ID

A missing ImmutableID in Okta or Microsoft 365 prevents successful authentication.

How is the ImmutableID updated for on-premises Active Directory accounts?

Update the ImmutableID in Microsoft Entra ID for on-premises Active Directory (AD) accounts by converting the AD objectGUID to a Base64-encoded string and running PowerShell commands.

1. Launch PowerShell as an administrator.
2. Convert the 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 Microsoft 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. Remove the Microsoft Office 365 assignments to reimport accounts already assigned and shown under the Assignments tab before the ImmutableID population.
5. Verify that Deactivate Users is cleared for the Microsoft Office 365 app under Provisioning > To App.
6. Clear unconfirmed users under the Imports tab for Microsoft Office 365 if there are pending assignments.
7. Run the Microsoft Office 365 import to bring the existing profile assignments back into Okta after populating the ImmutableID for all required accounts in Microsoft Entra ID.
8. Select Deactivate Users if it was cleared in the previous step.

NOTE: Create the accounts in Microsoft Office 365/Microsoft Entra ID with the domain federated with Okta. Authentication fails for accounts created under other domains. Change the domain using the Microsoft Entra ID interface. Set the ImmutableID before making changes, as it serves as the SourceAnchor and is required to perform the change. After the new import and assignment confirmation, accounts with the correct domain in the username/User Principal Name (UPN) can authenticate using the federation tile in the Okta Dashboard.

How is the ImmutableID updated for Microsoft Entra ID accounts not sourced from on-premises Active Directory?

Update the ImmutableID for Microsoft Entra ID accounts not sourced from on-premises Active Directory by assigning the accounts to the Microsoft Office 365 app in Okta and running PowerShell commands.

1. Assign the accounts to the Microsoft Office 365 app in Okta to generate an AppUser ID. The ID begins with the prefix 0ua.
2. Obtain the AppUser ID for the Microsoft Office 365 app for each account using the List Application Users API, the Rockstar Chrome extension, or System Log Add User to App Membership events using the eventType eq "application.user_membership.add" search expression.
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 account.
   # Account 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 Microsoft Office 365 app that “Deactivate Users” is cleared under Provisioning > To App before proceeding.
5. Unassign all accounts assigned from step 1 (this may take a few minutes depending on how many accounts were assigned), remove the assignment of the app from the imported accounts, and import the accounts again. They will be imported with the new "ImmutableID", which will serve for SSO.

NOTE: Create the accounts in Microsoft Office 365/Microsoft Entra ID with the domain federated with Okta. Authentication fails for accounts created under other domains. Change the domain using the Microsoft Entra ID interface. Set the `ImmutableID` before making changes, as it serves as the SourceAnchor and is required to perform the change. After the new import and assignment confirmation, accounts with the correct domain in the username/User Principal Name (UPN) can authenticate using the federation tile in the Okta Dashboard.

How is the ImmutableID configured for accounts that do not exist in Microsoft Entra ID and are not sourced from on-premises Active Directory?

Configure the `ImmutableID` for accounts that do not exist in Microsoft Entra ID and are not sourced from on-premises Active Directory by setting the Okta to App profile mapping to apply on creation and using the following expression:

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

This expression first checks if an on-premises AD source is present for each account and sets the `ImmutableID` based on the AD profile External ID (ObjectGUID) only if the account has exactly one on-premises AD source. Otherwise, the mapping sets the `ImmutableID` value to the Okta App User ID. Accounts already assigned to Microsoft Office 365 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. Ensure that:

• The script accurately reflects the variables relating to the environment.
• The script commands or any subset of the provided script are fully tested against a small subset of accounts, preferably in a lower environment, before being run in production.

Related References

• Microsoft Entra Connect: Design concepts
• Handling Immutable ID Issues in Okta for Microsoft 365 Assignments
• Error During Microsoft Office 365 Single Sign-On "AADSTS51004 The user account does not exist in the directory"