PowerShell How-To

Working with the LocalAccounts Cmdlets in PowerShell v5

One of the features of PowerShell that left many people wondering why it wasn't included earlier was local account management. Every Windows system has local accounts and being able to add, remove and modify these local accounts is a routine task across system administrators. Before PowerShell v5, the community was forced to step in and create their own ways to manage these accounts. Boe Prox even wrote about how to handle user accounts here on McpMag way back in 2015. If you look at how to manage local accounts using Boe's method, the average system administrator's eyes glaze over.

Finally, native local account management is here with the introduction of the Microsoft.PowerShell.LocalAccounts PowerShell module that comes with PowerShell v5.

The LocalAccounts module has all the cmdlets you need to manage local accounts.

PS> Get-Command -Module  Microsoft.PowerShell.LocalAccounts

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Cmdlet          Add-LocalGroupMember                               1.0.0.0    Microsoft.PowerShell.LocalAccounts
Cmdlet          Disable-LocalUser                                  1.0.0.0    Microsoft.PowerShell.LocalAccounts
Cmdlet          Enable-LocalUser                                   1.0.0.0    Microsoft.PowerShell.LocalAccounts
Cmdlet          Get-LocalGroup                                     1.0.0.0    Microsoft.PowerShell.LocalAccounts
Cmdlet          Get-LocalGroupMember                               1.0.0.0    Microsoft.PowerShell.LocalAccounts
Cmdlet          Get-LocalUser                                      1.0.0.0    Microsoft.PowerShell.LocalAccounts
Cmdlet          New-LocalGroup                                     1.0.0.0    Microsoft.PowerShell.LocalAccounts
Cmdlet          New-LocalUser                                      1.0.0.0    Microsoft.PowerShell.LocalAccounts
Cmdlet          Remove-LocalGroup                                  1.0.0.0    Microsoft.PowerShell.LocalAccounts
Cmdlet          Remove-LocalGroupMember                            1.0.0.0    Microsoft.PowerShell.LocalAccounts
Cmdlet          Remove-LocalUser                                   1.0.0.0    Microsoft.PowerShell.LocalAccounts
Cmdlet          Rename-LocalGroup                                  1.0.0.0    Microsoft.PowerShell.LocalAccounts
Cmdlet          Rename-LocalUser                                   1.0.0.0    Microsoft.PowerShell.LocalAccounts
Cmdlet          Set-LocalGroup                                     1.0.0.0    Microsoft.PowerShell.LocalAccounts
Cmdlet          Set-LocalUser                                      1.0.0.0    Microsoft.PowerShell.LocalAccounts

Let's see how we can use these cmdlets over the lifetime of a local user account. To get started, we'll need to create a user from scratch. Creating a new user is done by using the New-LocalUser cmdlet. The New-LocalUser cmdlet has two mandatory parameters; Name and Password. Both parameters are self-explanatory, but you won't be able to just type in the password as you might expect. A password is sensitive and, as such, the New-LocalUser cmdlet requires a secure string. We'll have to convert our plain text password to a secure string before New-LocalUser will accept it. This conversion is doing using the ConvertTo-SecureString cmdlet.

PS> New-LocalUser -Name foo  -Password 'test123'
New-LocalUser : Cannot bind parameter 'Password'. Cannot convert the "test123" value of type "System.String" to type "System.Security.SecureString".
At line:1 char:35
+ New-LocalUser -Name foo -Password 'test123'
+                                   ~~~~~~~~~
+ CategoryInfo          : InvalidArgument: (:) [New-LocalUser], ParameterBindingException
+ FullyQualifiedErrorId : CannotConvertArgumentNoMessage,Microsoft.PowerShell.Commands.NewLocalUserCommand

PS> New-LocalUser -Name foo -Password (ConvertTo-SecureString -String 'test123' -AsPlainText -Force)

Name Enabled Description
---- ------- -----------
foo  True

When creating the user, I forgot to add the full name. Let's modify our new user to add this attribute. Modifying attributes are done with the Set-LocalUser cmdlet. We can modify attributes of an existing user either by using the Name property, or we can also grab the current user using the Get-LocalUser cmdlet and passing that result directly to Set-LocalUser for the same effect.

## No pipeline
Set-LocalUser -Name foo -FullName 'My Foo User'

## Pipeline
Get-Localuser -Name 'foo' | Set-Localuser -FullName 'My Foo User'

I now need the user to the administrators group, so I'll use the Add-LocalGroupMember cmdlet by grabbing the user account again with Get-LocalUser and piping it to Add-LocalGroupMember.

Get-Localuser -Name 'foo' |  Add-LocalGroupMember -Group 'Administrators'

I now don't need the user account we created in the first place. It needs to be removed. No problem! I have the Remove-LocalUser cmdlet for that. Using the same methodology as before, we will find the user with Get-LocalUser and pipe it to Remove-LocalUser to get it removed for good. And, for good measure, I'll be sure it's gone by calling Get-LocalUser again afterward.

PS> Get-Localuser -Name 'foo' |  Remove-LocalUser
PS> Get-Localuser -Name 'foo'
Get-Localuser : User foo was not found.
At line:1 char:1
+ Get-Localuser -Name 'foo'
+ ~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo          : ObjectNotFound: (foo:String) [Get-LocalUser], UserNotFoundException
+ FullyQualifiedErrorId : UserNotFound,Microsoft.PowerShell.Commands.GetLocalUserCommand

You can tell that the LocalAccount cmdlets are much easier to use than rolling your own code to perform the same task. Even though Microsoft was late in delivering these cmdlets, I'm glad they did! These cmdlets finally will allow us scripters to get back to solving more pressing problems rather than trying to figure out how to manage local accounts.

About the Author

Adam Bertram is an independent consultant, technical writer, trainer and presenter. Adam specializes in consulting and evangelizing all things IT automation mainly focused around Windows PowerShell. Adam is a Microsoft Windows PowerShell MVP, 2015 powershell.org PowerShell hero and has numerous Microsoft IT pro certifications. He is a writer, trainer and presenter and authors IT pro course content for Pluralsight. He is also a regular contributor to numerous print and online publications and presents at various user groups and conferences. You can find Adam at adamtheautomator.com or on Twitter at @adbertram.

comments powered by Disqus

SharePoint Watch

Sign up for our newsletter.

I agree to this site's Privacy Policy.