Use a Free PowerShell Module to Work with Local Accounts

Use a Free PowerShell Module to Work with Local Accounts

  • Comments 5
  • Likes

Summary: Learn how to use a free Windows PowerShell module to simplify working with local users and groups.
 

Weekend Scripter

Microsoft Scripting Guy Ed Wilson here. Well it is officially the Fourth of July weekend in Charlotte, North Carolina. (For those around the globe, the United States celebrates its independence on July 4 each year.) One problem with the celebrations is that one never knows when a town will be celebrating. It might be obvious that people will celebrate the Fourth of July on July 4, but that is making things way too simple. This is especially true when it falls on a Monday, or some other weekday. Fireworks are expensive these days, and it seems that towns want to get as much “bang for the buck” as they can, and so often they will host the festivities on the nearest Saturday, which is the case around here. An advantage is that often one can travel to several other towns’ celebrations and actually to go to three or more Fourth of July celebrations. The Scripting Wife and I are not quite that energetic, and while we enjoy fireworks, we manage to see them more by accident than by design.

On Thursday, I wrote an article about using parameter sets to simplify coding requirements. At that time, I released my Local User Management module to the Scripting Guys Script Repository,  and I used that module as an example in my article. On Friday, I talked about some of the design considerations surrounding naming conventions for Windows PowerShell functions. Once again, I used the Local User Management module as the basis of the discussion. Today, I want to show you how to use the module to simplify management tasks surrounding working with local user accounts.

In addition, I repeat my solicitation for comments on the module. Shoot me an email at scripter@microsoft.com with ideas for additional functions or ideas for improvement. Tell me how you want to use the module and I will see what I can do. I know there will be a version 2; there may also be a version 3--and perhaps even more versions.

After copying the Local User Management module from the Scripting Guys repository, the first thing to do is to save it as LocalUserModule.psm1. Now, where you save the module can be a bit of an issue. If you put it in the normal user location, $env:userprofile\Documents\WindowsPowerShell\Modules, and the logged-on user does not have administrator rights, the user will not be able to use any of the advanced functions because of lack of rights. On the other hand, if you use runas to start Windows PowerShell with an account that does have administrator rights, that user’s $env:userprofile\Documents\WindowsPowerShell\Modules location is different than the low rights user account.

On the other hand, if you put the Local User Management module in $PSHOME\modules, it will require administrator rights to perform the “installation” because administrator rights are required to mess around in the System32 folder. Of course, you can bypass both of these locations and copy the module anywhere you wish, but if you do that, it will not be listed when use the Get-Module –listavailable command. In the end, the best location for the module depends on how you anticipate using the module. If your account has administrator rights, and you will be running it from your own machine, the decision is easy: put it in your $env:userprofile\Documents\WindowsPowerShell\Modules location. If you want the module to be available to many different administrators of the machine, put it in the $PSHOME\modules location. It can even be part of your machine build process. If you anticipate using the module in an ad hoc fashion on random machines, you may decide to store it on a centralized network share. If you do this, you will need to remember to start Windows PowerShell with the bypass option to avoid errors when loading the module. The command to do this is shown here:

powershell -executionpolicy bypass

As seen in the following figure, I use the Run dialog box from the Start menu to launch Windows PowerShell in bypass mode.

Image of using Run to launch Windows PowerShell in bypass mode

Whenever I work with modules, there are three commands I use in succession. The first lists the available modules, the second command loads the module, and finally I determine what commands are exported by the module. The three commands, and their associated output on my computer appear here.

PS C:\> Get-Module -ListAvailable

 

ModuleType          Name                                  ExportedCommands

-----------------          --------                               ----------------------------

Script                      ConfigureDesktop               {}

Script                      LocalUserModule                {}

Script                      PAMADSNAPSHOT               {}

Script                       PAMDisks                            {}

Script                       PAMEnv                                {}

Script                       PAMLOAD                            {}

Script                       PAMMath                              {}

Script                       PAMRestorePoint                {}

Script                        PAMShares                         {}

Script                        PAMStability                        {}

Script                         PAMSysInfo                        {}

Script                         PinnedApplications           {}

Script                         PinnedApplicationsModule {}

Manifest                    Pscx                                      {}

Script                         Windows7Library               {}

Manifest                    ActiveDirectory                     {}

Manifest                     AppLocker                           {}

Manifest                     BitsTransfer                        {}

Manifest                     FailoverClusters                {}

Manifest                     GroupPolicy                         {}

Manifest                     NetworkLoadBalancingCl...   {}

Manifest                      PSDiagnostics                   {}

Manifest                      TroubleshootingPack        {} 

 

PS C:\> Import-Module local*

PS C:\> Get-Command -Module local*

 

CommandType     Name                                                  Definition

---------------------     ---------                                              ----------

Function                  New-LocalGroup                                ...

Function                  New-LocalUser                                   ...

Function                  Remove-LocalGroup                           ...

Function                  Remove-LocalUser                              ...

Function                  Set-LocalGroup                                    ...

Function                  Set-LocalUser                                       ...

Function                  Set-LocalUserPassword                       ...

Function                  Test-IsAdministrator                              ...

 

To create a new local user, a new local group, and add the local user to the local group, I use the following commands:

New-LocalUser -userName TESTUSER -password P@ssword1

New-LocalGroup -GroupName testgroup

Set-LocalGroup -userName testuser -GroupName testgroup –add

If I need to remove a local user from a local group, I once again use the Set-Localgroup function:

Set-LocalGroup -userName testuser -GroupName testgroup –remove

If I need to change a local user password, I use the Set-LocalUserPassword function. This will change local administrator passwords and service account passwords. The command and syntax are shown here:

Set-LocalUserPassword -userName testuser -password MyNewPassw@rd!

If I need to delete a local group, I use the Remove-LocalGroup function:

Remove-LocalGroup -GroupName testgroup

I can also delete local users by using the Remove-LocalUser command:

Remove-LocalUser testuser

If I need to create three users, I can do this from the Windows PowerShell console as shown here (the % character is an alias for the ForEach-Object Windows PowerShell cmdlet):

"testuser1","testuser2","testuser3" | % {New-LocalUser -userName $_ -password P@ssword1}

As shown in the following figure, the command created the three new test users.

Image of three new test users that were created

To create three groups, I can use the following syntax:

"testgroup", "testgroup2", "testgroup3" | % {New-LocalGroup $_}

To delete the three test groups, change New to Remove as shown here:

"testgroup", "testgroup2", "testgroup3" | % {Remove-LocalGroup $_}

I can also delete my three users by pipelining the array of user names:

"testuser1","testuser2","testuser3" | % {remove-LocalUser $_}

 

Well, that is enough for today. The Scripting Wife is standing at the door to my office with her arms folded and tapping her foot. Strangely enough she smells like a coconut. I imagine that means we are heading outside somewhere. It is the weekend after all.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

 

Ed Wilson, Microsoft Scripting Guy

 

 

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • Hello Ed,

    hope you had a nice weekend with the ScriptingWife! ( still wondering why she smelled like a coconut :-)

    Apart from the wonderful scripts the decision where to store new modules is indeed more

    complicated than I thought ...

    Especially the need for admin rights seems to be something to consider.

    One thing that may help is setting the environment variable "PSModulePath" to a location that is appropriate! I'd prefer to store my modules on a network drive below a "modules" folder and set PSModulePath in each profile.

    Adding locations to this path variable may be a way out!

    Klaus

  • Klaus,

    Most sunscreen lotion smells like coconuts. I had already applied the sun protection lotion and was waiting on Ed to be ready to go outside. Have a good day.

  • Hi Klaus-

    You are right, the need for admin rights is something to consider, and it does make things a bit more complicated. Personally, I do not like to use the PSModulePath variable very much because it is an array ... and I do not know which path is the system path and which is the one in the profile ... Of course I can check, but if I am going to all that trouble I may as well use my own variable. In fact, I like to create a variable for my own module path. I keep that variable in my profile. Here are some Hey Scripting Guy articles I wrote about the profile blogs.technet.com/.../profiles

  • Great module here. Got a whole bunch of Citrix XenApp servers with those infamous Anon accounts. Tried remoting with the Remove-LocalUser while looping thru a list of servers and looping thru a list of user accounts, but kept on getting a user not found. Any ideas? Tks, Bernardo

  • Hi, I have imported this module to $env:userprofile\Documents\WindowsPowerShell\Modules location however using Get-Module -ListAvailable command doesn't display this module as existing. Can you explain me how to deal with it? Note: I'm using Windows server 2012