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.
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 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:
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:
|Distinguished name||Get-ADGroup CN=Domain Users,CN=Users,DC=domain,DC=local|
|SAM account name||Get-ADGroup “Domain Users”|
|CN||Get-ADGroup “Domain Users”|
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:
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:
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:
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:
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 has a default set of parameters that can be used to set attributes for the group object. These include the following:
The following command uses each of these parameters to create an AD DS group object:
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.
|Path||Toronto OU||-Path “OU=Toronto,DC=domain,dc=local”|
|SAM account name||GroupA||-SAMAccountName GroupA|
|Managed By||JPOLICELLI||-ManagedBy JPOLICELLI|
|Description||Test Group||-Description “Test Group”|
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 email@example.com:
The full command would be:
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:
The table below shows the different formats that can be used to delete the same AD DS user account:
|Distinguished name||Remove-ADGroup “CN=GroupA,OU=Toronto,DC=domain,DC=local”|
|SAM account name||Remove-ADGroup|
As shown in the figure below, Remove-ADGroup will prompt you to confirm the deletion.
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:
To retrieve the membership of a group that has a SAM account name of Group1, you would use the following command:
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-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:
The figure below shows the command, and the results, to retrieve the group membership for the Administrator account:
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:
You can use any of the following to identify the members you want to add or remove:
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:
You can specify multiple members in a single command as follows:
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:
As shown in the figure below, you will be prompted for confirmation:
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:
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:
To change the scope of a group from Global to Universal, you can use the following command:
To change the type of a group from Security to Distribution, you can use the following command:
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.
John Policelli (Microsoft MVP for Directory Services, MCTS, MCSA, ITSM, iNet+, Network+, and A+) is a solutions-focused IT consultant with over a decade of combined success in architecture, security, strategic planning, and disaster recovery planning. John has designed and implemented dozens of complex directory service, e-Messaging, web, networking, and security enterprise solutions.
John has spent the past nine years focused on Identity and Access Management and providing thought leadership for some of the largest installations of Active Directory in Canada. He has been involved as an author, technical reviewer, and subject matter expert for over 50 training, exam writing, press, and whitepaper projects related to Windows Server 2008 Identity and Access Management, networking, and collaboration.
John's is the co-author of MCITP Self-Paced Training Kit (Exam 70-647): Windows Server Enterprise Administration. His latest book Active Directory Domain Services 2008 How-To has been selected as Microsoft Subnet's June, 2009, book giveaway.
To enter to win a copy of the book-of-the-month book giveway, visit the Microsoft Subnet home page.