Clear on-premises attributes from migrated Microsoft Entra ID users

After you've migrated your users and groups to Microsoft Entra ID, you may be ready to decommission your on-premises Active Directory and uninstall sync tools. After turning off directory synchronization, you can manage these objects directly in Microsoft Entra ID.

However, you may encounter issues in Windows, Intune, and Outlook due to legacy values remaining in the user attributes that were previously synchronized from on-premises. For example, hybrid device joining may fail because the system pulls the username and domain from these outdated attributes.

To prevent these issues, we recommend that customers clear the following on-premises attributes:

• onPremisesDistinguishedName
• onPremisesDomainName
• onPremisesImmutableId
• onPremisesSamAccountName
• onPremisesSecurityIdentifier
• onPremisesUserPrincipalName

How to update these attributes

You can update these attributes via Microsoft Graph Beta with Update User API call. These attributes can only be updated in Entra ID for native Cloud-Only users or for previously synced users that have been converted to Cloud-Only users after turning off synchronization in Entra ID.

Required roles

The Entra ID roles that can update on-premises attributes are:

• User Administrator
• Hybrid Identity Administrator

Required permissions

The required application permission is User.ReadWrite.All.

Using ADSyncTools PowerShell module

You can also view and update these on-premises attributes with the PowerShell scripts provided.

Prerequisites for managing on-premises attributes with ADSyncTools PowerShell module:

• Windows PowerShell 7
• Microsoft Graph SDK PowerShell module

In order to use ADSyncTools you need to install the module from PowerShell Gallery, as follows:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 
Install-Module ADSyncTools # If ADSyncTools isn’t installed, or; 
Update-Module ADSyncTools # If ADSyncTools is already installed 

Use the following commands to get started with ADSyncTools.

Import-Module ADSyncTools 

See the cmdlets available for managing OnPremises attributes:

Get-Command *onpremises* -Module ADSyncTools 

Result:

CommandType   Name                      Version  Source 
-----------   ----                      -------  ------ 
Function    Clear-ADSyncToolsOnPremisesAttribute      1.5.2   ADSyncTools 
Function    Get-ADSyncToolsOnPremisesAttribute       1.5.2   ADSyncTools 
Function    Set-ADSyncToolsOnPremisesAttribute       1.5.2   ADSyncTools 

Get all the details of a cmdlet (i.e., Syntax, Examples, etc.) with Get-Help <cmdlet> -Full:

Get-Help Get-ADSyncToolsOnPremisesAttribute -Full

Get-ADSyncToolsOnPremisesAttribute

Description

Gets a specific user or all users containing on-premises properties in Entra ID. It only returns the users that have on-premises attributes populated. By Default, it returns all cloud-only users, but you can specify -IncludeSyncedUsers to return all users, including users synced from on-premises AD.

This operation requires Microsoft Graph PowerShell SDK, preauthenticated with Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "User.Read.All"

SYNTAX

By Identity

 Get-ADSyncToolsOnPremisesAttribute [-Identity] <String> [[-Property] <String[]>] [<CommonParameters>] 

By IncludeSyncedUsers

Get-ADSyncToolsOnPremisesAttribute [[-IncludeSyncedUsers]] [[-Property] <String[]>] [<CommonParameters>] 

EXAMPLES

Example 1

Get the on-premises attributes of all cloud-users that have on-premises attributes populated.

Get-ADSyncToolsOnPremisesAttribute 

Clearing all on-premises attributes for all users

To clear all on-premises attributes from all users in a bulk fashion, use the get function to retrieve a list of all cloud-only users containing on-premises attributes and then pipeline the results to the Clear cmdlet adding the parameter -All.

This operation requires Microsoft Graph PowerShell SDK, preauthenticated with Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "User.ReadWrite.All"

You can back up all the current values with the following command:

Get-ADSyncToolsOnPremisesAttribute | Export-Csv backupOnpremisesAttributes.csv -Delimiter ';' 

To clear all on-premises attributes from all users, run:

Get-ADSyncToolsOnPremisesAttribute | Select-Object id | Clear-ADSyncToolsOnPremisesAttribute -All -Verbose 

Clearing all on-premises attributes for one user

To clear all on-premises attributes for one particular user, specify the objectId or UserPrincipalName followed by the parameter -All.

This operation requires Microsoft Graph PowerShell SDK, preauthenticated with Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "User.ReadWrite.All"

Clear-ADSyncToolsOnPremisesAttribute 'User1@Contoso.com' -All 

You can also use Clear-ADSyncToolsOnPremisesAttribute to clear any of the following on-premises attributes individually:

• onPremisesDistinguishedName
• onPremisesDomainName
• onPremisesImmutableId
• onPremisesSamAccountName
• onPremisesSecurityIdentifier
• onPremisesUserPrincipalName

Clear-ADSyncToolsOnPremisesAttribute

Description

Clears the on-premises properties of a specific Cloud-Only user or all CLoud-Only users in Entra ID.

SYNTAX

 Clear-ADSyncToolsOnPremisesAttribute [-Id] <String> [[-onPremisesDistinguishedName]] [[-onPremisesDomainName]] [[-onPremisesImmutableId]] [[-onPremisesSamAccountName]] [[-onPremisesSecurityIdentifier]] [[-onPremisesUserPrincipalName]] [<CommonParameters>] 

by BodyParameter

 Clear-ADSyncToolsOnPremisesAttribute [-Id] <String> [-BodyParameter] <String> [<CommonParameters>] 

by All

 Clear-ADSyncToolsOnPremisesAttribute [-Id] <String> [-All] [<CommonParameters>] 

Example 1

Clear only onPremisesImmutableId attribute

 Clear-ADSyncToolsOnPremisesAttribute -Identity '12345678-90ab-cd12-3456-7890abcd1234' -onPremisesImmutableId

Example 2

Clear onpremises attributes based on a json parameter body (-BodyParameter)

$jsonBody = @'
{ 
  "onPremisesDistinguishedName": null, 
  "onPremisesDomainName": null, 
  "onPremisesImmutableId": null, 
  "onPremisesSamAccountName": null, 
  "onPremisesSecurityIdentifier": null, 
  "onPremisesUserPrincipalName": null 
} 
'@ 

Clear-ADSyncToolsOnPremisesAttribute -Identity $userId -BodyParameter $jsonBody

Set-ADSyncToolsOnPremisesAttribute

Sets on-premises attributes for a Cloud-Only user in Entra ID.

This operation requires Microsoft Graph PowerShell SDK, preauthenticated with Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "User.ReadWrite.All"

You can back up all the current values with the following command:

Get-ADSyncToolsOnPremisesAttribute | Export-Csv backupOnpremisesAttributes.csv -Delimiter ';' 

This function can be used to set any of the on-premises attributes listed below:

• onPremisesDistinguishedName
• onPremisesDomainName
• onPremisesImmutableId
• sonPremisesSamAccountName
• onPremisesSecurityIdentifier *
• onPremisesUserPrincipalName

• Must have the correct Security Identifier format, e.g.: "S-1-5-21-1234567890-0987654321-1234567890-1111"

SYNTAX

Set-ADSyncToolsOnPremisesAttribute [-Identity] <String> [[-onPremisesDistinguishedName] <String>] [[-onPremisesDomainName] <String>] [[-onPremisesImmutableId] <String>] [[-onPremisesSamAccountName] <String>] [[-onPremisesSecurityIdentifier] <String>] [[-onPremisesUserPrincipalName] <String>] [<CommonParameters>] 

by BodyParameter

Set-ADSyncToolsOnPremisesAttribute [-Identity] <String> [-BodyParameter] <String> [<CommonParameters>] 

EXAMPLES

Example 1

Set only onPremisesImmutableId (pipelining)

'User1@Contoso.com' | Set-ADSyncToolsOnPremisesAttribute -onPremisesImmutableId 'nofCJe0gZk6D8J4gRgrt+A==' 

Example 2

Set onpremises attributes based on a json parameter body (-BodyParameter)

$jsonBody = @' 
{ 
  "onPremisesDistinguishedName": "User1@Contoso.com", 
  "onPremisesDomainName": 'Contoso.com', 
  "onPremisesImmutableId": 'nofCJe0gZk6D8J4gRgrt+A==', 
  "onPremisesSamAccountName": 'User1', 
  "onPremisesSecurityIdentifier": "S-1-5-21-4097605469-3104078553-1111111111-1111", 
  "onPremisesUserPrincipalName": "User1@Contoso.com" 
}
'@
Set-ADSyncToolsOnPremisesAttribute -Identity '98765432-6f08-40b2-8b66-123456789012' -BodyParameter $jsonBody