{"id":16411,"date":"2010-11-25T00:01:00","date_gmt":"2010-11-25T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2010\/11\/25\/use-powershell-to-add-local-users-to-local-groups\/"},"modified":"2010-11-25T00:01:00","modified_gmt":"2010-11-25T00:01:00","slug":"use-powershell-to-add-local-users-to-local-groups","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/use-powershell-to-add-local-users-to-local-groups\/","title":{"rendered":"Use PowerShell to Add Local Users to Local Groups"},"content":{"rendered":"

 <\/p>\n

Summary:<\/span><\/b> Microsoft Scripting Guy Ed Wilson shows how to add local users to local groups using Windows PowerShell.<\/span><\/p>\n

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

\"Hey,Hey, Scripting Guy! I have enjoyed your posts this week. It is amazing how often I need to enable the Local Administrator account, or create a new local user or group. One thing you have left out, however, is how I add a local user to a local group. In addition, I am using Windows PowerShell 2.0<\/span><\/a>, therefore you do not need to worry about backward compatibility. <\/span><\/p>\n

— EJ<\/span><\/p>\n

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

\"Hey,Hello EJ, Microsoft Scripting Guy Ed Wilson here. I am glad you have been enjoying my local user blog posts this week. You are right; the ability to create a local user and to create a local group is only half of the equation. To complete the local management story one must be able to add a user to a group. Because you do not need backward compatibility with Windows PowerShell 1.0, I am going to use a script that I wrote for the Windows 7 Resource Kit<\/span><\/a>. The Windows PowerShell 2.0 features that it uses are the help tags<\/span><\/a>. If one needed to, they could modify the script rather easily to work on Windows PowerShell 1.0 by changing out the help tags with the here-string syntax I have used earlier this week<\/span><\/a>. <\/span><\/p>\n

The Microsoft Press Windows 7 Resource Kit<\/span><\/a> is the authoritative reference book for IT Pros and others who wish to learn Windows 7. I wrote the chapter on Windows PowerShell for the book, as well as writing nearly 200 scripts for the book. It was a fun project. <\/span><\/p>\n

The complete Add-LocalUserToLocalGroup.ps1<\/b> script is seen here.<\/span><\/p>\n

Add-LocalUserToLocalGroup.ps1<\/span><\/strong><\/p>\n

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

   <\/span>.Synopsis<\/span><\/span><\/p>\n

    <\/span>Adds a local user to a local group on either a local or remote machine.<\/span><\/span><\/p>\n

   <\/span>.Description<\/span><\/span><\/p>\n

    <\/span>This script uses [adsi] type accelerator to use ADSI to create a local group.<\/span><\/span><\/p>\n

    <\/span>It will throw an error if $group is not present. It uses the WinNT provider to <\/span><\/span><\/p>\n

    <\/span>connect to local SAM database. This is case sensitive. This script must run with <\/span><\/span><\/p>\n

    <\/span>ADMIN rights to create local groups.<\/span><\/span><\/p>\n

   <\/span>.Example<\/span><\/span><\/p>\n

    <\/span>Add-LocalUserToLocalGroup.ps1 -computer MunichServer -user myUser -group mygroup<\/span><\/span><\/p>\n

    <\/span>Adds a local user called myUser on a computer named MunichServer to a local group called mygroup<\/span><\/span><\/p>\n

   <\/span>.Example<\/span><\/span><\/p>\n

    <\/span>Add-LocalUserToLocalGroup.ps1 -user myUser -group mygroup<\/span><\/span><\/p>\n

    <\/span>Adds a local user called myUser on local computer to a group called mygroup<\/span><\/span><\/p>\n

   <\/span>.Inputs<\/span><\/span><\/p>\n

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

   <\/span>.OutPuts<\/span><\/span><\/p>\n

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

   <\/span>.Notes<\/span><\/span><\/p>\n

    <\/span>NAME:  <\/span>Windows 7 Resource Kit<\/span><\/span><\/p>\n

    <\/span>AUTHOR: Ed Wilson<\/span><\/span><\/p>\n

    <\/span>LASTEDIT: 5\/20\/2009<\/span><\/span><\/p>\n

    <\/span>KEYWORDS: ADSI<\/span><\/span><\/p>\n

   <\/span>.Link<\/span><\/span><\/p>\n

     <\/span>Http:\/\/www.ScriptingGuys.com<\/span><\/span><\/p>\n

#Requires -Version 2.0<\/span><\/span><\/p>\n

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

param(<\/span><\/span><\/p>\n

      <\/span>$computer=$env:computerName, <\/span><\/span><\/p>\n

      <\/span>[Parameter(mandatory=$true)]<\/span><\/span><\/p>\n

      <\/span>$user, <\/span><\/span><\/p>\n

      <\/span>[Parameter(mandatory=$true)]<\/span><\/span><\/p>\n

      <\/span>$group<\/span><\/span><\/p>\n

) #end param<\/span><\/span><\/p>\n

# *** Functions<\/span><\/span><\/p>\n

function New-Underline<\/span><\/span><\/p>\n

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

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

.Synopsis<\/span><\/span><\/p>\n

 <\/span>Creates an underline the length of the input string<\/span><\/span><\/p>\n

.Example<\/span><\/span><\/p>\n

 <\/span>New-Underline -strIN “Hello world”<\/span><\/span><\/p>\n

.Example<\/span><\/span><\/p>\n

 <\/span>New-Underline -strIn “Morgen welt” -char “-” -sColor “blue” -uColor “yellow”<\/span><\/span><\/p>\n

.Example<\/span><\/span><\/p>\n

 <\/span>“this is a string” | New-Underline<\/span><\/span><\/p>\n

.Notes<\/span><\/span><\/p>\n

 <\/span>NAME:<\/span><\/span><\/p>\n

 <\/span>AUTHOR: Ed Wilson<\/span><\/span><\/p>\n

 <\/span>LASTEDIT: 5\/20\/2009<\/span><\/span><\/p>\n

 <\/span>KEYWORDS:<\/span><\/span><\/p>\n

.Link<\/span><\/span><\/p>\n

 <\/span>Http:\/\/www.ScriptingGuys.com<\/span><\/span><\/p>\n

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

[CmdletBinding()]<\/span><\/span><\/p>\n

param(<\/span><\/span><\/p>\n

      <\/span>[Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]<\/span><\/span><\/p>\n

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

      <\/span>$strIN,<\/span><\/span><\/p>\n

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

      <\/span>$char = “=”,<\/span><\/span><\/p>\n

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

      <\/span>$sColor = “Green”,<\/span><\/span><\/p>\n

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

      <\/span>$uColor = “darkGreen”,<\/span><\/span><\/p>\n

      <\/span>[switch]<\/span><\/span><\/p>\n

      <\/span>$pipe<\/span><\/span><\/p>\n

 <\/span>) #end param<\/span><\/span><\/p>\n

 <\/span>$strLine= $char * $strIn.length<\/span><\/span><\/p>\n

 <\/span>if(-not $pipe)<\/span><\/span><\/p>\n

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

   <\/span>Write-Host -ForegroundColor $sColor $strIN<\/span><\/span><\/p>\n

   <\/span>Write-Host -ForegroundColor $uColor $strLine<\/span><\/span><\/p>\n

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

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

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

  <\/span>$strIn<\/span><\/span><\/p>\n

  <\/span>$strLine<\/span><\/span><\/p>\n

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

} #end New-Underline function<\/span><\/span><\/p>\n

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

function Test-IsAdministrator<\/span><\/span><\/p>\n

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

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

    <\/span>.Synopsis<\/span><\/span><\/p>\n

        <\/span>Tests if the user is an administrator<\/span><\/span><\/p>\n

    <\/span>.Description<\/span><\/span><\/p>\n

        <\/span>Returns true if a user is an administrator, false if the user is not an administrator    <\/span>    <\/span><\/span><\/span><\/p>\n

    <\/span>.Example<\/span><\/span><\/p>\n

        <\/span>Test-IsAdministrator<\/span><\/span><\/p>\n

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

    <\/span>param() <\/span><\/span><\/p>\n

    <\/span>$currentUser = [Security.Principal.WindowsIdentity]::GetCurrent()<\/span><\/span><\/p>\n

    <\/span>(New-Object Security.Principal.WindowsPrincipal $currentUser).IsInRole([Security.Principal.WindowsBuiltinRole]::Administrator)<\/span><\/span><\/p>\n

} #end function Test-IsAdministrator<\/span><\/span><\/p>\n

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

# *** Entry point to script ***<\/span><\/span><\/p>\n

If(-not (Test-IsAdministrator)) { New-Underline “Admin rights are required for this script” ; exit }<\/span><\/span><\/p>\n

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

if(!$user -or !$group) <\/span><\/span><\/p>\n

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

       <\/span>$(Throw ‘A value for $user and $group is required.’)<\/span><\/span><\/p>\n

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

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

$OBjOU = [ADSI]”WinNT:\/\/$computer\/$group,group”<\/span><\/span><\/p>\n

$objOU.add(“WinNT:\/\/$computer\/$user”)<\/span><\/span><\/p>\n

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

The Add-LocalUserToLocalGroup.ps1<\/b> script is rather long, but what it does is not very complicated. In fact, most of the code is taken up with the comment-based help. The script begins with a comment block that provides command line help for the script. The comment block is listed here.<\/span><\/p>\n

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

   <\/span>.Synopsis<\/span><\/span><\/p>\n

    <\/span>Adds a local user to a local group on either a local or remote machine.<\/span><\/span><\/p>\n

   <\/span>.Description<\/span><\/span><\/p>\n

    <\/span>This script uses [adsi] type accelerator to use ADSI to create a local group.<\/span><\/span><\/p>\n

    <\/span>It will throw an error if $group is not present. It uses the WinNT provider to <\/span><\/span><\/p>\n

    <\/span>connect to local SAM database. This is case sensitive. This script must run with <\/span><\/span><\/p>\n

    <\/span>ADMIN rights to create local groups.<\/span><\/span><\/p>\n

   <\/span>.Example<\/span><\/span><\/p>\n

    <\/span>Add-LocalUserToLocalGroup.ps1 -computer MunichServer -user myUser -group mygroup<\/span><\/span><\/p>\n

    <\/span>Adds a local user called myUser on a computer named MunichServer to a local group called mygroup<\/span><\/span><\/p>\n

   <\/span>.Example<\/span><\/span><\/p>\n

    <\/span>Add-LocalUserToLocalGroup.ps1 -user myUser -group mygroup<\/span><\/span><\/p>\n

    <\/span>Adds a local user called myUser on local computer to a group called mygroup<\/span><\/span><\/p>\n

   <\/span>.Inputs<\/span><\/span><\/p>\n

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

   <\/span>.OutPuts<\/span><\/span><\/p>\n

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

   <\/span>.Notes<\/span><\/span><\/p>\n

    <\/span>NAME:  <\/span>Windows 7 Resource Kit<\/span><\/span><\/p>\n

    <\/span>AUTHOR: Ed Wilson<\/span><\/span><\/p>\n

    <\/span>LASTEDIT: 5\/20\/2009<\/span><\/span><\/p>\n

    <\/span>KEYWORDS: ADSI<\/span><\/span><\/p>\n

   <\/span>.Link<\/span><\/span><\/p>\n

     <\/span>Http:\/\/www.ScriptingGuys.com<\/span><\/span><\/p>\n

#Requires -Version 2.0<\/span><\/span><\/p>\n

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

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

For information about using help tags, see this Hey, Scripting Guy! Blog post<\/span><\/a>.  <\/span>When Get-Help<\/b> is used with the path to the script, the output shown in the following figure appears.<\/span><\/p>\n

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

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

<\/span>The New-Underline<\/b> function is used to underline output. It accepts pipelined input, and I often use it when displaying output. It is talked about in this Hey, Scripting Guy! Blog post<\/span><\/a>. The complete text of this function is seen here. The function contains its own help, and can easily be incorporated into a profile. <\/span><\/p>\n

function New-Underline<\/span><\/span><\/p>\n

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

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

.Synopsis<\/span><\/span><\/p>\n

 <\/span>Creates an underline the length of the input string<\/span><\/span><\/p>\n

.Example<\/span><\/span><\/p>\n

 <\/span>New-Underline -strIN “Hello world”<\/span><\/span><\/p>\n

.Example<\/span><\/span><\/p>\n

 <\/span>New-Underline -strIn “Morgen welt” -char “-” -sColor “blue” -uColor “yellow”<\/span><\/span><\/p>\n

.Example<\/span><\/span><\/p>\n

 <\/span>“this is a string” | New-Underline<\/span><\/span><\/p>\n

.Notes<\/span><\/span><\/p>\n

 <\/span>NAME:<\/span><\/span><\/p>\n

 <\/span>AUTHOR: Ed Wilson<\/span><\/span><\/p>\n

 <\/span>LASTEDIT: 5\/20\/2009<\/span><\/span><\/p>\n

 <\/span>KEYWORDS:<\/span><\/span><\/p>\n

.Link<\/span><\/span><\/p>\n

 <\/span>Http:\/\/www.ScriptingGuys.com<\/span><\/span><\/p>\n

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

[CmdletBinding()]<\/span><\/span><\/p>\n

param(<\/span><\/span><\/p>\n

      <\/span>[Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]<\/span><\/span><\/p>\n

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

      <\/span>$strIN,<\/span><\/span><\/p>\n

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

      <\/span>$char = “=”,<\/span><\/span><\/p>\n

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

      <\/span>$sColor = “Green”,<\/span><\/span><\/p>\n

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

      <\/span>$uColor = “darkGreen”,<\/span><\/span><\/p>\n

      <\/span>[switch]<\/span><\/span><\/p>\n

      <\/span>$pipe<\/span><\/span><\/p>\n

 <\/span>) #end param<\/span><\/span><\/p>\n

 <\/span>$strLine= $char * $strIn.length<\/span><\/span><\/p>\n

 <\/span>if(-not $pipe)<\/span><\/span><\/p>\n

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

   <\/span>Write-Host -ForegroundColor $sColor $strIN<\/span><\/span><\/p>\n

   <\/span>Write-Host -ForegroundColor $uColor $strLine<\/span><\/span><\/p>\n

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

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

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

  <\/span>$strIn<\/span><\/span><\/p>\n

  <\/span>$strLine<\/span><\/span><\/p>\n

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

} #end New-Underline function<\/span><\/span><\/p>\n

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

Because adding a user to a group is a privileged operation, the script requires Administrator rights. I wrote the Test-IsAdministrator<\/b> function to perform that check. This is another function I often use in my scripts, and it also makes a great candidate for a profile. Refer to this Hey Scripting Guy! Blog post<\/span><\/a> for information about using the Test-IsAdministrator<\/b> function.<\/span><\/p>\n

function Test-IsAdministrator<\/span><\/span><\/p>\n

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

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

    <\/span>.Synopsis<\/span><\/span><\/p>\n

        <\/span>Tests if the user is an administrator<\/span><\/span><\/p>\n

    <\/span>.Description<\/span><\/span><\/p>\n

        <\/span>Returns true if a user is an administrator, false if the user is not an administrator        <\/span><\/span><\/span><\/p>\n

    <\/span>.Example<\/span><\/span><\/p>\n

        <\/span>Test-IsAdministrator<\/span><\/span><\/p>\n

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

    <\/span>param() <\/span><\/span><\/p>\n

    <\/span>$currentUser = [Security.Principal.WindowsIdentity]::GetCurrent()<\/span><\/span><\/p>\n

    <\/span>(New-Object Security.Principal.WindowsPrincipal $currentUser).IsInRole([Security.Principal.WindowsBuiltinRole]::Administrator)<\/span><\/span><\/p>\n

} #end function Test-IsAdministrator<\/span><\/span><\/p>\n

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

The actual code that adds a user to a group is easy. I use the WinNT provider and connect to a specific group on a computer. I then call the add<\/b> method<\/span><\/span><\/a> and pass the user from the computer. The group and the user name are supplied via the command line when the script is called. <\/span><\/p>\n

Note:<\/span><\/b> WinNT, as used in the code below, is case sensitive. This is something that is unusual for Windows PowerShell because Windows PowerShell is normally case insensitive. The case sensitivity itself, however, for the WinNT provider name comes from ADSI and is not a result of Windows PowerShell itself. <\/b><\/span><\/p>\n

This code is seen here:<\/span><\/p>\n

$objOU = [ADSI]”WinNT:\/\/$computer\/$group,group”<\/span><\/span><\/p>\n

$objOU.add(“WinNT:\/\/$computer\/$user”)<\/span><\/span><\/p>\n

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

The script can be called in a couple of ways. Here are two examples:<\/span><\/p>\n

Add-LocalUserToLocalGroup.ps1 -computer MunichServer -user myUser -group mygroup<\/span><\/span><\/p>\n

Add-LocalUserToLocalGroup.ps1 -user myUser -group mygroup<\/span><\/span><\/p>\n

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

In addition, you could supply information via a text file and loop through the information in the file if you need to add multiple users and groups.<\/span><\/p>\n

EJ, that is all there is to using Windows PowerShell to add a local user to a local group. This also concludes local user week. Join me tomorrow as I open my virtual mail bag and answer a raft of miscellaneous questions.<\/span><\/p>\n

I invite you to follow me on Twitter<\/span><\/a> or Facebook<\/span><\/a>. If you have any questions, send email to me at scripter@microsoft.com<\/span><\/a> or post them on the Official Scripting Guys Forum<\/span><\/a>. See you tomorrow. Until then, peace.<\/span><\/p>\n

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

Ed Wilson, Microsoft Scripting Guy<\/span><\/b><\/p>\n","protected":false},"excerpt":{"rendered":"

  Summary: Microsoft Scripting Guy Ed Wilson shows how to add local users to local groups using Windows PowerShell.   Hey, Scripting Guy! I have enjoyed your posts this week. It is amazing how often I need to enable the Local Administrator account, or create a new local user or group. One thing you have […]<\/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":[197,23,24,3,198,45],"class_list":["post-16411","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-local-account-management","tag-local-accounts-and-windows-nt-4-0-accounts","tag-other-directory-services","tag-scripting-guy","tag-users","tag-windows-powershell"],"acf":[],"blog_post_summary":"

  Summary: Microsoft Scripting Guy Ed Wilson shows how to add local users to local groups using Windows PowerShell.   Hey, Scripting Guy! I have enjoyed your posts this week. It is amazing how often I need to enable the Local Administrator account, or create a new local user or group. One thing you have […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/16411","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=16411"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/16411\/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=16411"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=16411"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=16411"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}