.NET Assemblies In PowerShell – Part 1: Manage Active Directory groups

The most popular way to manage Active Directory with PowerShell is to use the cmdlets provided by the PowerShell module ActiveDirectory. Most of you probably know some of these cmdlets and have already used them quite a bit. If so, you probably also know that this module is only available after you install the Active Directory RSAT tools on your machine, or when PowerShell is run directly on a Domain Controller.

But: There’s another way to manage Active Directory with PowerShell. 

The series “.NET Assemblies In PowerShell” is about how to use .Net assemblies in PowerShell for daily business tasks, instead of predefined modules and cmdlets.

In the first part, I want to show you how you can add and remove users from Active Directory groups with PowerShell from any Windows machine, without using the ActiveDirectory module. Those of  you who don’t like to read a lot and are more interested in some code snippets can just jump to the section As a function further down in this article. There, you will find a ready-to-use function for adding members to a group.

 

The namespace

First of all, we need the .Net Framework namespace System.DirectoryServices.AccountManagement. This namespace provides management capabilities for directory objects like users, computers and groups. The required assembly is available on any Windows machine by default, no matter if client or server OS.

To make the classes and functionalities of a namespace available in PowerShell, you can simply add it with the Add-Type cmdlet. In this case, the command would be the following:

 

The PrincipalContext object

Alright, we got the namespace. How do we proceed?

Through adding the namespace, we now have some new classes available for creating objects. One of them is the PrincipalContext class. We will use this one for the first object that we need to create. Here, we can specify the domain we want to operate in, the credentials and we could even provide a specific OU as a base for our operations. To create the object, we do as follows:

 

The group object

Next thing we need to do is to create an object for the group that we want to manage. For this, the namespace offers us the class  System.DirectoryServices.AccountManagement.GroupPrincipal. During creation, we basically search the group in AD and load it into an object. Here’s how to do it:

Now, we have the domain and the group. So, how do we add users to this group?

 

Add members

This time, we don’t have to create an object as well, for the member we want to add. We only need to specify by which identity type it will be identified (e.g. SAMAccountName, Distinguished Name, User Principal Name, etc.) and the actual identity of the new member. We then pass this info together with the PricipalContext object to the Add method of the group object’s Members property.

Lastly, we have to save the group object, so that the changes will be provisioned to the Active Directory.

 

Remove members

To remove a member from a group you can simply use the Remove method instead of the Add method.

 

All together now

Here’s a complete example of how you can add Active Directory user accounts to a group and how to remove them again.

Yeah, I know. That’s a whole lot of code for such a simple task. But we can simplify things… 

If you want to run the tasks in the current domain and you also want to use your current user for it, you can simply leave out the domain name and the credentials in the PrincipalContext constructor. This is how the constructor would then look like:

By this, the number of necessary lines can be reduced to the following:

Sure, it’s still a lot. It’s also a lot more coding effort than to just type Add-ADGroupMember -Identity group1 -Members user1. The advantage, as mentioned in the beginning, is that you can run this on any Windows machine without having the AD RSAT tools installed.

 

As a function

If you want to make things a little more convenient for you, just create a function around the code. Here’s a function I wrote to add members to a group.

The function basically works like the Add-ADGroupMember cmdlet. Specify the group name in the “groupname” parameter and the SAMAccountName(s) of the member(s) you want to add in the “members” parameter. Multiple members can be provided by using a comma (“,”) as delimiter. Here’s an example how to add two users to a group, by using the function:

During the execution it will show the result for each member you want to add:

 

List group members

To list all group members, you just need to access the Members property of the group object.

 

Speed

I had the feeling that these operations are executed a little faster than through the cmdlets of the Active Directory module. So, I measured the execution time with the Measure-Command cmdlet. Here is the result:

As we can see, the actual execution is a couple of milliseconds faster than by using the Add-ADGroupMember cmdlet. Although, if you would measure the whole function I provided before, the Add-ADGroupMember cmdlet still wins the race.

Further info

The “System.DirectoryServices.AccountManagement” namespace

The PrincipalContext class

The Add-Type cmdlet

How to work with .Net classes in PowerShell

 

In my second part of this series, I will write more about working with Active Directory group members and with Active Directory users in general. So, stay tuned ๐Ÿ˜‰

 

 

 

Photo by Blake Guidry on Unsplash

Leave a Reply

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