Extension VMAccess pour Windows

2025-05-05

L’extension VMAccess est utilisée pour gérer les utilisateurs administratifs, configurer RDP et vérifier ou réparer des disques sur des machines virtuelles Windows Azure. L’extension s’intègre aux modèles Azure Resource Manager. Vous pouvez aussi l’appeler en utilisant Azure CLI, Azure PowerShell, le portail Azure et l’API REST Machines virtuelles Azure.

Cet article explique comment exécuter l’extension VMAccess à partir d’Azure PowerShell et via un modèle Azure Resource Manager. Cet article fournit également des étapes de résolution des problèmes pour les systèmes Windows.

Remarque

Si vous utilisez l’extension VMAccess pour réinitialiser le mot de passe de votre machine virtuelle après avoir installé l’extension de connexion Microsoft Entra, réexécutez l’extension de connexion Microsoft Entra pour réactiver la connexion Microsoft Entra pour votre machine virtuelle.

Conditions préalables

Versions de Windows prises en charge

Version du système d'exploitation	x64	ARM64
Windows 10	Soutenu	Soutenu
Windows 11	Soutenu	Soutenu
Windows Server 2016	Soutenu	Soutenu
Windows Server 2016 Core	Soutenu	Soutenu
Windows Server 2019	Soutenu	Soutenu
Windows Server 2019 Core	Soutenu	Soutenu
Windows Server 2022	Soutenu	Soutenu
Windows Server 2022 Core	Soutenu	Soutenu
Windows Server 2025	Soutenu	Soutenu
Windows Server 2025 Core	Soutenu	Soutenu

Conseils

VMAccess est conçu pour récupérer l’accès à une machine virtuelle lorsque l’accès est perdu. En fonction de ce principe, il accorde des privilèges d’administrateur au compte spécifié dans le champ nom d’utilisateur. Si vous ne souhaitez pas qu’un utilisateur dispose d’autorisations d’administrateur, connectez-vous à la machine virtuelle et utilisez des outils intégrés (tels que net user et Local Users and Groups) pour gérer les privilèges utilisateur.
Une seule version de l’extension peut être appliquée à une machine virtuelle. Pour exécuter une deuxième action, mettez à jour l’extension existante avec une nouvelle configuration.
Lors de la mise à jour d’un utilisateur, VMAccess modifie les paramètres Bureau à distance pour autoriser la connexion.

Schéma d’extensions

La configuration de l’extension VMAccess inclut des paramètres pour le nom d’utilisateur, les mots de passe et la réinitialisation du mot de passe administrateur. Vous pouvez stocker ces informations dans des fichiers de configuration, les spécifier dans PowerShell ou les inclure dans un modèle Azure Resource Manager (ARM). Le schéma JSON suivant contient toutes les propriétés disponibles pour être utilisées dans les paramètres publics et protégés.

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "<name>",
  "apiVersion": "2023-09-01",
  "location": "<location>",
  "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
  ],
  "properties": {
    "publisher": "Microsoft.Compute",
    "type": "VMAccessAgent",
    "typeHandlerVersion": "2.4",
    "autoUpgradeMinorVersion": true,
    "settings": {},
    "protectedSettings": {
      "username": "<username>",
      "password": "<password>",
      "reset_password": true
    } 
  }
}

Valeurs de propriétés

Nom	Valeur/Exemple	Type de données
apiVersion	2023-09-01	date
éditeur	Microsoft.Compute	ficelle
type	VMAccessAgent	ficelle
typeHandlerVersion	2,4	Int

Valeurs de la propriété Settings

Nom	Type de données	Descriptif
nom d'utilisateur	ficelle	Nom de l’utilisateur à gérer (obligatoire pour toutes les actions sur un compte d’utilisateur).
mot de passe	ficelle	Mot de passe à définir pour le compte d’utilisateur.
réinitialiser_mot_de_passe	booléen	Indique si le mot de passe de l’utilisateur doit être réinitialisé ou non.

Déployer avec PowerShell

Vous pouvez utiliser PowerShell pour appliquer l’extension VMAccess à une machine virtuelle Windows. PowerShell suivant est un exemple de script pour réinitialiser le mot de passe administrateur :

$resourceGroup = "<ResourceGroupName>"
$vmName = "<VMName>"
$location = "<Location>"
$username = "<Username>"
$password = "<NewPassword>"

$settings = @{}
$protectedSettings = @{
    "username" = $username
    "password" = $password
    "reset_password" = $true
}

Set-AzVMExtension -ResourceGroupName $resourceGroup `
                    -VMName $vmName `
                    -Location $location `
                    -Name "VMAccessAgent" `
                    -Publisher "Microsoft.Compute" `
                    -ExtensionType "VMAccessAgent" `
                    -TypeHandlerVersion "2.4" `
                    -Settings $settings `
                    -ProtectedSettings $protectedSettings

Déploiement de modèle

Les extensions de machine virtuelle Azure peuvent être déployées avec des modèles Azure Resource Manager (ARM). Le schéma JSON détaillé dans la section précédente peut être utilisé dans un modèle ARM pour exécuter l’extension VMAccess pendant le déploiement du modèle. Vous trouverez un exemple de modèle qui inclut l’extension VMAccess sur GitHub.

La configuration JSON d’une extension de machine virtuelle doit être imbriquée dans le fragment de la ressource de machine virtuelle du modèle, plus précisément dans l’objet "resources": [] de la machine virtuelle et, dans le cas d’un groupe de machines virtuelles identiques, sous l’objet "virtualMachineProfile":"extensionProfile":{"extensions" :[].

Utiliser les commandes d'extension Azure PowerShell VM/VMSS pour Windows

Vous pouvez utiliser la commande Set-AzVMExtension pour exécuter l’extension VMAccess avec la configuration spécifiée pour une machine virtuelle Windows.

PowerShell suivant est un exemple utilisant la commande Set-AzVMExtension :

Set-AzVMExtension `
  -ResourceGroupName "myResourceGroup" `
  -VMName "myVM" `
  -Name "VMAccessAgent" `
  -Publisher "Microsoft.Compute" `
  -Type "VMAccessAgent" `
  -TypeHandlerVersion "2.0" `
  -Settings @{ "ResetPassword" = $true } `
  -ProtectedSettings @{ "Username" = "adminUser"; "Password" = "userPassword" }

Les paramètres -Settings et -ProtectedSettings acceptent également les chemins d’accès au fichier JSON. Par exemple, pour mettre à jour le mot de passe de l’administrateur local à l’aide d’un fichier JSON, créez un fichier nommé update_admin_password.json avec le contenu suivant. Remplacez les valeurs par vos propres informations :

{
  "Username": "adminUser",
  "Password": "userPassword"
}

Ensuite, exécutez l’extension avec le fichier JSON comme entrée :

Set-AzVMExtension `
  -ResourceGroupName "myResourceGroup" `
  -VMName "myVM" `
  -Name "VMAccessAgent" `
  -Publisher "Microsoft.Compute" `
  -Type "VMAccessAgent" `
  -TypeHandlerVersion "2.0" `
  -ProtectedSettings (Get-Content -Path "update_admin_password.json" -Raw | ConvertFrom-Json)

Déploiement Azure PowerShell pour Windows

Azure PowerShell peut être utilisé pour déployer l’extension VMAccess sur une machine virtuelle Windows existante ou un groupe de machines virtuelles identiques. Vous pouvez déployer l’extension sur une machine virtuelle en exécutant :

$username = "<username>"
$password = "<password>"
$settings = @{ "ResetPassword" = $true }
$protectedSettings = @{ "Username" = $username; "Password" = $password }
Set-AzVMExtension -ResourceGroupName "<resource-group>" `
    -VMName "<vm-name>" `
    -Location "<location>" `
    -Publisher "Microsoft.Compute" `
    -ExtensionType "VMAccessAgent" `
    -Name "VMAccessAgent" `
    -TypeHandlerVersion "2.0" `
    -Settings $settings `
    -ProtectedSettings $protectedSettings

Vous pouvez également fournir et modifier des paramètres d’extension en utilisant des chaînes :

$username = "<username>"
$password = "<password>"
$settingsString = '{"ResetPassword": true}';
$protectedSettingsString = '{"Username":"' + $username + '", "Password":"' + $password + '"}';
Set-AzVMExtension -ResourceGroupName "<resource-group>" `
    -VMName "<vm-name>" `
    -Location "<location>" `
    -Publisher "Microsoft.Compute" `
    -ExtensionType "VMAccessAgent" `
    -Name "VMAccessAgent" `
    -TypeHandlerVersion "2.0" `
    -SettingString $settingsString `
    -ProtectedSettingString $protectedSettingsString

Pour déployer sur un groupe de machines virtuelles identiques, exécutez la commande suivante :

$resourceGroupName = "<resource-group>"
$vmssName = "<vmss-name>"
$protectedSettings = @{
  "Username" = "adminUser"
  "Password" = "userPassword"
}
$publicSettings = @{
  "ResetPassword" = $true
}
$vmss = Get-AzVmss `
            -ResourceGroupName $resourceGroupName `
            -VMScaleSetName $vmssName
Add-AzVmssExtension -VirtualMachineScaleSet $vmss `
    -Name "VMAccessAgent" `
    -Publisher "Microsoft.Compute" `
    -Type "VMAccessAgent" `
    -TypeHandlerVersion "2.0" `
    -AutoUpgradeMinorVersion $true `
    -Setting $publicSettings `
    -ProtectedSetting $protectedSettings
Update-AzVmss `
    -ResourceGroupName $resourceGroupName `
    -Name $vmssName `
    -VirtualMachineScaleSet $vmss

Dépannage et support technique

Les journaux d’extension VMAccess existent localement sur la machine virtuelle et sont particulièrement utiles pour la résolution des problèmes.

Emplacement	Descriptif
`C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.VMAccessAgent\`	Contient les journaux de l’Agent Windows qui indiquent quand une mise à jour de l’extension s’est produite. Vérifiez ces logs afin de vous assurer que l’extension s’est correctement exécutée.
`C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.VMAccessAgent\<version>\`	L’extension VMAccess produit des journaux détaillés dans ce répertoire. Il inclut `CommandExecution.log`, qui enregistre chaque commande exécutée avec son résultat et `extension.log`, qui contient des journaux d’exécution individuels.
`C:\WindowsAzure\Logs\WaAppAgent\`	Contient les détails de configuration et les journaux binaires liés à l’extension VMAccess.

Vous pouvez également récupérer l’état d’exécution de l’extension VMAccess ainsi que d’autres extensions sur une machine virtuelle donnée en exécutant la commande suivante :

Vous pouvez récupérer l’état d’exécution des extensions de machine virtuelle sur une machine virtuelle donnée en exécutant la commande PowerShell suivante :

Get-AzVMExtension -ResourceGroupName "myResourceGroup" -VMName "myVM" | Format-Table

Messages d’erreur

Erreur	Descriptif
{"innererror » : {"internalErrorCode » : « CannotModifyExtensionsWhenVMNotRunning"}, « code » : « OperationNotAllowed »,"message » : « Impossible de modifier les extensions dans la machine virtuelle lorsque la machine virtuelle n’est pas en cours d’exécution."}	L’erreur indique que l’opération de modification des extensions dans la machine virtuelle n’est pas autorisée, car la machine virtuelle n’est pas en cours d’exécution. Vérifiez que la machine virtuelle est dans un état en cours d’exécution avant de tenter de modifier les extensions.
La machine virtuelle a signalé un échec lors du traitement de l’extension « enablevmAccess » (publisher « Microsoft.Compute » et tapez « VMAccessAgent »). Message d’erreur : « L’extension VMAccess ne prend pas en charge le contrôleur de domaine. » Pour plus d’informations sur la résolution des problèmes, consultez https://aka.ms/vmextensionwindowstroubleshoot .	L’erreur indique que l’extension de machine virtuelle « enablevmAccess » a échoué, car elle ne prend pas en charge le contrôleur de domaine. Vérifiez que la machine virtuelle n’est pas configurée en tant que contrôleur de domaine lors de l’utilisation de cette extension. Pour plus d’informations, consultez Réinitialiser les services Bureau à distance ou son mot de passe administrateur dans une machine virtuelle Windows.
La machine virtuelle « vmname » n’a pas signalé l’état de l’agent ou des extensions de machine virtuelle. Vérifiez que le système d’exploitation est opérationnel et sain, la machine virtuelle dispose d’un agent de machine virtuelle en cours d’exécution et qu’elle peut établir des connexions sortantes vers le stockage Azure. Reportez-vous aux https://aka.ms/vmextensionwindowstroubleshoot pour obtenir des informations supplémentaires sur le dépannage de l’agent VM.	Consultez la liste de contrôle de résolution des problèmes.
La machine virtuelle a signalé un échec lors du traitement de l’extension « enablevmAccess » (publisher « Microsoft.Compute » et tapez « VMAccessAgent »). Message d’erreur : « Impossible de mettre à jour les paramètres de connexion Bureau à distance pour le compte Administrateur. Erreur : System.Reflection.TargetInvocationException. L’exception a été levée par la cible d’un appel. >--- System.Runtime.InteropServices.COMException : le mot de passe ne répond pas aux exigences de stratégie de mot de passe. Vérifiez la longueur minimale du mot de passe, la complexité du mot de passe et les exigences d’historique des mots de passe. --- Fin de la trace d’exceptions internes --- sur System.DirectoryServices.DirectoryEntry.Invoke(String methodName, Object[] args) sur Microsoft.WindowsAzure.GuestAgent.Plugins.WindowsUser.SetPassword(SecureString password, Boolean expirePassword) sur Microsoft.WindowsAzure.GuestAgent.Plugins.RemoteAccessAccountManager.AddOrUpdateRemoteUserAccount(String userName, SecureString password, Boolean expirePassword) à l’adresse Microsoft.WindowsAzure.GuestAgent.Plugins.JsonExtensions.VMAccess.VMAccessExtension.OnEnable()'. Pour plus d’informations sur la résolution des problèmes, consultez https://aka.ms/vmextensionwindowstroubleshoot.	L’erreur indique que l’extension de machine virtuelle « enablevmAccess » n’a pas pu mettre à jour les paramètres de connexion Bureau à distance pour le compte Administrateur en raison d’une violation de stratégie de mot de passe. Vérifiez que le mot de passe répond aux exigences de stratégie de mot de passe Windows, notamment la longueur minimale, la complexité et l’historique. Pour plus d’informations, consultez Résoudre les problèmes liés aux extensions de machine virtuelle.
La machine virtuelle a signalé un échec lors du traitement de l’extension « enablevmAccess » (publisher « Microsoft.Compute » et tapez « VMAccessAgent »). Message d’erreur : « Le mot de passe du compte d’utilisateur administrateur ne peut pas être nul ou vide s’il a fourni le nom d’utilisateur. » Pour plus d’informations sur la résolution des problèmes, consultez https://aka.ms/vmextensionwindowstroubleshoot .	L’erreur indique que l’extension de machine virtuelle « enablevmAccess » a échoué, car le mot de passe du compte d’utilisateur administrateur n’a pas été fourni. Vérifiez qu’un mot de passe non null et non vide est spécifié pour le compte d’utilisateur administrateur pour résoudre ce problème.
L’approvisionnement de l’extension de machine virtuelle enablevmaccess a expiré. L’approvisionnement d’extension a pris trop de temps. L’extension n’a pas fait état d’un message.	Le message d’erreur indique que le provisionnement de l’extension de machine virtuelle « enablevmaccess » a expiré en raison d’un délai trop long. En outre, l’extension n’a pas fourni de message d’état pendant le processus. Pour résoudre ce problème, envisagez de vérifier les performances et les conditions réseau de la machine virtuelle, puis réessayez l’opération d’approvisionnement. Pour plus d’informations, consultez Résolution des problèmes d’échecs d’extension de machine virtuelle Windows Azure.
La machine virtuelle a signalé un échec lors du traitement de l’extension « enablevmAccess » (publisher « Microsoft.Compute » et tapez « VMAccessAgent »). Message d’erreur : « Impossible de mettre à jour les paramètres de connexion Bureau à distance pour le compte Administrateur. Erreur : System.Exception : Le compte d’utilisateur scsadmin existe déjà, mais ne peut pas être mis à jour, car il ne se trouve pas dans le groupe Administrateurs. sur Microsoft.WindowsAzure.GuestAgent.Plugins.RemoteAccessAccountManager.AddOrUpdateRemoteUserAccount(String userName, SecureString password, Boolean expirePassword) sur Microsoft.WindowsAzure.GuestAgent.Plugins.JsonExtensions.VMAccessExtension.OnEnable()'. Pour plus d’informations sur la résolution des problèmes, consultez https://aka.ms/vmextensionwindowstroubleshoot .	L’erreur indique que l’extension de machine virtuelle « enablevmAccess » a échoué, car le compte d’utilisateur « scsadmin » existe déjà, mais n’est pas dans le groupe Administrateurs. Vérifiez que le compte d’utilisateur est ajouté au groupe Administrateurs pour résoudre ce problème.
La machine virtuelle a signalé un échec lors du traitement de l’extension « enablevmaccess » (publisher « Microsoft.Compute » et tapez « VMAccessAgent »). Message d’erreur : « Impossible de mettre à jour les paramètres de connexion Bureau à distance pour le compte Administrateur. Erreur : System.Runtime.InteropServices.COMException (0x800708C5) : le mot de passe ne répond pas aux exigences de stratégie de mot de passe. Vérifiez la longueur minimale du mot de passe, la complexité du mot de passe et les exigences d’historique des mots de passe. sur System.DirectoryServices.DirectoryEntry.CommitChanges() sur Microsoft.WindowsAzure.GuestAgent.Plugins.WindowsUser.SetPassword(Mot de passe SecureString, Boolean expirePassword) sur Microsoft.WindowsAzure.GuestAgent.Plugins.WindowsUserManager.CreateUserInGroup(String userName, SecureString password, Boolean expirePassword, String[] groups) sur Microsoft.WindowsAzure.GuestAgent.Plugins.RemoteAccessAccountManager.AddOrUpdateRemoteUserAccount(String userName, SecureString password, Boolean expirePassword) sur Microsoft.WindowsAzure.GuestAgent.Plugins.JsonExtensions.VMAccess.VMAccessExtension.OnEnable()'. Pour plus d’informations sur la résolution des problèmes, consultez https://aka.ms/vmextensionwindowstroubleshoot .	Le message d’erreur indique que la machine virtuelle n’a pas pu traiter l’extension « enablevmaccess » en raison d’un problème lié à la mise à jour des paramètres de connexion Bureau à distance pour le compte Administrateur. L’erreur spécifique est liée au mot de passe qui ne répond pas aux exigences de stratégie, telles que la longueur minimale, la complexité et l’historique. Pour résoudre ce problème, vérifiez que le mot de passe est conforme aux normes de stratégie requises. Pour plus d’informations, consultez Résoudre les problèmes liés aux extensions de machine virtuelle.
{"innererror » : {"internalErrorCode » : « MultipleExtensionsPerHandlerNotAllowed"}, « code » : « BadRequest »,"message » : « Multiple VMExtensions par gestionnaire non pris en charge pour le type de système d’exploitation 'Windows'. VMExtension « enablevmaccess » avec le gestionnaire « Microsoft.Compute.VMAccessAgent » ajouté ou spécifié en entrée.}	Le message d’erreur indique que plusieurs extensions de machine virtuelle par gestionnaire ne sont pas prises en charge pour le type de système d’exploitation « Windows ». L’extension « enablevmaccess » avec le gestionnaire « Microsoft.Compute.VMAccessAgent » a déjà été ajoutée ou spécifiée dans l’entrée. Pour résoudre ce problème, vérifiez qu’une seule extension par gestionnaire est configurée pour la machine virtuelle. Supprimez manuellement l'extension et réessayez l'opération `Remove-AzVMExtension -ResourceGroupName "ResourceGroup11" -Name "ExtensionName" -VMName "VirtualMachineName"`

Pour obtenir plus d’aide, vous pouvez contacter les experts Azure sur le Support de la communauté Azure. Vous pouvez également signaler un incident au support Azure. Accédez à Support Azure, puis sélectionnez Obtenir de l’aide. Pour plus d’informations sur le support Azure, consultez les plans de support Azure.