{"id":52843,"date":"2009-07-29T03:01:00","date_gmt":"2009-07-29T03:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2009\/07\/29\/hey-scripting-guy-how-can-i-add-a-user-to-multiple-groups\/"},"modified":"2009-07-29T03:01:00","modified_gmt":"2009-07-29T03:01:00","slug":"hey-scripting-guy-how-can-i-add-a-user-to-multiple-groups","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/hey-scripting-guy-how-can-i-add-a-user-to-multiple-groups\/","title":{"rendered":"Hey, Scripting Guy! How Can I Add a User to Multiple Groups?"},"content":{"rendered":"

<\/span><\/p>\n

\"Hey,<\/span><\/p>\n

Hey Scripting Guy! It seems that I can never find what I need anymore. I am looking for a Windows PowerShell script that will add a user to multiple groups. The user and the group are in the same organizational unit, and I do not want to have to run the same script multiple times to add a user to multiple groups. It should be easy to do, right?<\/p>\n<\/p>\n

— WK<\/p>\n

\n

 <\/p>\n

\n

 <\/p>\n

 <\/p>\n<\/p>\n

\"Hey,<\/p>\n

Hello WK, <\/p>\n

I am sorry you are having trouble finding information. You did not mention if it is the Internet in general, or the Script Center Web site that is causing you trouble. If it is the Internet in general, I would suggest you give Bing<\/font><\/a> a try—I have been using it since its inception and have been impressed with both its speed and the results it returns. In fact, I like it so much; I have it installed on my Windows Mobile Smart phone as well. Bing rocks and was a lifesaver when I was on vacation in New York City recently. If you are having problems navigating the Scripting Guys site, I would suggest you watch Script Center 101<\/font><\/a>. We have recently added a really cool control to the main Script Center page that hosts this entertaining and informative video. After watching Script Center 101, you will know as much about the Script Center as I do. <\/p>\n

In the meantime, I do not want you to miss out on finding a script, so I wrote the Add-UserToGroups.ps1 script for you. Check it out. it is cool. The complete script is seen here. <\/p>\n

Add-UserToGroups.ps1<\/p>\n

<\/strong><\/p>\n

Param(
   <\/span>[string[]]$group,
   <\/span>[string]$user,
   <\/span>[string]$ou,
   <\/span>[string]$domain,
   <\/span>[switch]$whatif,
   <\/span>[switch]$help,
   <\/span>[switch]$debug
) #end param<\/p>\n

Function Get-ScriptHelp
{
 <\/span>“Add-UserToGroups.ps1 adds a user to one or more groups. User and group must be in same OU”
 <\/span>“Add-UserToGroups.ps1 -user cn=myuser -group cn=mygroup -ou ou=myou -domain ‘dc=nwtraders,dc=com'”
  <\/span>“Add-UserToGroups.ps1 -user cn=myuser -group cn=mygroup1,cn=mygroup2 -ou ou=myou -domain ‘dc=nwtraders,dc=com'”
 <\/span>“Add-UserToGroups.ps1 -user cn=myuser -group cn=mygroup -ou ou=myou -domain ‘dc=nwtraders,dc=com’ -whatif”
} # end function Get-ScriptHelp<\/p>\n

Function Add-UserToGroups
{
 <\/span>Param(
   <\/span>[string[]]$group,
   <\/span>[string]$user,
   <\/span>[string]$ou,
   <\/span>[string]$domain
 <\/span>) #end param
 <\/span>$ads_Property_Append = 3
 <\/span>ForEach($g in $group)
 <\/span>{
   <\/span>write-debug “Connecting to group: LDAP:\/\/$g,$ou,$domain”
   <\/span>$de = [adsi]”LDAP:\/\/$g,$ou,$domain”
    <\/span>write-debug “Putting user: $user,$ou,$domain”
   <\/span>$de.putex($ads_Property_Append,”member”, @(“$user,$ou,$domain”))
   <\/span>$de.SetInfo()
  <\/span>} #end foreach
} # end function Add-UserToGroups<\/p>\n

Function Get-Whatif
{
  <\/span>Param(
   <\/span>[string[]]$group,
   <\/span>[string]$user,
   <\/span>[string]$ou,
   <\/span>[string]$domain
 <\/span>) #end param
 <\/span>ForEach($g in $group)
  <\/span>{
   <\/span>“WHATIF: Add user $user,$ou,$domain to $g,$ou,$domain”
  <\/span>} #end foreach
} #end function Get-Whatif<\/p>\n

# *** Entry Point to script ***
if($debug) { $debugPreference = “continue” }
if(-not($user -and $group -and $ou -and $domain))
  <\/span>{ throw (“user group ou and domain required”) }
if($whatif) { Get-Whatif -user $user -group $group -ou $ou -domain $domain ; exit }
if($help) { Get-Scripthelp ; exit }<\/p>\n

 <\/span>Write-Debug “Adding user to group …”
 <\/span>Write-Debug “Calling Add-UserToGroups function.”
 <\/span>Write-Debug “passing: user $user group $group ou $ou domain $domain”<\/p>\n

Add-UserToGroups -user $user -group $group -ou $ou -domain $domain<\/p>\n

<\/font><\/font><\/font><\/p>\n

The first thing the Add-UserToGroups.ps1 script does is create a series of command-line parameters. To create command-line parameters, use the Param<\/b> statement and separate each parameter with a comma. The group parameter is a string that will accept an array. The square brackets are used to indicate an array of strings. This allows you to supply the name of more than one group from the command line. The group parameter is seen here: <\/p>\n

[string[]]$group<\/span><\/p>\n

<\/font><\/font><\/p>\n

The user<\/b>, ou<\/b>, and domain<\/b> parameters are strings. When supplying the user name and the ou name from the command line, quotation marks are not required because the parameter expects a string to be supplied. The domain parameter value must be surrounded with single quotation marks. This is because the domain parts are separated by commas and would be interpreted as an array if they were not grouped by single quotation marks. The user<\/b>, ou<\/b>, and domain<\/b> parameters are seen here: <\/p>\n

[string]$user,
[string]$ou,
[string]$domain,<\/span><\/p>\n

<\/font><\/font><\/p>\n

The last three parameters are switched parameters. This means they only work if they are present on the command line. Switched parameters provide an easy way to incorporate additional functionality into the scripts design. Here three switched parameters are defined: whatif<\/b>, help<\/b>, and debug<\/b>. These three parameters correspond to the common parameters that are supported by most cmdlets. In this manner, the Add-UserToGroups.ps1 script will behave in a similar fashion as Windows PowerShell cmdlets and will therefore be easy to use. The switched parameters are shown here: <\/p>\n

   <\/font><\/span>[switch]$whatif,
   <\/span>[switch]$help,
   <\/span>[switch]$debug<\/span><\/p>\n

<\/font><\/font><\/p>\n

The complete Param<\/b> section of the script is seen here: <\/p>\n

Param(
   <\/span>[string[]]$group,
   <\/span>[string]$user,
   <\/span>[string]$ou,
   <\/span>[string]$domain,
   <\/span>[switch]$whatif,
   <\/span>[switch]$help,
   <\/span>[switch]$debug
) #end param<\/span><\/p>\n

<\/font><\/font><\/p>\n

When a script accepts command-line parameters, it is a best practice to provide help for the script. In Windows PowerShell 1.0, you can do this by creating a function that displays information about the parameters and acceptable syntax. In Windows PowerShell 2.0, there are tags that allow you to integrate the information with the Get-Help<\/b> cmdlet. In the Add-UserToGroups.ps1 script, a function named Get-ScriptHelp<\/b> is created to display the purpose of the script and several examples of allowable syntax. This ensures the script will run on both Windows PowerShell 2.0 and Windows PowerShell 1.0. The Get-ScriptHelp<\/b> function is called when the script is called with the help switch. The entire Get-ScriptHelp<\/b> function is seen here: <\/p>\n

Function Get-ScriptHelp
{
 <\/span>“Add-UserToGroups.ps1 adds a user to one or more groups. User and group must be in same OU”
 <\/span>“Add-UserToGroups.ps1 -user cn=myuser -group cn=mygroup -ou ou=myou
-domain ‘dc=nwtraders,dc=com'”
 <\/span>“Add-UserToGroups.ps1 -user cn=myuser -group cn=mygroup1,cn=mygroup2 -ou ou=myou
-domain ‘dc=nwtraders,dc=com'”
 <\/span>“Add-UserToGroups.ps1 -user cn=myuser -group cn=mygroup -ou ou=myou
-domain ‘dc=nwtraders,dc=com’ -whatif”
} # end function Get-ScriptHelp<\/span><\/p>\n

<\/font><\/font><\/p>\n

The main portion of the script is the Add-UserToGroups<\/b> function. This function begins by creating a series of parameters for the function. These parameters correspond to the parameters created by the script itself. The difference is there are no switched parameters for the function. The group<\/b> parameter is created as an array of strings just like it was at the beginning of the script. Similarly, the user<\/b>, ou<\/b>, and domain<\/b> parameters are defined as strings. This is seen here: <\/p>\n

Function Add-UserToGroups
{
 <\/span>Param(
   <\/span>[string[]]$group,
   <\/span>[string]$user,
   <\/span>[string]$ou,
   <\/span>[string]$domain
 <\/span>) #end param<\/span><\/p>\n

<\/font><\/font><\/p>\n

To update a property in Active Directory, you can use the putex<\/b> method. This method needs a value from the ADS_PROPERTY_OPERATION_ENUM<\/a>. The ADS<\/b><\/span>_PROPERTY_APPEND<\/b> constant is equal to the value 3. When this is set to 3, it instructs the directory service to append the property values to the object.<\/p>\n

The ADS_PROPERTY_OPERATION_ENUM<\/b> values seen in Table 1 are used in the first position of the putex<\/b> method call. <\/p>\n

Table 1<\/strong><\/p>\n

<\/p>\n\n\n\n\n\n
\n
\n

Enumeration name<\/p>\n

<\/strong><\/p>\n<\/div>\n<\/td>\n

\n
\n

Enumeration value<\/p>\n

<\/strong><\/p>\n<\/div>\n<\/td>\n<\/tr>\n

\n
\n

  <\/span>ADS_PROPERTY_CLEAR    <\/span><\/p>\n<\/div>\n<\/td>\n

\n
\n

 <\/span>1<\/p>\n<\/div>\n<\/td>\n<\/tr>\n

\n
\n

  <\/span>ADS_PROPERTY_UPDATE   <\/span><\/p>\n<\/div>\n<\/td>\n

\n
\n

 <\/span>2<\/p>\n<\/div>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

 <\/p>\n

<\/strong><\/p>\n

Rather than create an actual constant, you can create a variable and assign the value to it. As long as you do not modify the value of the variable, it will be constant. If you feel the need to protect the value, you could make it a read-only variable. To do this, you would use the following syntax:<\/p>\n

New-Variable -Name ads_Property_Append -Value 3 -Option readonly<\/span><\/p>\n

<\/font><\/font><\/p>\n

The advantage of a read-only variable is you can delete it or change the value if you specify the force switched parameter. You therefore obtain protection from inadvertent changes to the variable with the flexibility of making changes if you must do so. <\/p>\n

In the Add-UserToGroups<\/b> function there was no need to protect the variable, and a simple value assignment is used to create and to set the value for the variable. This is seen here: <\/p>\n

 <\/span>$ads_Property_Append = 3<\/span><\/p>\n

<\/font><\/font><\/p>\n

Because there may be more than one group that you wish to assign the user to, the ForEach<\/b> statement is used to iterate through the $group<\/b> variable. The variable $g<\/b> is used to keep track of the position inside the collection. In Windows PowerShell this works if there is a single value in the $group<\/b> variable or if there are many values. In VBScript, an error is generated when you try to walk through a collection by using For…Each…Next<\/b> and there is a single value in the variable. This line of code is seen here: <\/p>\n

 <\/font><\/span>ForEach($g in $group)
 <\/span>{<\/span><\/p>\n

<\/font><\/font><\/p>\n

You can use the Write-Debug<\/b> cmdlet to display debugging information when the script is run with the debug switch. If the script is not run with the debug switch, nothing is displayed on the command line. This is seen here:<\/p>\n

\"Image<\/p>\n


A well-designed series of Write-Debug<\/b> statements displays progress information on the Windows PowerShell console. The code that writes to the console is seen here: <\/p>\n

   <\/span>write-debug “Connecting to group: LDAP:\/\/$g,$ou,$domain”<\/span> <\/p>\n

<\/font><\/font><\/p>\n

Next the [adsi]<\/span> type accelerator is used to connect to the group. The LDAP protocol is used to make the connection to the group in Active Directory. The returned DirectoryEntry<\/b> object is stored in the variable $de<\/b> as seen here: <\/p>\n

   <\/span>$de = [adsi]”LDAP:\/\/$g,$ou,$domain”<\/span><\/p>\n

<\/font><\/font><\/p>\n

Now it is time to produce another Write-Debug<\/b> statement. This is seen here: <\/p>\n

    <\/span>write-debug “Putting user: $user,$ou,$domain”<\/span><\/p>\n

<\/font><\/font><\/p>\n

When the DirectoryEntry<\/b> object has been created and stored in the $de<\/b> variable, you can call the putex<\/b> method to append the user to the member<\/b> property of the group<\/b> object. This is seen here: <\/p>\n

   <\/span>$de.putex($ads_Property_Append,”member”, @(“$user,$ou,$domain”))<\/span><\/p>\n

<\/font><\/font><\/p>\n

Next you will need to commit your changes to Active Directory. To do this, you call the setinfo<\/b> method from the DirectoryEntry<\/b> object. This is seen here: <\/p>\n

   <\/font><\/span>$de.SetInfo()
  <\/span>} #end foreach
} # end function Add-UserToGroups<\/span><\/p>\n

<\/font><\/font><\/p>\n

It is time to create the Get-Whatif<\/b> function. The Get-Whatif<\/b> function is called when the script is run with the whatif<\/b> switched parameter. The first thing that must be done is to create the same parameters that are used by the Add-UserToGroups<\/b> function. This is because the Get-Whatif<\/b> will accept the command-line parameters that would be used to add a user to one or more groups. This is seen here: <\/p>\n

Function Get-Whatif
{
  <\/span>Param(
   <\/span>[string[]]$group,
   <\/span>[string]$user,
   <\/span>[string]$ou,
   <\/span>[string]$domain
 <\/span>) #end param<\/span><\/p>\n

<\/font><\/font><\/p>\n

Because there could be more than one group that is supplied from the command line, you will need to use the ForEach<\/b> statement to walk through the group names. Inside the ForEach<\/b> statement you display the WhatIf<\/b> information. This is seen here: <\/p>\n

<\/font><\/span><\/p>\n","protected":false},"excerpt":{"rendered":"

Hey Scripting Guy! It seems that I can never find what I need anymore. I am looking for a Windows PowerShell script that will add a user to multiple groups. The user and the group are in the same organizational unit, and I do not want to have to run the same script multiple times […]<\/p>\n","protected":false},"author":595,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[7,44,3,198,45],"class_list":["post-52843","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-active-directory","tag-groups","tag-scripting-guy","tag-users","tag-windows-powershell"],"acf":[],"blog_post_summary":"

Hey Scripting Guy! It seems that I can never find what I need anymore. I am looking for a Windows PowerShell script that will add a user to multiple groups. The user and the group are in the same organizational unit, and I do not want to have to run the same script multiple times […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/52843","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/595"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=52843"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/52843\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=52843"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=52843"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=52843"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}