Modify an Active Directory group.
Syntax
Set-ADGroup [-Identity] ADGroup [-Add hashtable] [-Clear string[]]
[-Description string] [-DisplayName string] [-GroupCategory ADGroupCategory]
[-GroupScope ADGroupScope] [-HomePage string] [-ManagedBy ADPrincipal]
[-Remove hashtable] [-Replace hashtable] [-SamAccountName string]
[-AuthType {Negotiate | Basic}] [-Credential PSCredential]
[-Partition string] [-PassThru switch] [-Server string]
[-Confirm] [-WhatIf] [CommonParameters]
Set-ADGroup -Instance ADGroup [-AuthType {Negotiate | Basic}]
[-Credential PSCredential] [-Partition string[]] [-PassThru switch]
[-Server string] [-Confirm] [-WhatIf] [CommonParameters]
Key
-Add hashtable
Specify values to add to an object property.
Use this parameter to add one or more values to a property that cannot be modified
using a cmdlet parameter. To modify an object property, you must use the LDAP display name.
Specify multiple values to a property by specifying a comma-separated list of values
and more than one property by separating them using a semicolon.
The format for this parameter is
-Add @{Attribute1LDAPDisplayName=value1, value2, ...;
Attribute2LDAPDisplayName=value1, value2, ...; AttributeNLDAPDisplayName=value1, value2, ...}
For example, to remove the value "555-222-2222" and add the values "555-222-1111" and "555-222-3333
" to Phone-Office-Other attribute (LDAP display name 'otherTelephone'), and add the value "555-222-9999" to Pho
ne-Mobile-Other (LDAP display name 'otherMobile'), set the Add and Remove parameters as follows.
-Add @{otherTelephone='555-222-1111', '555-222-3333'; otherMobile='555-222-9999' } -Remove @{otherTelephone='
555-222-2222'}
When you use the -Add, -Remove, -Replace and -Clear parameters together, the operations will be
performed in the order: Remove, then Add, then Replace, then clear.
-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.
-Clear string[]
An array of object properties that will be cleared in the directory.
Use this parameter to clear one or more values of a property that cannot be modified
using a cmdlet parameter. To modify an object property, you must use the LDAP display name.
Modify more than one property by specifying a comma-separated list.
The format for this parameter is
-Clear Attribute1LDAPDisplayName, Attribute2LDAPDisplayName
For example, to clear the value for the Phone-Office-Other attribute
(LDAP display name 'otherTelephone') set the Clear parameter as follows.
-Clear otherTelephone
-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 Display 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 Display 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 Display 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 display 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 Display Name (ldapDisplayName) for this property is "wWWHomePage".
-Identity ADGroup
Specify an AD group object by providing one of the following values.
(The identifier in parentheses is the LDAP display name for the attribute.)
Distinguished Name
Example: CN=AnnualReports,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-21-3165297888-301567370-576410423-1103
Security Accounts Manager (SAM) Account Name (sAMAccountName)
Example: AnnualReports
The cmdlet searches the default naming context or partition to find the object.
If two or more objects are found, the cmdlet returns a non-terminating error.
This parameter can also get this object through the pipeline or you can set this
parameter to an object instance.
Examples:
-Identity "CN=AnnualReports,OU=europe,CN=users,DC=corp,DC=SS64,DC=com"
-Identity $ADGroupInstance
-Instance ADGroup
A modified copy of a group object to use to update the actual AD group object.
When this parameter is used, any modifications made to the modified copy of
the object are also made to the corresponding AD object.
The cmdlet only updates the object properties that have changed.
The -Instance parameter can only update group objects that have been retrieved
by using Get-ADGroup. When you specify the Instance parameter, you
cannot specify other parameters that set properties on the object.
The following is an example of how to use Get-ADGroup to retrieve an
instance of the ADGroup object. The object is modified by using the PowerShell
command line. Then the Set-ADGroup cmdlet saves the changes to the AD object.
Step 1: Retrieve a local instance of the object.
$groupInstance = Get-ADGroup -Identity "SS64Reports"
Step 2: Modify one or more properties of the object instance.
$groupInstance.GroupScope= "Global"
Step3: Save your changes to "SS64Reports".
Set-ADGroup -Instance $groupInstance
-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 display 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 Display Name of "managedBy".
-Partition string
The distinguished name of an AD partition.
The distinguished name must be one of the naming contexts on the current
directory server. The cmdlet searches this partition to find the object defined by
the -Identity parameter.
The following two examples show how to specify a value for this parameter.
-Partition "CN=Configuration,DC=Europe,DC=Test,DC=SS64,DC=com"
-Partition "CN=Schema,CN=Configuration,DC=Europe,DC=Test,DC=SS64,DC=com"
In many cases, a default value will be used for the Partition parameter if no value
is specified.
-PassThru switch
Return the new or modified object.
By default (i.e. if -PassThru is not specified), this cmdlet does not generate any output.
-Remove hashtable
Remove values of an object property.
Use this parameter to remove one or more values of a property that cannot be modified
using a cmdlet parameter. To remove an object property, you must use the LDAP display name.
You can remove more than one property by specifying a semicolon-separated list.
The format for this parameter is
-Remove @{Attribute1LDAPDisplayName=value[]; Attribute2LDAPDisplayName=value[]}
For example, to add the values blue and green and remove the value pink from a property with a LDAP
display name of FavColors, set the Add and Remove parameters as follows.
-Add @{FavColors=Blue,Green} -Remove {FavColors=Pink}
-Replace hashtable
Specify values for an object property that will replace the current values.
Use this parameter to replace one or more values of a property that cannot be modified
using a cmdlet parameter. To modify an object property, you must use the LDAP display name.
You can modify more than one property by specifying a comma-separated list.
The format for this parameter is
-Replace @{Attribute1LDAPDisplayName=value[], Attribute2LDAPDisplayName=value[]}
-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 display 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.
CommonParameters:
-Verbose, -Debug, -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer -OutVariable.
Set-ADGroup modifies the properties of an AD group. Commonly used property
values may be modified by using the cmdlet parameters. Property values that are not associated with cmdlet parameters can be modified by using the -Add, -Replace, -Clear and -Remove parameters.
The -Identity parameter specifies the AD group to modify. Identify a group by its distinguished name (DN), GUID, security identifier (SID) or Security Accounts Manager (SAM) account name. Alternatively set the
-Identity parameter to an object variable, or you can pass a group object through the PowerShell pipeline. For example, use Get-ADGroup to retrieve a group object and then pass the object through the pipeline to Set-ADGroup.
The -Instance parameter provides a way to update a group object by applying the changes made to a copy of the object. When you set the Instance parameter to a copy of an Active Directory group object that has been modified, the Set-ADGroup cmdlet can save the same changes back to the original group object. To get a copy of the object to modify, use Get-ADGroup. The -Identity parameter is not allowed when you use the -Instance parameter.
Examples
Set the description property of the group AccessControl to "Access Group" on an ADAM instance:
PS C:\> set-adgroup -server localhost:60000 -Identity "CN=AccessControl,DC=AppNC" -description "Access Group" -passthru
Modify the description on all groups that have a name that starts with 'access' via the pipeline:
PS C:\> get-adgroup -filter 'name -like "Access*"' | set-adgroup -description "Access Group"
Set the description property on the AccessControl group via the instance parameter:
PS adam:\DC=AppNC> get-adgroup -filter 'name -like "Access*"' | set-adgroup -description "Access Group"
PS adam:\DC=AppNC> $group = get-adgroup -server localhost:60000 -Identity "CN=AccessControl,DC=AppNC"
PS adam:\DC=AppNC> $group.description = "Access Group"
PS adam:\DC=AppNC> set-adgroup -Instance $group -passthru
“The secret of Happiness is Freedom, and the secret of Freedom, Courage” ~ Thucydides
Related PowerShell Cmdlets:
Get-ADGroup - Get an AD group.
Remove-ADGroup - Remove an AD group.
New-ADGroup - Create an AD group.