ADGroup

Parameters

Parameter	Attribute	DataType	Description	Allowed Values
GroupName	Key	String	Specifies the Security Account Manager (SAM) account name of the group (ldapDisplayName 'sAMAccountName').
AdminDescription	Write	String	Specifies the description displayed on admin screens. Can be set to Group_ to filter out a group from Entra ID Connect synchronization.
Category	Write	String	Active Directory group category. Default value is 'Security'.	Security, Distribution
CommonName	Write	String	Specifies the common name assigned to the group (ldapDisplayName 'cn'). If not specified the default value will be the same value provided in parameter GroupName.
Credential	Write	PSCredential	The credential to be used to perform the operation on Active Directory.
Description	Write	String	Description of the Active Directory group.
DisplayName	Write	String	Display name of the Active Directory group.
DomainController	Write	String	Active Directory domain controller to enact the change upon.
Ensure	Write	String	Specifies if this Active Directory group should be present or absent. Default value is 'Present'.	Present, Absent
GroupScope	Write	String	Active Directory group scope. Default value is 'Global'.	DomainLocal, Global, Universal
ManagedBy	Write	String	Active Directory managed by attribute specified as a DistinguishedName.
Members	Write	StringArray[]	Active Directory group membership should match membership exactly.
MembershipAttribute	Write	String	Active Directory attribute used to perform membership operations. Default value is 'SamAccountName'.	SamAccountName, DistinguishedName, ObjectGUID, SID
MembersToExclude	Write	StringArray[]	Active Directory group should NOT include these members.
MembersToInclude	Write	StringArray[]	Active Directory group should include these members.
Notes	Write	String	Active Directory group notes field.
Path	Write	String	Location of the group within Active Directory expressed as a Distinguished Name.
RestoreFromRecycleBin	Write	Boolean	Try to restore the group from the recycle bin before creating a new one.
DistinguishedName	Read	String	Returns the distinguished name of the Active Directory group.

Description

The ADGroup DSC resource will manage groups within Active Directory.

Requirements

• Target machine must be running Windows Server 2008 R2 or later.
• The parameter RestoreFromRecycleBin requires that the feature Recycle Bin has been enabled prior to an object is deleted. If the feature Recycle Bin is disabled then the property msDS-LastKnownRDN is not added the deleted object.

Examples

Example 1

This configuration will create a new domain-local group

Configuration ADGroup_NewGroup_Config
{
    param
    (
        [parameter(Mandatory = $true)]
        [System.String]
        $GroupName,

        [ValidateSet('DomainLocal', 'Global', 'Universal')]
        [System.String]
        $Scope = 'Global',

        [ValidateSet('Security', 'Distribution')]
        [System.String]
        $Category = 'Security',

        [ValidateNotNullOrEmpty()]
        [System.String]
        $Description
    )

    Import-DscResource -Module ActiveDirectoryDsc

    Node localhost
    {
        ADGroup 'ExampleGroup'
        {
            GroupName   = $GroupName
            GroupScope  = $Scope
            Category    = $Category
            Description = $Description
            Ensure      = 'Present'
        }
    }
}

Example 2

This configuration will create a new domain-local group with three members.

Configuration ADGroup_NewGroupWithMembers_Config
{
    Import-DscResource -ModuleName ActiveDirectoryDsc

    node localhost
    {
        ADGroup 'dl1'
        {
            GroupName  = 'DL_APP_1'
            GroupScope = 'DomainLocal'
            Members    = 'john', 'jim', 'sally'
        }
    }
}

Example 3

This configuration will create a new domain-local group in contoso with three members in different domains.

Configuration ADGroup_NewGroupMultiDomainMembers_Config
{
    Import-DscResource -ModuleName ActiveDirectoryDsc

    node localhost
    {
        ADGroup 'dl1'
        {
            GroupName           = 'DL_APP_1'
            GroupScope          = 'DomainLocal'
            MembershipAttribute = 'DistinguishedName'
            Members             = @(
                'CN=john,OU=Accounts,DC=contoso,DC=com'
                'CN=jim,OU=Accounts,DC=subdomain,DC=contoso,DC=com'
                'CN=sally,OU=Accounts,DC=anothersub,DC=contoso,DC=com'
            )
        }
    }
}

Example 4

This configuration will create a new domain-local group in contoso with two members; one from the contoso domain and one from the fabrikam domain. This qualified SamAccountName format is required if any of the users are in a one-way trusted forest/external domain.

Configuration ADGroup_NewGroupOneWayTrust_Config
{
    Import-DscResource -ModuleName ActiveDirectoryDsc

    node localhost
    {
        ADGroup 'ExampleExternalTrustGroup'
        {
            GroupName           = 'ExampleExternalTrustGroup'
            GroupScope          = 'DomainLocal'
            MembershipAttribute = 'SamAccountName'
            Members             = @(
                'contoso\john'
                'fabrikam\toby'
            )
        }
    }
}