Unix Server Tech Knowledge Base

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Add/Update User with PowerShell ======

===== Discussion =====
We needed a way to automatically update a local user on a bunch of systems which were not on an Active Directory configuration. We had remote access, and the ability to run PowerShell scripts as an administrator.

It should not be interactive at all.

===== Generate password hash =====

The first step is to generate a password hash (what Windows calls a SecureString) so we are not passing around passwords in plaintext. 

<code powershell genPass.ps1>
$password = ConvertTo-SecureString -String "password" -AsPlainText -Force
$plain = convertFrom-securestring -securestring $password
$plain
</code>

The final line will give a very long hex number, which is the hash of the password ("password" in first line).

===== Download and Modify script =====

Download the following Powershell file and edit in your favorite text editor. Paste the output of the previouss code into this script where the script has "Very Long Hex String from above" (keep the quotes around it).

Adjust the following to your needs
  * $password: Replace //Very Long Hex String from above// with the hash from the previous step
  * $user: This will be the username you log in as
  * $group: The group to add the user to
  * $fullname: The display name of the user (optional)
  * $description: A description of the user (optional)

<code powershell adduser.ps1>
# script to add a local user with admin privileges on a Windows machine
# Generate the password hash with the following three lines (after changing "password"
#
# $password = ConvertTo-SecureString -String "password" -AsPlainText -Force
# $plain = convertFrom-securestring -securestring $password
# $plain
#
# paste the output into -String below
# adjust the user and which group to add them to.
# if user already exists, will ignore (with message.
# password is updated no matter what
# if user is already in group, will ignore (with message)

$password = ConvertTo-SecureString -String "Very Long Hex String from above"
$user = 'test'
$group = "Administrators"
$fullname = "Test Account"
$description = 'Test Account'

# Check if user exists
if (-not (Get-LocalUser -Name $user -ErrorAction SilentlyContinue)) {
    try {
        New-LocalUser -Name $user  -Password $password -FullName $fullname -Description $description -PasswordNeverExpires
        Write-Host "User '$user' created."
    } catch {
        Write-Warning "Failed to create user '$user': $_"
    }
} else {
    Write-Host "User '$user' already exists."
}

# Set (or reset) the password
try {
    Set-LocalUser -Name $user -Password $password
    Write-Host "Password updated for user '$user'."
} catch {
    Write-Warning "Failed to update password: $_"
}

# Add to local group if not already a member
try {
    if (-not (Get-LocalGroupMember -Group $group -Member $user -ErrorAction SilentlyContinue)) {
        Add-LocalGroupMember -Group $group -Member $user
        Write-Host "User '$user' added to group '$group'."
    } else {
        Write-Host "User '$user' is already in group '$group'."
    }
} catch {
    Write-Warning "Failed to add user '$user' to group '$group': $_"
}
</code>

===== Run the code =====

You can run the code by opening PowerShell as Administrator, then copying/pasting directly into the window. This avoids the need to specifically allow power shell script execution. The same code can be used on multiple machines.

===== Enhancements =====

Note, if the password hash is to be transported over public media (e-mail, ftp, chat), you may want add the -Key or -SecureKey parameters to the encoding (ConvertTo-SecureString) and decoding (ConvertTo-SecureString) commands.

-SecureKey appearantly uses single pad encryption to further secure the key. See https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/convertto-securestring for details.

===== Links =====
  * https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.localaccounts/set-localuser?view=powershell-5.1
  * https://www.danielengberg.com/powershell-script-add-user-to-local-admin-group/
  * https://stackoverflow.com/questions/49595003/checking-if-a-local-user-account-group-exists-or-not-with-powershell
  * https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/convertto-securestring?view=powershell-7.5
  * https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.localaccounts/get-localuser?view=powershell-5.1
  * https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/convertto-securestring

Also, thanks to DavidN for tightening it up a little for me.