Create an Active Directory group.
Syntax
New-ADGroup [-Name] string [-GroupScope ADGroupScope]
[-AuthType {Negotiate | Basic}] [-Credential PSCredential] [-Description string]
[-DisplayName string] [-GroupCategory ADGroupCategory]
[-HomePage string] [-Instance ADGroup] [-ManagedBy ADPrincipal]
[-OtherAttributes hashtable] [-PassThru] [-Path string]
[-SamAccountName string] [-Server string]
[-Confirm] [-WhatIf] [CommonParameters]
Key
-AuthType {Negotiate | Basic}
The authentication method to use: Negotiate (or 0), Basic (or 1)
A Secure Sockets Layer (SSL) connection is required for Basic authentication.
-Credential PSCredential
The user account credentials to use to perform this task.
The default credentials are those of the currently logged on user unless the
cmdlet is run from an Active Directory PowerShell provider drive.
If the cmdlet is run from such a provider drive, the account associated with the drive is the default.
Type a user name, such as "User64" or "Domain64\User64" or specify a
PSCredential object such as one generated by Get-Credential
If a user name is specified, the cmdlet will prompt for a password.
-Description string
A description of the object.
This parameter sets the value of the Description property for the object.
The LDAP provider Name (ldapDisplayName) for this property is "description".
-DisplayName string
The display name of the object.
This parameter sets the DisplayName property of the object.
The LDAP provider Name (ldapDisplayName) for this property is "displayName".
-GroupCategory ADGroupCategory
The category of the group.
Possible values of this parameter are:
Distribution or 0
Security or 1
This parameter sets the GroupCategory property of the group.
This parameter value combined with other group values sets the LDAP provider Name
(ldapDisplayName) attribute named "groupType".
-GroupScope ADGroupScope
The group scope of the group. Possible values of this parameter are:
DomainLocal or 0
Global or 1
Universal or 2
This parameter sets the GroupScope property of a group object to the specified value.
The LDAP provider name of this property is "groupType".
-HomePage string
The URL of the home page of the object.
This parameter sets the homePage property of an Active Directory object.
The LDAP provider Name (ldapDisplayName) for this property is "wWWHomePage".
-Instance ADGroup
An instance of a group object to use as a template for a new group object.
Use an instance of an existing group object as a template or construct a
new group object by using the PowerShell command line or by using a script.
The following examples show how to use these two methods:
Method 1: Use the Get-ADGroup cmdlet and then override property values of
the new object by setting the appropriate parameters.
$groupInstance = Get-ADGroup -Identity "KarenTohReports"
New-ADGroup -Name "SS64 Reports" -Instance $groupInstance GroupType DomainLocal
Method 2: Use the New-Object cmdlet and pass the object to the New-ADGroup cmdlet.
$groupTemplate = New-Object Microsoft.ActiveDirectory.Management.ADGroup
$groupTemplateGroupType = DomainLocal
New-ADGroup -Name "SS64 Reports" -Instance $groupInstance
Note: Specified attributes are not validated, so attempting to set attributes that
do not exist or cannot be set will raise an error.
-ManagedBy ADPrincipal
The user or group that manages the object by providing one of the following property values.
Note: The identifier in parentheses is the LDAP provider name for the property.
Distinguished Name
Example: CN=demo1,OU=Europe,CN=Users,DC=corp,DC=ss64,DC=com
GUID (objectGUID)
Example: 599c3d2e-f72d-4d20-8a88-030d99495f20
Security Identifier (objectSid)
Example: S-1-5-64-3265277888-301567356-523410843-1244
SAM Account Name (sAMAccountName)
Example: demo1
This parameter sets the Active Directory attribute with an LDAP provider Name of "managedBy".
-Name string
The name of the object.
The LDAP provider Name (ldapDisplayName) of this property is "name".
-OtherAttributes hashtable
Object attribute values for attributes that are not represented by cmdlet parameters.
Set one or more parameters at the same time with this parameter.
If an attribute takes more than one value, you can assign multiple values.
To identify an attribute, specify the LDAP provider name (ldapDisplayName) defined for it in
the Active Directory schema.
Syntax:
To specify a single value for an attribute:
-OtherAttributes @{'AttributeLDAPName'=value}
To specify multiple values for an attribute
-OtherAttributes @{'AttributeLDAPName'=value1,value2,...}
Specify values for more than one attribute by using semicolons to separate attributes.
To set values for multiple attributes:
-OtherAttributes @{'Attribute1LDAPName'=value; 'Attribute2LDAPName'=value1,value2;...}
The following examples show how to use this parameter.
To set the value of a custom attribute called favColors that takes a set of Unicode strings:
-OtherAttributes @{'favColors'="pink","purple"}
To set values for favColors and dateOfBirth simultaneously, use the following syntax:
-OtherAttributes @{'favColors'="pink","purple"; 'dateOfBirth'=" 01/01/1960"}
-PassThru switch
Return the new or modified object.
By default (i.e. if -PassThru is not specified), this cmdlet does not generate any output.
-Path string
The X.500 path of the Organizational Unit (OU) or container where the new object is created.
In many cases, a default value will be used for -Path if no value is specified.
Note: The PowerShell cmdlets, such New-Item, Remove-Item, Remove-ItemProperty, Rename-Item and
Set-ItemProperty also contain a Path property. However, for the AD provider cmdlets, the -Path parameter
identifies the path of the actual object and not the container.
-SamAccountName string
The Security Account Manager (SAM) account name of the user, group, computer, or service account.
The maximum length of the description is 256 characters. To be compatible with older operating systems,
create a SAM account name that is 20 characters or less. This parameter sets the SAMAccountName
for an account object. The LDAP provider name (ldapDisplayName) for this property is "sAMAccountName".
Note: If the string value provided is not terminated with a '$' character, the system adds one if needed.
-Server string
The AD Domain Services instance to connect to, this may be a Fully qualified domain name,
NetBIOS name, Fully qualified directory server name (with or without port number)
-Confirm
Prompt for confirmation before executing the command.
-WhatIf
Describe what would happen if you executed the command without actually executing the command.
New-ADGroup creates a new Active Directory group object. Many object properties are defined by setting cmdlet parameters. Properties that cannot be set by cmdlet parameters can be set using the -OtherAttributes parameter.
There are 3 different ways to create an object by using this cmdlet:
Method 1: Use New-ADGroup, specify the required parameters, and set any additional property values by using the cmdlet parameters.
Method 2: Use a template to create the new object. To do this, create a new group object or retrieve a copy of an existing group object and set the Instance parameter to this object. The object provided to the Instance parameter is used as a template for the new object. You can override property values from the template by setting cmdlet parameters. For examples and more information, see the -Instance parameter description for this cmdlet.
Method 3: Use Import-CSV with the New-ADGroup cmdlet to create multiple Active Directory group objects.
To do this, use the Import-CSV cmdlet to create the custom objects from a comma-separated value (CSV) file that contains a list of object properties. Then pass these objects through the pipeline to the New-ADGroup cmdlet to create
the group objects.
Create a new group named 'RODC Admins' in the container 'CN=Users,DC=SS64,DC=Com' and set the GroupCategory, DisplayName, GroupScope, and Description properties on the new object.:
PS C:\> New-ADGroup -Name "RODC Admins" -SamAccountName RODCAdmins -GroupCategory Security -GroupScope Global -DisplayName "RODC Administrators" -Path "CN=Users,DC=SS64,DC=Com" -Description "Members of this group are RODC Administrators"
Create a new group using the cmdlet default behavior:
PS C:\> New-ADGroup
cmdlet New-ADGroup at command pipeline position 1
Supply values for the following parameters:
GroupScope: Universal
Name: SS64grp
Create a new group using the property values from a current group:
PS C:\> Get-ADGroup SS64 -Properties Description | New-ADGroup -Name NewEmployees -SamAccountName NewEmp -GroupCategory Distribution -PassThru
Create a new group named 'G-Sales-Alaska' on an AD LDS instance:
PS C:\> New-ADGroup -Server localhost:60000 -Path "OU=SalesDeptOU,DC=AppNC" -Name G-Sales-Alaska -GroupScope DomainLocal -GroupCategory Distribution
“A human being should be able to change a diaper, plan an invasion, butcher a hog, conn a ship, design a building, write a sonnet, balance accounts, build a wall, set a bone, comfort the dying, take orders, give orders, cooperate, act alone, solve equations, analyze a new problem, pitch manure, program a computer, cook a tasty meal, fight efficiently, die gallantly. Specialization is for insects” ~ Robert Anson Heinlein
Get-ADGroup - Get an AD group.
Remove-ADGroup - Remove an AD group.
Set-ADGroup - Modify an AD group.
New-LocalGroup - Add a local group.
How-to: Understand the different types of Active Directory group.