Microsoft Entra ID
General

Tshoot Clear On Premises Attributes

In brief

The page reorganizes attribute and role lists and improves formatting for ADSyncTools command output and PowerShell examples. It continues to specify ADSyncTools v2.5.0 as the minimum required version.

What Entra admins need to know

Administrators have clearer reference material for managing on-premises attributes; no action is required.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

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

  • onPremisesDistinguishedName

  • onPremisesDomainName

  • onPremisesImmutableId

  • onPremisesObjectIdentifier

  • onPremisesSamAccountName

  • onPremisesSecurityIdentifier

  • onPremisesUserPrincipalName

How to update these attributes

You can update these attributes via Microsoft Graph Beta with Update User API call. You can update these attributes in Microsoft Entra ID only for Cloud‑Only users. This includes users that were previously synchronized and later converted to Cloud‑Only when tenant synchronization was disabled.

Required roles

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

Required permissions

The required application permissions are User.ReadWrite.All and User-OnPremisesSyncBehavior.ReadWrite.All (the latter is required specifically for the onPremisesObjectIdentifier attribute).

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:

Install the ADSyncTools module from PowerShell Gallery:

[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 on-premises attributes:

Get-Command *onpremises* -Module ADSyncTools

Result:

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

Get all the details of a cmdlet (for example, Syntax and Examples) 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 -Scopes "User.ReadWrite.All, User-OnPremisesSyncBehavior.ReadWrite.All"

SYNTAX

By Identity

 Get-ADSyncToolsOnPremisesAttribute [-Id] <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 -Scopes "User.ReadWrite.All, User-OnPremisesSyncBehavior.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 -Scopes "User.ReadWrite.All, User-OnPremisesSyncBehavior.ReadWrite.All"

Clear-ADSyncToolsOnPremisesAttribute '[email protected]' -All

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

  • onPremisesDistinguishedName

  • onPremisesDomainName

  • onPremisesImmutableId

  • onPremisesObjectIdentifier

  • onPremisesSamAccountName

  • onPremisesSecurityIdentifier

  • onPremisesUserPrincipalName

Clear-ADSyncToolsOnPremisesAttribute

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]]
[[-onPremisesObjectIdentifier]] [[-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 -Id '12345678-90ab-cd12-3456-7890abcd1234' -onPremisesImmutableId

Example 2

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

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

Clear-ADSyncToolsOnPremisesAttribute -Id $userId -BodyParameter $jsonBody

Set-ADSyncToolsOnPremisesAttribute

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

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 following on-premises attributes:

  • onPremisesDistinguishedName

  • onPremisesDomainName

  • onPremisesImmutableId

  • onPremisesObjectIdentifier *

  • sonPremisesSamAccountName

  • onPremisesSecurityIdentifier **

  • onPremisesUserPrincipalName

    ** Must have the correct Security Identifier format, for example: "S-1-5-21-1234567890-0987654321-1234567890-1111"

SYNTAX

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

By BodyParameter

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

EXAMPLES

Example 1

Set only onPremisesImmutableId (pipelining)

'[email protected]' | Set-ADSyncToolsOnPremisesAttribute -onPremisesImmutableId 'nofCJe0gZk6D8J4gRgrt+A=='

Example 2

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

$jsonBody = @'
{
  "onPremisesDistinguishedName": "[email protected]",
  "onPremisesDomainName": 'Contoso.com',
  "onPremisesImmutableId": 'nofCJe0gZk6D8J4gRgrt+A==',
  "onPremisesSamAccountName": 'User1',
  "onPremisesSecurityIdentifier": "S-1-5-21-4097605469-3104078553-1111111111-1111",
  "onPremisesUserPrincipalName": "[email protected]"
}
'@
Set-ADSyncToolsOnPremisesAttribute -Id '11111111-2222-3333-4444-555555555555' -BodyParameter $jsonBody
Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…