Extension de machine virtuelle Key Vault pour Windows

L’extension de machine virtuelle Azure Key Vault assure l’actualisation automatique des certificats stockés dans un coffre de clés Azure. L’extension surveille une liste de certificats observés stockés dans des coffres de clés. Lors de la détection d’une modification, l’extension récupère et installe les certificats correspondants. Cet article présente les plateformes, configurations et options de déploiement qui sont prises en charge pour l’extension de machine virtuelle Key Vault pour Windows.

Systèmes d’exploitation

L’extension de machine virtuelle Key Vault prend en charge Windows Server 2022 et Windows Server 2025, sur AMD64 et ARM64. Sur Windows Server 2025, les clés privées sont enregistrées dans KeyGuard.

Certificats pris en charge

L’extension de machine virtuelle Key Vault prend en charge les types de contenu de certificat suivants :

• PKCS#12
• PEM

Fonctionnalités

Extension de machine virtuelle Key Vault pour Windows version 4.0 :

• Installe des clés privées dans KeyGuard en cas d’exécution sur Windows Server 2025.
• Installe les deux versions les plus récentes de chaque certificat.
• Effectue la validation de la chaîne de certificats avant d’installer un certificat qui contient l’utilisation étendue de la clé (EKU) de l’authentification du serveur TLS, y compris les certificats qui contiennent d’autres EKU à côté de celui-ci (par exemple, l’authentification du client). Les erreurs de validation de chaîne entraînent un échec d’approvisionnement pour l’extension. Les certificats sans la référence EKU d’authentification du serveur ne sont pas soumis à cette vérification.

Mise à niveau à partir de la version 3.0

Si vous effectuez une mise à jour à partir de la version 3.0, les fonctionnalités suivantes sont modifiées ou supprimées :

• pollingIntervalInS est maintenant limité à entre 5 et 60 minutes. Par défaut, l’interrogation est effectuée une fois par heure.
• linkOnRenewal est supprimé. La liaison se produit toujours.
• keyExportable est supprimé. Les clés privées ne sont plus exportables.
• requireInitialSync est supprimé. L’extension signale uniquement la réussite si tous les certificats configurés sont installés.
• La configuration d’une version spécifique d’un certificat n’est plus possible.
• Les clés privées sont désormais toujours stockées via l’API de chiffrement : CNG (Next Generation) au lieu de CAPI.

Prérequis

Passez en revue les conditions préalables suivantes pour l’utilisation de l’extension de machine virtuelle Key Vault pour Windows :

• Une instance Key Vault Azure avec un certificat. Pour plus d’informations, consultez Créer un coffre de clé avec le portail Azure.

• Une machine virtuelle avec une identité managée affectée.

• Le rôle Utilisateur de secrets Key Vault doit être attribué au niveau de l’étendue Key Vault pour les machines virtuelles et l’identité managée Groupes de machines virtuelles identiques Azure. Ce rôle récupère la partie d’un secret d’un certificat. Pour plus d’informations, consultez les articles suivants :

  • Authentification dans Azure Key Vault
  • Utilisation des autorisations de secret, de clé et de certificat de RBAC Azure avec Azure Key Vault
  • Attribution de rôle d’étendue de coffre de clés

• Les groupes de machines virtuelles identiques doivent avoir la configuration identity suivante :

  "identity": {
     "type": "UserAssigned",
     "userAssignedIdentities": {
        "[parameters('userAssignedIdentityResourceId')]": {}
     }
  }
  

• L’extension de machine virtuelle Key Vault doit avoir la configuration authenticationSettings suivante :

  "authenticationSettings": {
      "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]",
      "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]"
  }
  

Schéma d’extensions

L’extrait JSON suivant illustre le schéma de l’extension de machine virtuelle Key Vault. Avant d’examiner les options d’implémentation de schéma, passez en revue les notes importantes suivantes.

• L’extension ne nécessite pas de paramètre protégés. Tous les paramètres sont considérés comme des informations publiques.

• Vos URL de certificats observés doivent être de la forme https://myVaultName.vault.azure.net/secrets/myCertName.

  Cette forme est préférée car le chemin /secrets retourne le certificat complet, y compris la clé privée, contrairement au chemin /certificates. Pour plus d’informations sur les certificats, consultez Vue d’ensemble des clés, des secrets et des certificats Azure Key Vault.

• La propriété authenticationSettings est requise pour les machines virtuelles avec n’importe quelles identités affectées par l’utilisateur.

  Elle spécifie l'identité à utiliser pour l'authentification auprès de Key Vault. Définissez cette propriété avec une identité affectée par le système pour éviter les problèmes liés à une extension de machine virtuelle avec plusieurs identités.

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KVVMExtensionForWindows",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForWindows",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "observedCertificates": <An array of KeyVault URIs that represent monitored certificates, including certificate store location and ACL permission to certificate private key. Example: 
             [
                {
                    "url": <A Key Vault URI to the secret portion of the certificate. Example: "https://myvault.vault.azure.net/secrets/mycertificate1">,
                    "certificateStoreName": <The certificate store name. Example: "MY">,
                    "certificateStoreLocation": <The certificate store location, which currently works locally only. Example: "LocalMachine">,
                    "accounts": <Optional. An array of preferred accounts with read access to certificate private keys. Administrators and SYSTEM get Full Control by default. Example: ["Network Service", "Local Service"]>
                },
                {
                    "url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
                    "certificateStoreName": <Example: "MY">,
                    "certificateStoreLocation": <Example: "CurrentUser">,
                    "accounts": <Example: ["Local Service"]>
                },
                {
                    "url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate3">,
                    "certificateStoreName": <Example: "TrustedPeople">,
                    "certificateStoreLocation": <Example: "LocalMachine">
                }
             ]>
         },
         "authenticationSettings": {
             "msiEndpoint":  <Required when the msiClientId property is used. Specifies the MSI endpoint. Example for most Azure VMs: "http://169.254.169.254/metadata/identity/oauth2/token">,
             "msiClientId":  <Required when the VM has any user assigned identities. Specifies the MSI identity. Example:  "00001111-aaaa-2222-bbbb-3333cccc4444">
         }
      }
   }
}

Valeurs de propriétés

Le schéma JSON comprend les propriétés suivantes.

Déploiement de modèle

Les extensions de machine virtuelle Azure peuvent être déployées avec des modèles Azure Resource Manager (ARM). Les modèles sont idéaux lorsque vous déployez une ou plusieurs machines virtuelles nécessitant une actualisation de certificats après le déploiement. Vous pouvez déployer l’extension sur des machines virtuelles individuelles ou dans des instances de Virtual Machine Scale Sets. La configuration et le schéma sont communs aux deux types de modèle.

La configuration JSON d’une extension de coffre de clés est imbriquée dans le modèle de machine virtuelle ou de Virtual Machine Scale Sets. Pour une extension de ressource de machine virtuelle, la configuration est imbriquée sous l’objet "resources": [] de machine virtuelle. Pour une extension d’instance de Virtual Machine Scale Sets, la configuration est imbriquée sous l’objet "virtualMachineProfile":"extensionProfile":{"extensions" :[].

Les extraits de code JSON suivants fournissent des exemples de paramètres pour un déploiement de modèle ARM de l’extension de machine virtuelle Key Vault.

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KeyVaultForWindows",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForWindows",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "observedCertificates": <An array of KeyVault URIs that represent monitored certificates, including certificate store location and ACL permission to certificate private key. Example:
             [
                {
                    "url": <A Key Vault URI to the secret portion of the certificate. Example: "https://myvault.vault.azure.net/secrets/mycertificate1">,
                    "certificateStoreName": <The certificate store name. Example: "MY">,
                    "certificateStoreLocation": <The certificate store location, which currently works locally only. Example: "LocalMachine">,
                    "accounts": <Optional. An array of preferred accounts with read access to certificate private keys. Administrators and SYSTEM get Full Control by default. Example: ["Network Service", "Local Service"]>
                },
                {
                    "url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
                    "certificateStoreName": <Example: "MY">,
                    "certificateStoreLocation": <Example: "CurrentUser">,
                    "accounts": <Example: ["Local Service"]>
                },
                {
                    "url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate3">,
                    "certificateStoreName": <Example: "TrustedPeople">,
                    "certificateStoreLocation": <Example: "LocalMachine">
                }
             ]>           
         },
         "authenticationSettings": {
            "msiEndpoint":  <Required when the msiClientId property is used. Specifies the MSI endpoint. Example for most Azure VMs: "http://169.254.169.254/metadata/identity/oauth2/token">,
            "msiClientId":  <Required when the VM has any user assigned identities. Specifies the MSI identity. Example: "00001111-aaaa-2222-bbbb-3333cccc4444">
         }
      }
   }
}

Mise à niveau automatique de l’extension

L’extension de machine virtuelle Key Vault prend en charge la mise à niveau automatique des extensions pour les machines virtuelles et les ensembles de mise à l'échelle dans Azure. L’extension est mise à jour automatiquement lorsque les propriétés autoUpgradeMinorVersion et enableAutomaticUpgrade des exemples précédents sont définies sur true.

Tri des dépendances d’extension

L’extension de machine virtuelle Key Vault prend en charge l’ordre des dépendances d’extension. L’extension signale un démarrage réussi après le téléchargement et l’installation de tous les certificats.

Si vous utilisez d’autres extensions qui nécessitent l’installation de certificats avant de commencer, vous pouvez utiliser l’ordre des dépendances d’extension pour déclarer une dépendance sur l’extension de machine virtuelle Key Vault.

Au démarrage, l’extension de machine virtuelle Key Vault tente de télécharger et d’installer des certificats jusqu’à 25 fois avec des périodes d’interruption croissantes, pendant lesquelles elle reste dans un état Transitioning. Si les nouvelles tentatives sont épuisées, l’extension signale un état d’erreur . Une fois tous les certificats installés, l’extension de machine virtuelle Key Vault signale un démarrage réussi.

Pour plus d’informations sur la configuration des dépendances entre les extensions, consultez Provisionnement d’extensions de séquence dans les Virtual Machine Scale Sets.

Déploiement d’Azure PowerShell

L’extension de machine virtuelle Azure Key Vault peut être déployée avec Azure PowerShell. Enregistrez les paramètres d’extension de machine virtuelle Key Vault dans un fichier JSON (settings.json).

Les extraits de code JSON suivants fournissent des exemples de paramètres pour le déploiement de l’extension de machine virtuelle Key Vault avec PowerShell.

{   
   "secretsManagementSettings": {
   "observedCertificates":
   [
      {
          "url": "https://<examplekv>.vault.azure.net/secrets/certificate1",
          "certificateStoreName": "MY",
          "certificateStoreLocation": "LocalMachine",
          "accounts": [
             "Network Service"
          ]
      },
      {
          "url": "https://<examplekv>.vault.azure.net/secrets/certificate2",
          "certificateStoreName": "MY",
          "certificateStoreLocation": "LocalMachine",
          "accounts": [
             "Network Service",
             "Local Service"
          ]
      }
   ]},
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity/oauth2/token",
      "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }      
}

Déployer sur une machine virtuelle

# Build settings
$settings = (get-content -raw ".\settings.json")
$extName =  "KeyVaultForWindows"
$extPublisher = "Microsoft.Azure.KeyVault"
$extType = "KeyVaultForWindows"
 
# Start the deployment
Set-AzVmExtension -TypeHandlerVersion "4.0" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings

Déployer sur un Virtual Machine Scale Sets instance

# Build settings
$settings = ".\settings.json"
$extName = "KeyVaultForWindows"
$extPublisher = "Microsoft.Azure.KeyVault"
$extType = "KeyVaultForWindows"
  
# Add extension to Virtual Machine Scale Sets
$vmss = Get-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName>
Add-AzVmssExtension -VirtualMachineScaleSet $vmss  -Name $extName -Publisher $extPublisher -Type $extType -TypeHandlerVersion "4.0" -Setting $settings

# Start the deployment
Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss 

Déploiement de l’interface de ligne de commande Azure

L’extension de machine virtuelle Azure Key Vault peut être déployée à l’aide d’Azure CLI. Enregistrez les paramètres d’extension de machine virtuelle Key Vault dans un fichier JSON (settings.json).

Les extraits de code JSON suivants fournissent des exemples de paramètres pour le déploiement de l’extension de machine virtuelle Key Vault avec Azure CLI.

   {   
        "secretsManagementSettings": {
          "observedCertificates": [
            {
                "url": "https://<examplekv>.vault.azure.net/secrets/certificate1",
                "certificateStoreName": "MY",
                "certificateStoreLocation": "LocalMachine",
                "accounts": [
                    "Network Service"
                ]
            },
            {
                "url": "https://<examplekv>.vault.azure.net/secrets/certificate2",
                "certificateStoreName": "MY",
                "certificateStoreLocation": "LocalMachine",                
                "accounts": [
                    "Network Service",
                    "Local Service"
                ]
            }
        ]
        },
          "authenticationSettings": {
          "msiEndpoint":  "http://169.254.169.254/metadata/identity/oauth2/token",
          "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
        }      
     }

Déployer sur une machine virtuelle

# Start the deployment
az vm extension set --name "KeyVaultForWindows" `
 --publisher Microsoft.Azure.KeyVault `
 --resource-group "<resourcegroup>" `
 --vm-name "<vmName>" `
 --settings "@settings.json" `
 --version "4.0"

Déployer sur un Virtual Machine Scale Sets instance

# Start the deployment
az vmss extension set --name "KeyVaultForWindows" `
 --publisher Microsoft.Azure.KeyVault `
 --resource-group "<resourcegroup>" `
 --vmss-name "<vmssName>" `
 --settings "@settings.json" `
 --version "4.0"

az vm extension delete --name "KeyVaultForWindows" --resource-group "<resourcegroup>" --vm-name "<vmName>"

Problèmes de dépannage

Voici quelques suggestions pour résoudre les problèmes de déploiement.

Questions fréquentes

Existe-t-il une limite au nombre de certificats observés ?

Non. L’extension de machine virtuelle Key Vault ne limite pas le nombre de certificats observés (observedCertificates).

Quelle est l’autorisation par défaut lorsqu’aucun compte n’est spécifié ?

Par défaut, les administrateurs et SYSTEM reçoivent le contrôle total.

Comment déterminer si une clé de certificat est CAPI1 ou CNG ?

À compter de Key Vault extension de machine virtuelle 4.0, les clés privées pour tous les certificats sont enregistrées via CNG.

L’extension prend-elle en charge le rétablissement automatique de la liaison de certificat ?

Oui, l’extension de machine virtuelle Azure Key Vault prend en charge le rétablissement automatique de la liaison de certificat. L’extension de machine virtuelle Key Vault prend en charge la liaison S-channel lors du renouvellement de certificat.

Pour IIS, vous pouvez configurer le rétablissement automatique de liaison en activant le rétablissement automatique de liaison des renouvellements de certificat dans IIS. L’extension de machine virtuelle Azure Key Vault génère des notifications de cycle de vie des certificats lorsqu’un certificat avec un SAN correspondant est installé. IIS utilise cet évènement pour rétablir automatiquement la liaison du certificat. Pour plus d’informations, consultez Reliaison de certificat dans IIS.

Afficher l’état de l’extension

Vérifiez l’état du déploiement de votre extension dans le portail Azure ou en utilisant PowerShell ou Azure CLI.

Pour voir l’état du déploiement des extensions pour une machine virtuelle donnée, exécutez les commandes suivantes.

• Azure PowerShell :

  Get-AzVMExtension -ResourceGroupName <myResourceGroup> -VMName <myVM> -Name <myExtensionName>
  

• L’interface de ligne de commande Azure CLI :

  az vm get-instance-view --resource-group <myResourceGroup> --name <myVM> --query "instanceView.extensions"
  

Passer en revue les journaux et la configuration

Les journaux d’extension Key Vault machine virtuelle existent uniquement localement sur la machine virtuelle. Passez en revue les détails du journal pour vous aider à résoudre les problèmes.

Installation du certificat sur Windows

L’extension de machine virtuelle Key Vault pour Windows installe des certificats dans le magasin de certificats Windows. Lorsqu’un certificat est téléchargé à partir de Key Vault, l’extension :

1. Installe tous les certificats intermédiaires et de fin de chaîne, peu importe le nombre de certificats intermédiaires présents. Les certificats racines ne sont pas installés, car l’extension n’est pas autorisée à effectuer l’installation racine. Il incombe au propriétaire du service d'assurer que le certificat racine est approuvé sur le système concerné.
   • Les certificats de nœud terminal sont installés dans le magasin de certificats (certificateStoreName) et à l’emplacement (certificateStoreLocation) spécifiés
   • Les certificats d’autorité de certification intermédiaire sont installés dans le magasin d’autorités de certification intermédiaires
2. Place les certificats dans le magasin de certificats spécifié (certificateStoreName) et l’emplacement (certificateStoreLocation)
3. Applique les autorisations appropriées à la clé privée en fonction de la configuration spécifiée.
4. Définit la CERT_RENEWAL propriété pour garantir que les liaisons de certificat dans les applications comme IIS sont automatiquement mises à jour lorsque les certificats sont renouvelés.

Magasins de certificats par défaut

Si ce n’est pas le cas, les certificats sont installés dans les emplacements suivants par défaut :

• Nom du magasin : MY (Personnel)
• Emplacement du magasin : LocalMachine

Contrôle d’accès aux certificats

Par défaut, les administrateurs et SYSTEM reçoivent des autorisations contrôle total sur les certificats installés. Vous pouvez personnaliser l’accès à l’aide du accounts tableau dans la configuration du certificat :

"accounts": ["Network Service", "Local Service"]

Cela accorde l’accès en lecture aux comptes spécifiés, ce qui permet aux applications s’exécutant sous ces identités d’utiliser les certificats.

Renouvellement de certificat

Lorsque les certificats sont renouvelés dans Key Vault, l’extension est automatiquement :

1. Télécharge la nouvelle version du certificat.
2. L’installe dans le magasin de certificats configuré.
3. Gère les liaisons existantes via la CERT_RENEWAL propriété.

Gestion du cycle de vie des certificats

Pour les applications comme IIS qui prennent en charge les notifications de cycle de vie des services de certificats, l’extension de machine virtuelle Key Vault déclenche Event 1001 dans le journal des événements Windows lorsqu’un certificat avec un autre nom d’objet (SAN) correspondant est installé. IIS s’abonne à cet événement pour rebiner automatiquement le certificat renouvelé sans interruption de service. D’autres applications et équipes peuvent également écouter l’événement 1001 pour agir sur les renouvellements de certificats si nécessaire. Pour plus d’informations, consultez Notifications de cycle de vie des services de certificats.

Obtenir de l’aide

Voici quelques autres options pour vous aider à résoudre les problèmes de déploiement :

• Pour obtenir de l’aide, contactez les experts Azure dans Microsoft Q& A.

• Si ne trouvez pas de réponse sur le site, vous pouvez publier une question pour que Microsoft ou d’autres membres de la communauté puissent vous aider.

• Vous pouvez également contacter le Support Microsoft. Pour plus d’informations sur l’utilisation de support Azure, consultez How to create an support Azure request.