ADGroup

ADGroup

Parameters

Parameter	Attribute	DataType	Description	Allowed Values
GroupName	Key	String	Name of the Active Directory group.
GroupScope	Write	String	Active Directory group scope. Default value is 'Global'.	DomainLocal, Global, Universal
Category	Write	String	Active Directory group category. Default value is 'Security'.	Security, Distribution
Path	Write	String	Location of the group within Active Directory expressed as a Distinguished Name.
Ensure	Write	String	Specifies if this Active Directory group should be present or absent. Default value is 'Present'.	Present, Absent
Description	Write	String	Description of the Active Directory group.
DisplayName	Write	String	Display name of the Active Directory group.
Credential	Write	PSCredential	The credential to be used to perform the operation on Active Directory.
DomainController	Write	String	Active Directory domain controller to enact the change upon.
Members	Write	StringArray[]	Active Directory group membership should match membership exactly.
MembersToInclude	Write	StringArray[]	Active Directory group should include these members.
MembersToExclude	Write	StringArray[]	Active Directory group should NOT include these members.
MembershipAttribute	Write	String	Active Directory attribute used to perform membership operations. Default value is 'SamAccountName'.	SamAccountName, DistinguishedName, ObjectGUID, SID
ManagedBy	Write	String	Active Directory managed by attribute specified as a DistinguishedName.
Notes	Write	String	Active Directory group notes field.
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'
            )
        }
    }
}