Working with the LocalAccounts Cmdlets in PowerShell v5
- By Adam Bertram
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 220.127.116.11 Microsoft.PowerShell.LocalAccounts
Cmdlet Disable-LocalUser 18.104.22.168 Microsoft.PowerShell.LocalAccounts
Cmdlet Enable-LocalUser 22.214.171.124 Microsoft.PowerShell.LocalAccounts
Cmdlet Get-LocalGroup 126.96.36.199 Microsoft.PowerShell.LocalAccounts
Cmdlet Get-LocalGroupMember 188.8.131.52 Microsoft.PowerShell.LocalAccounts
Cmdlet Get-LocalUser 184.108.40.206 Microsoft.PowerShell.LocalAccounts
Cmdlet New-LocalGroup 220.127.116.11 Microsoft.PowerShell.LocalAccounts
Cmdlet New-LocalUser 18.104.22.168 Microsoft.PowerShell.LocalAccounts
Cmdlet Remove-LocalGroup 22.214.171.124 Microsoft.PowerShell.LocalAccounts
Cmdlet Remove-LocalGroupMember 126.96.36.199 Microsoft.PowerShell.LocalAccounts
Cmdlet Remove-LocalUser 188.8.131.52 Microsoft.PowerShell.LocalAccounts
Cmdlet Rename-LocalGroup 184.108.40.206 Microsoft.PowerShell.LocalAccounts
Cmdlet Rename-LocalUser 220.127.116.11 Microsoft.PowerShell.LocalAccounts
Cmdlet Set-LocalGroup 18.104.22.168 Microsoft.PowerShell.LocalAccounts
Cmdlet Set-LocalUser 22.214.171.124 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
---- ------- -----------
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'
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.
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.