通过

从已迁移的 Microsoft Entra ID 用户清理本地属性

  • 项目

将用户和组迁移到 Microsoft Entra ID 后，可以停用本地 Active Directory 和卸载同步工具。 关闭目录同步后，可以直接在 Microsoft Entra ID 中管理这些对象。

但是，你可能会在 Windows、Intune 和 Outlook 中遇到问题，因为以前从本地同步的用户属性中保留了旧值。 例如，混合设备加入可能会失败，因为系统从这些过时的属性中提取用户名和域名。

为了防止这些问题，我们建议客户清除以下本地属性：

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

如何更新这些属性

可以使用更新用户 API 调用通过 Microsoft Graph Beta 更新这些属性。 对于本地仅限云的用户或在 Entra ID 中关闭同步后已转换为仅限云的用户的先前同步用户，这些属性只能在 Entra ID 中更新。

必需的角色

可更新本地属性的 Entra ID 角色包括：

所需的权限

所需的应用程序权限为 User.ReadWrite.All。

使用 ADSyncTools PowerShell 模块

还可以使用提供的 PowerShell 脚本查看和更新这些本地属性。

使用 ADSyncTools PowerShell 模块管理本地属性的先决条件：

若要使用 ADSyncTools，需要从 PowerShell 库安装模块，如下所示：

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

注意

在 Entra ID 中管理本地属性的最低所需版本为 v1.5.2。

使用以下命令开始使用 ADSyncTools。

Import-Module ADSyncTools

请参阅可用于管理 OnPremises 属性的 cmdlet：

Get-Command *onpremises* -Module ADSyncTools

结果：

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-Help <cmdlet> -Full 获取 cmdlet（即语法、示例等）的所有详细信息：

Get-Help Get-ADSyncToolsOnPremisesAttribute -Full

Get-ADSyncToolsOnPremisesAttribute

说明

获取特定用户或在 Entra ID 中包含本地属性的所有用户。 它仅返回填充了本地属性的用户。 默认情况下，它返回所有仅限云的用户，但你可以指定 -IncludeSyncedUsers 以返回所有用户，包括从本地 AD 同步的用户。

此操作需要 Microsoft Graph PowerShell SDK（使用 Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "User.Read.All" 进行预先身份验证）

SYNTAX

按标识

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

按 IncludeSyncedUsers

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

示例

示例 1

获取填充了本地属性的所有云用户的本地属性。

Get-ADSyncToolsOnPremisesAttribute

清除所有用户的所有本地属性

若要批量清除所有用户的所有本地属性，请使用 get 函数检索包含本地属性的所有仅限云的用户的列表，然后将结果传送到“清除”cmdlet，以添加参数 -All。

此操作需要 Microsoft Graph PowerShell SDK（使用 Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "User.ReadWrite.All" 进行预先身份验证）

重要

在清除生产环境中 Entra ID 用户的本地属性之前，作为安全建议，备份所有用户的本地属性，以防需要回滚操作。

可以使用以下命令备份所有当前值：

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

若要清除所有用户的所有本地属性，请运行：

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

清除一个用户的所有本地属性

若要清除一个特定用户的所有本地属性，请指定 objectId 或 UserPrincipalName，然后指定参数 -All。

此操作需要 Microsoft Graph PowerShell SDK（使用 Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "User.ReadWrite.All" 进行预先身份验证）

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

还可以使用 Clear-ADSyncToolsOnPremisesAttribute 单独清除以下任何本地属性：

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

Clear-ADSyncToolsOnPremisesAttribute

说明

清除 Entra ID 中特定仅限云的用户或所有仅限云的用户的本地属性。

SYNTAX

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

按 BodyParameter

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

按 All

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

示例 1

仅清除 onPremisesImmutableId 属性

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

示例 2

基于 json 参数正文清除 onpremises 属性 (-BodyParameter)

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

Clear-ADSyncToolsOnPremisesAttribute -Identity $userId -BodyParameter $jsonBody

Set-ADSyncToolsOnPremisesAttribute

在 Entra ID 中为仅限云的用户设置本地属性。

此操作需要 Microsoft Graph PowerShell SDK（使用 Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "User.ReadWrite.All" 进行预先身份验证）

重要

在更新生产环境中 Entra ID 用户的本地属性之前，作为安全建议，备份所有用户的本地属性，以防需要回滚操作。

可以使用以下命令备份所有当前值：

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

此函数可用于设置下面列出的任何本地属性：

  • onPremisesDistinguishedName
  • onPremisesDomainName
  • onPremisesImmutableId
  • sonPremisesSamAccountName
  • onPremisesSecurityIdentifier *
  • onPremisesUserPrincipalName
  • 必须具有正确的安全标识符格式，例如：“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>]

按 BodyParameter

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

示例

示例 1

仅设置 onPremisesImmutableId（管道传送）

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

示例 2

基于 json 参数正文设置 onpremises 属性 (-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

注意

可以结合使用 -Verbose 与任何命令来显示函数正在执行的操作的其他详细信息。