PowerShell How-To

Working with the LocalAccounts Cmdlets in PowerShell v5

• By Adam Bertram
• 06/29/2017

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.