SALES: 1-800-867-1380

VMAccess Extension

Updated: January 7, 2015

The VMAccess extension enables you to reset Remote Desktop Access or Secure Shell (SSH) settings on a Virtual Machine and to reset the password for the account that has administrator or sudo authority.

To add this extension, the Azure VM Agent must be installed on the Virtual Machine. For more information about installing the VM Agent, see Azure VM Extensions and Features.

If you know the name of the built-in administrator account, you can specify the new password for that account. If you do not know the name of the account, you can use the VMAccess extension to change the name and the password of the account.

You can use an Azure PowerShell cmdlet or Service Management REST APIs to add the VMAccess extension.

Follow these steps to add the VMAccess extension to a virtual machine, which resets the Remote Desktop Access settings and the password for the specified administrator account.

For instructions on using VMAccess on Linux VMs, see Using VMAccess Extension to Reset Login Credentials for Linux VM

  1. Specify the Virtual Machine to which you want to add the VMAccess extension.

    PS C:\> $VM1 = Get-AzureVM -ServiceName "ServiceName" -Name "VMName"
  2. Add the VMAccess extension to the Virtual Machine.

    PS C:\> Set-AzureVMaccessExtension -VM $VM1 –UserName "AdminAccountName" –Password "NewPassword" –ReferenceName "MyVMAccessAgent" | Update-AzureVM
ReferenceName is a label that you specify to identify the added extension. After this value is set, all updates to the extension must refer to the label that was initially provided.

You can also use the VMAccess extension to reset the Remote Desktop Access settings without resetting a password. To do this, add the extension without providing the –UserName and –Password parameters.

The following code example represents a C# console application that calls the Update Role operation. The example has been modified to include the ResourceExtensionReference element, which defines the name of the extension, the identifier of the publisher who created the extension, and the version of the extension. You can find this information by using the List Resource Extensions operation.

To run this example, replace the values of the following variables:


Variable Value


Provide a thumbprint of a management certificate that has been uploaded to authorize operations to perform in Azure. For more information, see Create and Upload a Management Certificate for Windows Azure.


Provide the subscription identifier that is needed to find the appropriate cloud service. To find the subscription identifier, click Settings in the Azure Management Portal.


Provide the name of the existing cloud service that contains the Virtual Machine. You can use List Cloud Services to find the names of existing services.


Provide the name of the deployment.


Provide the name of the Virtual Machine.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Xml.Linq;
using System.Xml;
using System.Security.Cryptography.X509Certificates;
using System.Net;
using System.IO;

namespace UpdateRole
  class Program
    private static XNamespace wa = "";
    private const string Thumbprint = "<thumbprint-of-management-certificate>";
    private const string SubscriptionId = "<identifier-of-subscription>";
    private const string Version = "2013-11-01";
    private const string ServiceName = "<name-of-existing-service>";
    private const string DeploymentName = "<name-of-new-deployment>";
    private const string RoleName = "<name-of-virtual-machine>";

    // Gets or sets the certificate that matches the Thumbprint value.
    private static X509Certificate2 Certificate { get; set; }

    static void Main(string[] args)
      Certificate = GetStoreCertificate(Thumbprint);

      // Create the uri for the request
      string uriFormat = "" +    
      Uri uri = new Uri(String.Format(uriFormat, SubscriptionId, 
        ServiceName, DeploymentName, RoleName));

       byte[] bytes = System.Text.Encoding.UTF8.GetBytes(
       string VMAgentPublicConfig = Convert.ToBase64String(bytes);
       bytes = System.Text.Encoding.UTF8.GetBytes(
       string VMAgentPrivateConfig = Convert.ToBase64String(bytes);
      // Create the request to update the Virtual Machine
      XNamespace xsi = "";
      XDocument requestBody = new XDocument(
        new XDeclaration("1.0", "UTF-8", "no"),
         new XElement(wa + "PersistentVMRole", 
           new XElement(wa + "ConfigurationSets",
             new XElement(wa + "ConfigurationSet",
               new XElement(wa + "ConfigurationSetType", "NetworkConfiguration"),
               new XElement(wa + "InputEndpoints",
                 new XElement(wa + "InputEndpoint",
                   new XElement(wa + "LocalPort", "3389"),
                   new XElement(wa + "Name", "Remote Desktop"),
                   new XElement(wa + "Port", "56202"),
                   new XElement(wa + "Protocol", "TCP"))))),                
          new XElement(wa + "ResourceExtensionReferences",
            new XElement(wa + "ResourceExtensionReference",
              new XElement(wa + "ReferenceName", "MyVMAccessAgent"),
              new XElement(wa + "Publisher", "Microsoft.Compute"),
              new XElement(wa + "Name", "VMAccessAgent"),
              new XElement(wa + "Version", "1.0"),
                new XElement(wa + "ResourceExtensionParameterValues",
                  new XElement(wa + "ResourceExtensionParameterValue",
                    new XElement(wa + "Key", "VMAccessAgentPublicConfigParameter"),
                    new XElement(wa + "Value", VMAgentPublicConfig),
                    new XElement(wa + "Type", "Public")),
                  new XElement(wa + "ResourceExtensionParameterValue",
                    new XElement(wa + "Key", "VMAccessAgentPrivateConfigParameter"),
                    new XElement(wa + "Value", VMAgentPrivateConfig),
                    new XElement(wa + "Type", "Private")))))));

      // Submit the request and get the response
      XDocument responseBody;
      HttpWebResponse response = InvokeRequest(uri, "PUT", requestBody, out responseBody);

      HttpStatusCode statusCode = response.StatusCode;
      Console.WriteLine("The status of the operation: {0}", statusCode.ToString());
      if (responseBody != null)
      Console.Write("Press any key to continue:");

    // Gets the certificate matching the thumbprint from the local store.
    // Throws an ArgumentException if a matching certificate is not found.
    private static X509Certificate2 GetStoreCertificate(string thumbprint)
      List<StoreLocation> locations = new List<StoreLocation> 

      foreach (var location in locations)
        X509Store store = new X509Store("My", location);
          store.Open(OpenFlags.ReadOnly | OpenFlags.OpenExistingOnly);
          X509Certificate2Collection certificates = store.Certificates.Find(
            X509FindType.FindByThumbprint, thumbprint, false);
          if (certificates.Count == 1)
            return certificates[0];

      throw new ArgumentException(string.Format(
        "A Certificate with Thumbprint '{0}' could not be located.", thumbprint));

    // Add the request headers and get the response from the request
    private static HttpWebResponse InvokeRequest(
      Uri uri,
      string method,
      XDocument requestBody,
      out XDocument responseBody)
      HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(uri);
      request.Method = method;
      request.Headers.Add("x-ms-version", Version);
      request.ContentType = "application/xml";

      if (requestBody != null)
        using (Stream requestStream = request.GetRequestStream())
          using (StreamWriter streamWriter = new StreamWriter(
            requestStream, System.Text.UTF8Encoding.UTF8))
            requestBody.Save(streamWriter, SaveOptions.DisableFormatting);
      responseBody = null;
      HttpWebResponse response;
        response = (HttpWebResponse)request.GetResponse();
      catch (WebException ex)
        response = (HttpWebResponse)ex.Response;

      XmlReaderSettings settings = new XmlReaderSettings();
      settings.DtdProcessing = DtdProcessing.Ignore;

      if (response.ContentLength > 0)
        using (XmlReader reader = XmlReader.Create(response.GetResponseStream(), settings))
            responseBody = XDocument.Load(reader);
            responseBody = null;

      return response;

You can use the same method to update the extension that you used to add the extension. For more information, see Add the extension.

After you perform the operation to add the extension, you can log in to the instance using the account name and password that was provided to the VMAccess extension. For more information, see How to Log on to a Virtual Machine Running Windows Server.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
© 2015 Microsoft