How-To Administer Active Directory Domain Services Groups Using Windows PowerShell

The Active Directory Module for Windows PowerShell, which is included with Windows Server 2008 R2, can be used to administer Active Directory Domain Services (AD DS) objects, including group objects. For an overview of the Active Directory Module for Windows PowerShell, please see Introducing the Active Directory Module for Windows PowerShell.

What follows is an in-depth look at administering AD DS groups by using the Active Directory Module for Windows PowerShell.

Overview

There are a number of tasks that can be performed on group objects by using the cmdlets included with the Active Directory Module for Windows PowerShell, such as:

• Get-ADGroup
• New-ADGroup
• Remove-ADGroup
• Get-ADGroupMember
• Get-ADPrincipalGroupMembership
• Add-ADGroupMember
• Remove-ADGroupMember
• Add-ADPrincipalGroupMembership
• Set-ADGroup
• Move-ADObject
• RenameObjects
• Rename-ADObject

Retrieving AD DS Groups

Get-ADGroup can be used to retrieve AD DS group objects. Get-ADGroup allows you to find one or more AD DS group objects that meet criteria you specify.

Get-ADGroup allows you to specify the search criteria in multiple formats, including:

• Distinguished name
• GUID
• SID
• SAM account name
• CN

One of the advantages of Get-ADGroup is that it automatically recognizes the format of the criteria for all but LDAP filter. In other words, you do not have include a parameter in the command to tell it which format you are using. The table below shows the different formats that can be used to find the same AD DS group objects:

The LDAP filter format is particularly useful when you need to find more than one AD DS group objects. You can use this parameter to specify any LDAP supported filter format. For example, to find all AD DS group objects that have a name that contains Sales, you can use the following command:

• Get-ADGroup -LDAPFilter "(cn=*Sales*)"

As shown in the figure below, Get-ADGroup will return a default list of group object properties.

However, you can control which group object properties are returned by Get-ADGroup. To control which group object properties are returned by Get-ADGroup, you need to use the Properties parameter. As shown in the figure below, you can use a wildcard with the Properties parameter to return all properties for the AD DS group(s) found:

As shown in the figure below, you can also expand the list of properties you want returned for the AD DS group(s) found using a comma-separated list of the names of the properties you want returned:

You can also specify the search base and search scope by using the -SearchBase and -SearchScope parameters, respectively.

If you want to limit your search to a particular Organizational Unit, you can use the –SearchBase parameter and specify the distinguished name of the OU. The following command sets the search base to the Toronto OU:

• Get-ADGroup -LDAPFilter "(cn=*Sales*)" -searchBase “OU=Toronto,DC=domain,dc=local”

The -SearchScope parameter allows you to control the scope of the search. The scope can be set to Base, OneLevel, or SubTree. Base searches the current path/object; OneLevel searches the immediate children of the path/object; SubTree searches the current path/object and its children.

Adding the to above example, you can refine the command so that it only searches the Toronto OU, and no child-OUs by typing the following command:

• Get-ADGroup -LDAPFilter "(cn=*Sales*)" -SearchBase “OU=Toronto,DC=domain,dc=local” -SearchScope Base

Creating AD DS Group Objects

New-ADGroup can be used to create an AD DS group object. At minimum, you must specify the group scope and name to create an AD DS group. The command to create a global group with a name of Group1 is:

• New-ADGroup -Name Group1 -GroupScope Global

The above command will create the AD DS group object in the default container for groups, which is the Users container by default. Because the group category was not specified, the group will be created as a security group, which is the default. To create the group object as a distribution group, you can use the following command:

• New-ADGroup -Name Group1 -GroupScope Global -GroupCategory Distribution

New-ADGroup has a default set of parameters that can be used to set attributes for the group object. These include the following:

• Name
• Path
• SAM account name
• Managed By
• Group category (type)
• Description
• Group scope

The following command uses each of these parameters to create an AD DS group object:

• New-ADGroup -Name GroupA -path “OU=Toronto,DC=domain,DC=local” -SAMAccountName GroupA -ManagedBy JPOLICELLI -GroupCategory Security -Description “Test Group” -GroupScope Global

The table below breaks down the above command. The Attributes column lists the attributes that were set by the above command. The Value column lists the value that was set for each attribute. The Cmdlet Parameter column lists the actual cmdlet parameter and value that was used to set the value for each attribute.

You can also use the OtherAttributes parameter to specify values for attributes that are not represented by the default parameters. The following would be added to the above command to set the mail attribute to jpolicelli@domain.local:

-OtherAttributes @{'mail'=jpolicelli@domain.local}

The full command would be:

• New-ADGroup -Name GroupA -path “OU=Toronto,DC=domain,DC=local” -SAMAccountName GroupA -ManagedBy JPOLICELLI -GroupCategory Security -Description “Test Group” -GroupScope Global -OtherAttributes @{'mail'=jpolicelli@domain.local}

Deleting AD DS Group Objects

Remove-ADGroup can be used to delete AD DS group objects. Remove-ADGroup simply requires that you specify the object you want to delete. This can be specified in the following formats:

• Distinguished name
• GUID
• SID
• SAM account name
• CN

The table below shows the different formats that can be used to delete the same AD DS user account:

As shown in the figure below, Remove-ADGroup will prompt you to confirm the deletion.

Retrieving AD DS Group Membership

Get-ADGroupMember retrieves membership of an AD DS group. Get-ADGroupMember simply requires that you specify the group that you want to retrieve membership for. This can be specified in the following formats:

• DN
• GUID
• SID
• SAM account name

To retrieve the membership of a group that has a SAM account name of Group1, you would use the following command:

• Get-ADGroupMember Group1

By default, Get-ADGroupMember retrieves the direct members of a group. However, you can use the Recursive parameter with Get-ADGroupMember to retrieve direct and indirect members. In other words, the Recursive parameter will give you the full group membership, including the membership of any groups that are nested.

To retrieve the full group membership of a group that has a SAM account name of Group1, you would use the following command:

• Get-ADGroupMember Group1 –Recursive

Retrieving the AD DS Groups that a Security Principal is a Member of

Get-ADPrincipalGroupMembership retrieves the groups that a security principal (user, group, computer) is a member of. This is particularly useful when you need to determine all of the groups that a specific user belongs to. This cmdlet requires that a Global Catalog exist in the forest.

Get-ADPrincipalGroupMembership requires that you specify the security principal you want to retrieve the group membership for. This can be specified in the following formats:

• DN
• GUID
• SID
• SAM account name

The figure below shows the command, and the results, to retrieve the group membership for the Administrator account:

Managing AD DS Group Membership

Add-ADGroupMember and Remove-ADGroupMember can be used to manage group membership. In both cases, you need to specify the group you want to manage group membership for and the members you want to add or remove. You can use any of the following to specify the group  that you want to manage group membership for:

• DN
• GUID
• SID
• SAM account name

You can use any of the following to identify the members you want to add or remove:

• DN
• GUID
• SID
• SAM account name

To add a user that has a SAM account name of Administrator to a group that has a SAM account name of Group1, you would use the following command:

• Add-ADGroupMember Group1 Administrator

You can specify multiple members in a single command as follows:

• Add-ADGroupMember Group1 Member1,Member2,Member3,etc…

To remove a user that has a SAM account name of Administrator from a group that has a SAM account name of Group1, you would use the following command:

• Remove-ADGroupMember Group1 Administrator

As shown in the figure below, you will be prompted for confirmation:

Modifying AD DS Group Objects

Set-ADGroup can be used to modify the properties of an AD DS group objects. Set-ADGroup has a predefined list of properties that can modified, including the following:

• GroupScope
• ManagedBy
• DisplayName
• SAMAccountName
• GroupCategory
• Description
• HomePage

When using Set-ADGroup, you must specify the group that you want to modify. You can use the following formats to specify the group you want to modify:

• DN
• GUID
• SID
• SAM account name

To change the scope of a group from Global to Universal, you can use the following command:

• Set-ADGroup Group1 -GroupScope Universal

To change the type of a group from Security to Distribution, you can use the following command:

• Set-ADGroup Group1 -GroupCategory Distribution

Wrapping Up

The Active Directory Module for Windows PowerShell provides a powerful solution for managing Active Directory Domain Services groups with PowerShell. This module can be used to perform virtually every task on AD DS group objects. What’s more, the cmdlets specific to AD DS groups are robust and easy to learn.

• Microsoft
• Active Directory
• Active Directory DOmain Services
• AD
• AD DS
• Microsoft
• Microsoft Windows Power Shell
• Windows Server 2008 R2