.NET Assemblies In PowerShell – Part 2: Manage Active Directory group members and user accounts

In the first part of this series, I described how you can add and remove members to and from Active Directory groups in PowerShell, without using the ActiveDirectory module, but just by using the .Net namespace System.DirectoryServices.AccountManagement.

In this part I want to show how you can work with the members of a group, as well as with Active Directory accounts in general using this namespace in PowerShell. For the prerequisites, please check out the first part of this series.

The members property

In the last article, we created a GroupPrincipal object for an Active Directory group. One cool thing about this object type: you can easily work with any of the group members by accessing the Members property (type PrincipalCollection) of the group object.

By calling the Members property, a list of all group members will be shown, in which any group member is presented as a PrincipalContext object.

In the following example, we’re accessing the Members property of a group that contains two user accounts.

Well, this is really nice. First, we see a lot more of the members’ attributes than the Get-ADGroupMember cmdlet provides and second, we can directly work with these objects from here on. In my opinion, this is a great advantage over the ActiveDirectory PowerShell module. 

The group members 

Through the Members property we are not only able to list and manage who the members of a group are, we can even directly modify some attributes of the members (all attributes that are properties of the UserPrincipal class).

This could make some daily business tasks way easier for us.

For example: Let’s say you want to change the description for all members of a specific Active Directory group to “Test account”. Using the PowerShell ActiveDirectory module cmdlets, you would have to do something like this: 

  1. Run the Get-ADGroupMembers cmdlet.
    2. Iterate through the result.
    3. Pass each item of the result to the Set-ADUser cmdlet. 

Of course, you could also just pipe the result of the Get-ADGroupMember cmdlet to Set-ADUser.

Using the System.DirectoryServices.AccountManagement namespace, the steps would be the following:

First, let’s check the the current description of the group members (optional):

Now, let’s change it (this is actually all we need to do):

There will be no confirmation if the task was successful. In this case, no news is good news.

Finally, if we want to verify the effects of our command, we can just run the first command again (optional):

As we can see, the description of all group members was successfully changed to “Test account”. Pretty cool, huh?

Hint: Instead of using a For Each loop, we can even save some lines by calling the ForEach method of the Members property. See the following example:

Speed

Again, I was curious about how the execution times would compete against the cmdlets of the ActiveDirectory module. Here are the results of my measuring:

Sure, we already had the group object created before.

Ok, then let’s see how the creation of the group object will affect the execution time:

And…we have a winner. Even including all necessary code, we were still more than double as fast as the cmdlets of the ActiveDirectory module are.

 

The UserPrincipal object

Alright. Now, we know how to modify attributes of users that are members of a specific group. But, how do we work with an Active Directory user directly?

For this, we first need to create an object for the user which we want to manage.

This is done in the same way as for a group, except that we’re now using the UserPrincipal class of the System.DirectoryServices.AccountManagement namespace, instead of the GroupPrincipal class. Following, an example how to create such an object.

And, here’s our user:

Once created, we can access any of the UserPrincipal object’s properties and methods by using the PowerShell standard “.” notation.

Here’s an example how you can display only the DisplayName of the user object:

And here’s how you can change it:

Display the new value:

Keep in mind: For any changes of properties to take effect, the object has to be saved by using the Save method.

MemberOf

To list all Active Directory groups that a user is a member of, the UserPrincipal object provides the methods: GetGroups and GetAuthorizationGroups.

For a listing of groups of which the user is a direct member, we can use the GetGroups method, as shown below:

We see that the user is a member of the two groups “Domain Users” and “test-group001”. To make the output more readable, we can use the dot notation to show only the SAMAccountNames of those groups:

We can also include indirect memberships; groups in which the user is member of by group nesting.

For this, we need to use the GetAuthorizationGroups method. See the example below:

Now, the list contains some more groups. The additional groups are groups of which the user is a indirect member of. For example, we see the built-in group “Users” here, because the user is a member of the “Domain Users” group, which again is a member of the group “Users”.

Other useful methods

The UserPrincipal object provides some more pretty useful methods for daily business tasks on Active Directory user accounts. Following, there’s a brief description of some of them.

Check if an account is a member of a specific group

For this, we first need to create a GroupPrincipal object for the Active Directory group that we want to check. Once we’ve created it, we can check if the user is a member of that group, by calling the IsMemberOf method of the UserPrincipal object and passing the GroupPrincipal as an overload. Return values are “True”, or “False” (type Boolean).

Check if an account is locked out

Return values: “True”, or “False” (type Boolean).

Unlock an account

Refresh an expired password

Set a user’s password to expired

Set a new password

Delete a user account

Careful! There will be no confirmation question, or second approval option. It just deletes the account right away.

 

Further info

The “System.DirectoryServices.AccountManagement” namespace

The PrincipalContext class

The Add-Type cmdlet

How to work with .Net classes in PowerShell

 

In the next parts of this series, I will focus on creating Active Directory objects. So, stay tuned 😉

Leave a Reply

Your email address will not be published. Required fields are marked *