PowerShell How-To

How To Reset an Azure VM Admin Password with PowerShell

Using Azure's "virtual machine agent," you can reset the local administrator password without even hitting the Windows OS itself. Here's how.

• By Adam Bertram
• 12/13/2017

When a Windows server is located on-premises and you forget the local administrator password, what do you do? You'll probably try to find a tool to hack into the system or, if you're lucky, log on to Windows with another account that is in the local administrator's group.

This works fine when you've got the virtual machine (VM) or physical server on-prem, but things work differently in the cloud.

Microsoft Azure provides Infrastructure as a Service (IaaS), which essentially uses the same technology as you might be using on-prem but has the "cloud layer" on top of it. This cloud layer allows management of VMs not by accessing the Windows OS directly, but by issuing commands through the Azure cloud, which then get passed on to the VM in question. One of the tasks where you can use the cloud layer over a traditional approach is resetting the local administrator password.

Azure VMs generally have a small piece of software installed on them called a VM agent. This small agent is installed on the underlying Windows OS and communicates with Azure to allow the user control over the OS without necessarily touching the OS itself. The VM agent is installed on all images provisioned from the Azure Marketplace, but if you've uploaded your own image, it can be installed manually.

As soon as the VM agent is installed on an Azure VM, you're able to manage the local administrator password without even hitting the Windows OS itself. One way to do this is through PowerShell. Using the Set-AzureRmVMAccessExtension cmdlet that's part of the AzureRM PowerShell modules, we can execute commands through an Azure API and get the job done. Doing this requires setting the password and then issuing a reboot of the Azure VM.

To reset a password, we first need to define the VM we're working with. To do this, we can use the Get-AzureRmVm cmdlet. I'll go ahead and assign variables to both the VM name and the resource group since we'll need to reference those later, as well.

$vmName = 'YOURVMNAMEHERE'
$resourceGroupName = 'YOURRGHERE'
$vm = Get-AzureRmVm -Name $vmName -ResourceGroupName $resourceGroupName

Next, we'll need some way to pass the username and password into the script. A great way to do that is through the Get-Credential cmdlet.

$credential = Get-Credential

Once the credential is saved, we can then execute the command to actually make the password change using the variables we set earlier. Notice we had to use the GetNetworkCredential() method on the pscredential object. This method will not work if the credential is retrieved from another computer or from another user account. This shouldn't be a problem, though, since you're likely to execute this in a single script.

$extensionParams = @{
    'VMName' = $vmName
    'Username' = $Credential.UserName
    'Password' = $Credential.GetNetworkCredential().Password
    'ResourceGroupName' = $resourceGroupName
    'Name' = 'AdminPasswordReset'
    'Location' = $vm.Location
}

$result = Set-AzureRmVMAccessExtension @extensionParams

Once this completed (hopefully successfully), the VM will need to be rebooted. We can do that by using the Restart-AzureRmVm cmdlet.

$vm | Restart-AzureRmVM

When the VM comes back up, the username will have the new password! This technique is useful if you're able to authenticate to your Azure subscription and may have forgotten a local password on a VM or as part of a large automation script, perhaps.

For an example on how to implement this code into a function, check out the Reset-AzureRmVmAdminPassword script. Although not required, it shows how this code could be built into a fully-contained function or a single script.