Set-ADGroup

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:

Get-ADGroup - Get an AD group
Remove-ADGroup - Remove an AD group
New-ADGroup - Create an AD group


© Copyright SS64.com 1999-2014
Some rights reserved