Enable RDP or Reset Password with the VM Agent

[UPDATE 07/17/2014]  Make sure you are using version 0.8.5 or later of Azure PowerShell as there was an issue with earlier versions where you could not interact with the extensions when the VM was in an availability set. For more information, see Unable to add VM agent extension to VM.

The Set-AzureVMAccessExtension cmdlet allows you to reset the built-in administrator password of your Azure VM, as well as enable RDP if it was inadvertently disabled. This functionality was first made available in March 2014 in the 0.7.4 release of Azure PowerShell.

The password reset works on domain controllers, member servers, as well as standalone workgroup VMs.

This functionality relies on the VM agent already being installed in the VM. All VMs created from an image (either gallery or custom) after the beginning of March 2014 would have the VM agent installed by default. You can manually install the agent using the available Windows Installer MSI package: 

https://go.microsoft.com/fwlink/?LinkID=394789&clcid=0x409

Currently the portal only exposes the option to not have the VM agent installed (by unchecking Install VM Agent when creating the VM). To use specific VM agent extensions you need to use Azure PowerShell or the REST APIs.

  1. First install Azure PowerShell - How to install and configure Windows Azure PowerShell

    If you already had it installed, make sure you are on 0.8.5 or later by looking at the Version from the Get-Module azure command or look for Windows Azure PowerShell - July 2014 or later in the Programs and Features control panel.
     

  2. Check if the agent is installed on the VM. This command will return True if the agent is installed:

    (Get-AzureVM -ServiceName clmar4ws12r2b -Name clmar4ws12r2b).VM.ProvisionGuestAgent

    True
      

  3. To enable RDP and the necessary Windows firewall rule:

    Get-AzureVM -ServiceName clmar4ws12r2b -Name clmar4ws12r2b | Set-AzureVMAccessExtension | Update-AzureVM

    OperationDescription OperationId OperationStatus
    -------------------- ----------- ---------------
    Update-AzureVM 3918b55c-da4b-76ee-b9b1-8b0c249f0fee Succeeded
     

  4. To instead do a password reset of the built-in administrator account:

    Get-AzureVM -ServiceName clmar4ws12r2b -Name clmar4ws12r2b | Set-AzureVMAccessExtension -UserName craig -Password $password | Update-AzureVM

    You may need to restart the VM for the change to take effect.

    Note that you will see Succeeded even if the password reset fails because the password did not meet the password complexity requirements configured within the VM. So if you reset the password, restart the VM, but are not able to logon with the new password, make sure you specify a password that meets the complexity requirements of the VM.

The extension runs VMAccessAgent.ps1 from C:\Packages\Plugins\Microsoft.Compute.VMAccessAgent\<version>\ folder on the VM to enable RDP and set the firewall rule, and also to reset the admin password if you specify a username and password.

It will always enable RDP and enable the firewall rule, both when running Set-AzureVMAccessExtension with no parameters, but also when specifying a username and password.

To enable the firewall rule it runs:

netsh advfirewall firewall set rule group="remote desktop" new enable=Yes

To enable RDP it runs:

set-ItemProperty -Path 'HKLM:\System\CurrentControlSet\Control\Terminal Server' -name "fDenyTSConnections" -Value 0

If you do specify a username and password, it still enables RDP and the firewall rule, but additionally sets the built-in admin account to that new password (if the username matches the current built-in admin account name) or renames the built-in admin account to the specified username is different that the current built-in admin account name.

If the built-in admin account is disabled, it enables it.

If the built-in admin account gets renamed because you specified a different username, it issues a log off.

The operations are logged to C:\windowsazure\logs\Plugins\Microsoft.Compute.VMAccessAgent\<version>\VMAccessAgent.log.

When enabling RDP, the VMAccessAgent.log will show:

2014-03-06 04:52:23 [INFO]: Username/Password not provided. Will only fix the remote desktop connection.
2014-03-06 04:52:23 [INFO]: Enabling the remote desktop firewall rules. Output from netsh command:

Updated 3 rule(s).
Ok.

2014-03-06 04:52:24 [INFO]: Setting registry key to allow remote desktop connections to this machine.

When you reset the password, it will show:

2014-03-06 12:51:04 [INFO]: Reading the credentials.
2014-03-06 12:51:04 [INFO]: Older config does not exist.
2014-03-06 12:51:05 [INFO]: Name of builtin admin is 'craig'. Only changing the password.

If the password reset failed due to password complexity requirements, you'll see:

2014-03-06 12:17:54 [ERROR]: Resetting the password failed with error: {0} Exception calling "Invoke" with "2" argument(s): "The password does not meet the password policy requirements. Check the minimum password length, password complexity and password history requirements.