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 link 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 link attribute. The same problem affects the -Add, -Remove, and -Replace parameters. They cannot be used to modify back link attributes.

↑ Return to Top


Linked Attributes

Linked attributes in Active Directory are pairs of related distinguished name attributes. One is called the forward link attribute, the other the back link 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 we use the Active Directory Users and Computers mmc 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 happens if we use a script 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, we use Get-ADUser to retrieve the memberOf attribute of a user. We then attempt 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 we attempt to modify any back link 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 we attempt to use the -Remove, -Add, and -Replace parameters of Set-ADUser 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 we first retrieve the directReports of a user, then attempt to clear the directReports. The same error is raised.

 

To demonstrate that these parameters can be used to modify the forward link attribute, the below image shows the result when we modify 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 we attempted to use the -Replace parameter in the "Examples" section above, an error was raised because the memberOf attribute is a back link 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