PowerShell AD Module Cmdlets Cannot Clear, Add, Remove or Replace Back Linked Attributes

  • Article

Several of the PowerShell Active Directory module cmdlets accept the -Clear, -Add, -Remove, and -Replace parameters. However, these parameters raise an error if you attempt to use them to modify a back linked attribute. For example, you cannot use Set-ADUser to clear the memberOf attribute of a user.

Introduction

If you need to remove all of the group memberships of a user, it would be convenient to use the -Clear parameter of Set-ADUser to clear the memberOf attribute. However, this raises an error. The reason is that the memberOf attribute is a back linked attribute. The same problem affects the -Add, -Remove, and -Replace parameters. They cannot be used to modify back linked attributes.

↑ Return to Top

Linked Attributes

Linked attributes in Active Directory are pairs of related distinguished name attributes. One is called the forward linked attribute, the other the back linked attribute. The forward link is an attribute you can update. The back link is a related attribute that is automatically updated by the system when you update the forward link. For example, the member attribute of groups is a forward link. When you add a user to a group, the distinguished name of the user is added to the member attribute of the group. The system automatically updates the memberOf attribute of the corresponding user.

When the Active Directory Users and Computers mmc is used to add a group membership to a user on the "Member Of" tab, the system actually first updates the member attribute of the corresponding group. Then the link table is updated so the membership is reflected in the memberOf attribute of the user. The same also happens if a script is used to add a group membership.

Only the forward linked attribute is actually saved in the Active Directory database. A link table is used to refer to the value of the back linked attribute. For example, the member attribute of a group is an array of member distinguished names saved with the group object in AD. But the memberOf attribute of a user simply uses the link table to refer to the distinguished names of the groups.

↑ Return to Top

Examples

In the image below, Get-ADUser is used to retrieve the memberOf attribute of a user. Then attempt is made to remove all group memberships with the -Clear parameter of Set-ADUser.

 

The error indicates that the attribute is owned by the Security Accounts Manager. This doesn't really explain the problem. It is not well documented, but a similar error is raised whenever there is an attempt to modify any back linked attribute. The best explanation is that the AD module cmdlets cannot modify the attributes because they are not actually saved in the Active Directory database. Rather, the attributes reference a link table.

In the image below the -Remove, -Add, and -Replace parameters of Set-ADUser are used to modify the memberOf attribute of a user. The same error is raised in each case.

 

The same applies to all linked attributes in Active Directory. For example, the manager and directReports attributes are linked, with directReports the back link. In the image below the directReports of a user are retrieved, then the -Clear parameter attempt to clear the directReports. The same error is raised.

 

To demonstrate that these parameters can be used to modify the forward linked attribute, the below image shows the results when modifications are made the manager or member attributes. No errors are raised and the cmdlets complete successfully.

 

↑ Return to Top

Alternatives

Fortunately, there are alternate ways to accomplish the same tasks. To add a user to a group, the following script can be used.

$User = "jsmith"
$Group = "Sales in West"
Add-ADGroupMember -Identity $Group -Members $User

To remove a user from a group, a script similar to the following can be used.

$User = "jsmith"
$Group = "Sales in West,ou=School,dc=Hilltop,dc=rlmueller,dc=net"
Remove-ADGroupMember -Identity $Group -Members $User

The more difficult situation is alternatives for the -Clear parameter. The following script would be the most direct, but it requires looping through all of the groups.

$User = "jsmith"
$Groups = (Get-ADUser -Identity $User -Properties memberOf).memberOf
ForEach ($Group In $Groups)
{
    Remove-ADGroupMember -Identity $Group -Members $User -Confirm:$False
}

Another option is to use the Remove-ADPrincipalGroupMembership cmdlet to remove the memberships in one operation.

$User = "jsmith"
$Groups = (Get-ADUser -Identity $User -Properties memberOf).memberOf
Remove-ADPrincipalGroupMembership -Identity $User -MemberOf $Groups -Confirm:$False

A special case is the -Replace parameter. The documentation in the help files for the PowerShell AD cmdlets has incorrect information about this parameter. It replaces any existing value for an attribute with the value or values specified. If the attribute is multi-valued, it replaces all existing values with those specified. It does not replace one specified value with another. This issue was brought up and reported in the last two links in the "Other Resources" section below. The -Replace parameter probably should not be used with any multi-valued attributes.

When attempts were made to use the -Replace parameter in the "Examples" section above, an error was raised because the memberOf attribute is a back linked attribute. However, if the statement had succeeded, it would have replaced all existing values. You can use the -Replace parameter with the member attribute of groups. Just be aware that all members of the group will be replaced by the value (or values) that you specify.

↑ Return to Top

See Also

↑ Return to Top

Other Resources

↑ Return to Top