Working with the LocalAccounts Cmdlets in PowerShell v5 -- Microsoft Certified Professional Magazine Online (2024)

PowerShell How-To

Working with the LocalAccounts Cmdlets in PowerShell v5

  • By Adam Bertram
  • 06/29/2017

Working with the LocalAccounts Cmdlets in PowerShell v5 -- Microsoft Certified Professional Magazine Online (1)

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 a 20-year veteran of IT. He's an automation engineer, blogger, consultant, freelance writer, Pluralsight course author and content marketing advisor to multiple technology companies. Adam also founded the popular TechSnips e-learning platform. He mainly focuses on DevOps, system management and automation technologies, as well as various cloud platforms mostly in the Microsoft space. He is a Microsoft Cloud and Datacenter Management MVP who absorbs knowledge from the IT field and explains it in an easy-to-understand fashion. Catch up on Adam's articles at adamtheautomator.com,connect on LinkedInor follow him on Twitter at@adbertramor the TechSnips Twitter account @techsnips_io.


Working with the LocalAccounts Cmdlets in PowerShell v5 -- Microsoft Certified Professional Magazine Online (2024)

References

Top Articles
Latest Posts
Article information

Author: Maia Crooks Jr

Last Updated:

Views: 5933

Rating: 4.2 / 5 (43 voted)

Reviews: 82% of readers found this page helpful

Author information

Name: Maia Crooks Jr

Birthday: 1997-09-21

Address: 93119 Joseph Street, Peggyfurt, NC 11582

Phone: +2983088926881

Job: Principal Design Liaison

Hobby: Web surfing, Skiing, role-playing games, Sketching, Polo, Sewing, Genealogy

Introduction: My name is Maia Crooks Jr, I am a homely, joyous, shiny, successful, hilarious, thoughtful, joyous person who loves writing and wants to share my knowledge and understanding with you.