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.x :

• Installe des clés privées dans KeyGuard en cas d’exécution sur Windows Server 2025 et KeyGuard est opérationnel.
• 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 et les certificats auto-signés (où l’objet et l’émetteur sont identiques) ne sont pas soumis à cette vérification.
• Chaîne tous les certificats sur l’ordinateur qui proviennent du même objet de certificat Key Vault vers la dernière version de ce certificat.
• Prend en charge une redéfinition facultative de l’authentification pour chaque certificat, ce qui permet à chaque certificat observé de s’authentifier auprès de Key Vault avec une identité managée différente de celle utilisée par défaut par l’extension. Pour plus d’informations, consultez schéma d’extension.

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’extension interroge 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 s’il installe tous les certificats configurés.
• Vous ne pouvez plus configurer une version spécifique d’un certificat.
• L’extension stocke désormais toujours des clés privées à l’aide de 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.

• Attribuez le rôle d’utilisateur Key Vault Secrets au niveau de l’étendue Key Vault à l’identité managée pour la machine virtuelle ou Groupes de machines virtuelles identiques Azure. Ce rôle récupère la partie secrète 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

• Configurez Virtual Machine Scale Sets avec la configuration suivante identity :

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

• Configurez l’extension de machine virtuelle Key Vault avec la configuration suivante authenticationSettings :

  "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 des informations publiques.

• Les URL de certificat observées doivent utiliser le formulaire https://myVaultName.vault.azure.net/secrets/myCertName.

  Ce format est requis, car le chemin /secrets renvoie le certificat complet, y compris la clé privée, mais le chemin /certificates ne le renvoie pas. Pour plus d’informations sur les certificats, consultez Vue d’ensemble des clés, des secrets et des certificats Azure Key Vault. Vous ne pouvez pas spécifier une version spécifique du certificat.

• L’hôte d’URL doit être un hôte Azure Key Vault reconnu.

• 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 Key Vault 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"]>,
                    "authenticationOverride": <Optional. Overrides authenticationSettings for this certificate only, so it can authenticate with a different managed identity. Example: {"msiClientId": "11112222-bbbb-3333-cccc-4444dddd5555"}>
                },
                {
                    "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

Déployez Azure extensions de machine virtuelle à l’aide de modèles Azure Resource Manager (ARM). Les modèles sont idéaux lorsque vous déployez une ou plusieurs machines virtuelles qui nécessitent une actualisation post-déploiement des certificats. Vous pouvez déployer l’extension sur des machines virtuelles individuelles ou des instances 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 Key Vault 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 groupes identiques dans Azure. Azure met automatiquement l’extension à jour lorsque vous définissez sur autoUpgradeMinorVersion les propriétés enableAutomaticUpgrade et true dans les exemples précédents.

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 Virtual Machine Scale Sets.

Déploiement d’Azure PowerShell

Déployez l’extension de machine virtuelle Azure Key Vault à l’aide de 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 déployer l’extension de machine virtuelle Key Vault à l’aide de 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

Déployez l’extension de machine virtuelle Azure Key Vault à l’aide de la 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 déployer l’extension de machine virtuelle Key Vault à l’aide de la 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>"

Résoudre les problèmes

Utilisez ces 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, l’extension enregistre les clés privées pour tous les certificats à l’aide de 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’elle installe un certificat renouvelé pour le même objet de certificat Key Vault qu’un certificat existant. 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. Lorsque l’extension télécharge un certificat à partir de Key Vault, il :

1. Installe tous les certificats intermédiaires et de fin de chaîne, peu importe le nombre de certificats intermédiaires présents. L’extension n’installe pas les certificats racines, car elle n’est pas autorisée à les installer. Vérifiez que le certificat racine est approuvé sur le système.
   • Installe les certificats finaux dans le magasin de certificats spécifié (certificateStoreName) et dans l’emplacement spécifié (certificateStoreLocation).
   • Installe des certificats CA intermédiaires dans le magasin 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 du accounts paramètre spécifié dans la configuration.
4. Définit la CERT_RENEWAL propriété afin que les liaisons de certificat dans les applications telles que IIS soient automatiquement mises à jour lorsque les certificats sont renouvelés. Un certificat est chaîné à la version la plus récente qui provient du même objet de certificat Key Vault, identifié par l'URL de base secrète Key Vault du certificat. Les certificats qui correspondent à différents objets de certificat Key Vault ne sont jamais liés les uns aux autres.

Magasins de certificats par défaut

Par défaut, l’extension installe des certificats dans les emplacements suivants :

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

Contrôle d’accès au certificat

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"]

Cette configuration 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 du certificat

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

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

Gestion du cycle de vie des certificats

Pour les applications telles que IIS qui prennent en charge les notifications de cycle de vie des services de certificats, l’extension de machine virtuelle Key Vault déclenche l’événement 1001 dans le journal des événements Windows lorsqu’il installe un certificat renouvelé pour le même objet de certificat Key Vault qu’un certificat existant (liaison du nouveau certificat à son prédécesseur). IIS s’abonne à cet événement pour rebiner automatiquement le certificat renouvelé sans interrompre le 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

Microsoft fournit uniquement la prise en charge de la version majeure 3.0 et ultérieure de l’extension de machine virtuelle Key Vault. Si vous utilisez la version 1.0, effectuez une mise à niveau vers la dernière version avant de demander la prise en charge.

Utilisez ces autres options pour 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.