Extension de machine virtuelle Key Vault pour Windows

  • Article

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 les versions ci-dessous de Windows :

  • Windows Server 2022
  • Windows Server 2019
  • Windows Server 2016
  • Windows Server 2012

L’extension de machine virtuelle Key Vault est également prise en charge sur une machine virtuelle locale personnalisée. La machine virtuelle doit être chargée et convertie en image spécialisée pour être utilisée dans Azure avec l’installation minimale Windows Server 2019.

Certificats pris en charge

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

  • PKCS#12
  • PEM

Notes

L’extension de machine virtuelle Key Vault télécharge tous les certificats dans le magasin de certificats Windows ou l’emplacement fourni par la propriété certificateStoreLocation dans les paramètres de l’extension de machine virtuelle.

Mises à jour dans la version 3.0+

La version 3.0 de l’extension de machine virtuelle Key Vault pour Windows ajoute la prise en charge des fonctionnalités suivantes :

  • Ajouter des autorisations ACL aux certificats téléchargés
  • Configuration du magasin de certificats par certificat
  • Exporter des clés privées
  • Prise en charge de la reliaison de certificats IIS

Prérequis

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

Notes

L’ancien modèle d’autorisation de stratégie d’accès peut également être utilisé pour fournir l’accès aux machines virtuelles et aux Virtual Machine Scale Sets. Cette méthode nécessite une stratégie avec des autorisations d’obtention et de liste sur les secrets. Pour plus d’informations, consultez Attribuer une stratégie d’accès Key Vault.

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": "2022-08-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForWindows",
      "typeHandlerVersion": "3.0",
      "autoUpgradeMinorVersion": true,
      "settings": {
         "secretsManagementSettings": {
             "pollingIntervalInS": <A string that specifies the polling interval in seconds. Example: "3600">,
             "linkOnRenewal": <Windows only. Ensures s-channel binding when the certificate renews without necessitating redeployment. Example: true>,
             "requireInitialSync": <Initial synchronization of certificates. Example: true>,
             "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">,
                    "keyExportable": <Optional. Lets the private key be exportable. Example: "false">,
                    "accounts": <Example: ["Local Service"]>
                }
             ]>
         },
         "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:  "c7373ae5-91c2-4165-8ab6-7381d6e75619">
         }
      }
   }
}

Valeurs de propriétés

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

Nom Valeur/Exemple Type de données
apiVersion 2022-08-01 Date
publisher Microsoft.Azure.KeyVault string
type KeyVaultForWindows string
typeHandlerVersion "3.0" string
pollingIntervalInS "3600" string
linkOnRenewal (facultatif) true boolean
requireInitialSync (facultatif) false boolean
observedCertificates [{...}, {...}] tableau de chaînes
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate" string
observedCertificates/certificateStoreName MY string
observedCertificates/certificateStoreLocation LocalMachine ou CurrentUser (respect de la casse) string
observedCertificates/keyExportable (facultatif) false boolean
observedCertificates/accounts (facultatif) ["Network Service", "Local Service"] tableau de chaînes
msiEndpoint "http://169.254.169.254/metadata/identity/oauth2/token" string
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string

Déploiement de modèle

Les extensions de machines virtuelles Azure peuvent être déployées avec des modèles Azure Resource Manager. 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": "2022-08-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForWindows",
      "typeHandlerVersion": "3.0",
      "autoUpgradeMinorVersion": true,
      "settings": {
         "secretsManagementSettings": {
             "pollingIntervalInS": <A string that specifies the polling interval in seconds. Example: "3600">,
             "linkOnRenewal": <Windows only. Ensures s-channel binding when the certificate renews without necessitating redeployment. Example: true>,
             "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">,
                    "keyExportable": <Optional. Lets the private key be exportable. Example: "false">,
                    "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: "c7373ae5-91c2-4165-8ab6-7381d6e75619">
         }
      }
   }
}

Tri des dépendances d’extension

Vous pouvez activer l’extension de machine virtuelle Key Vault pour prendre en charge l’ordre des dépendances d’extension. Par défaut, l’extension de machine virtuelle Key Vault signale un démarrage réussi dès le début de l’interrogation. Toutefois, vous pouvez configurer l’extension pour signaler un démarrage réussi uniquement après que l’extension a téléchargé et installé tous les certificats.

Si vous utilisez d’autres extensions qui nécessitent l’installation de tous les certificats avant leur démarrage, vous pouvez activer l’ordre des dépendances d’extension dans l’extension de machine virtuelle Key Vault. Cette fonctionnalité permet à d’autres extensions de déclarer une dépendance sur l’extension de machine virtuelle Key Vault.

Vous pouvez utiliser cette fonctionnalité pour empêcher le démarrage d’autres extensions jusqu’à ce que tous les certificats dépendants soient installés. Lorsque la fonctionnalité est activée, l’extension de machine virtuelle Key Vault tente de télécharger et d’installer indéfiniment les certificats et reste dans un état de transition, jusqu’à ce que tous les certificats soient correctement installés. Une fois tous les certificats présents, l’extension de machine virtuelle Key Vault signale un démarrage réussi.

Pour activer la fonctionnalité de classement des dépendances d’extension dans l’extension de machine virtuelle Key Vault, définissez la propriété secretsManagementSettings :

"secretsManagementSettings": {
   "requireInitialSync": true,
   ...
}

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.

Important

La fonctionnalité de classement des dépendances d’extension n’est pas compatible avec un modèle ARM qui crée une identité affectée par le système et met à jour une stratégie d’accès Key Vault avec celle-ci. Si vous tentez d’utiliser la fonctionnalité dans ce scénario, un blocage se produit, car la stratégie d’accès Key Vault ne peut pas être mise à jour tant que toutes les extensions n’ont pas démarré. Vous devez utiliser à la place une identité MSI unique affectée par l’utilisateur et inscrire vos coffres au préalable sur une liste de contrôle d’accès en utilisant cette identité avant de les déployer.

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": {
   "pollingIntervalInS": "3600",
   "linkOnRenewal": true,
   "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",
          "keyExportable": true,
          "accounts": [
             "Network Service",
             "Local Service"
          ]
      }
   ]},
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity/oauth2/token",
      "msiClientId":  "c7373ae5-91c2-4165-8ab6-7381d6e75619"
   }      
}

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 "3.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 "3.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": {
          "pollingIntervalInS": "3600",
          "linkOnRenewal": true,
          "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",                
                "keyExportable": true,
                "accounts": [
                    "Network Service",
                    "Local Service"
                ]
            }
        ]
        },
          "authenticationSettings": {
          "msiEndpoint":  "http://169.254.169.254/metadata/identity/oauth2/token",
          "msiClientId":  "c7373ae5-91c2-4165-8ab6-7381d6e75619"
        }      
     }

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"

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"

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 ?

L’extension s’appuie sur le comportement par défaut de l’API PFXImportCertStore. Par défaut, si l’attribut Nom du fournisseur d’un certificat correspond à CAPI1, alors le certificat est importé avec les API CAPI1. Sinon, le certificat est importé à l’aide d’API 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 de canal S au moment du renouvellement de certificat lorsque la valeur de la propriété linkOnRenewal est définie sur true.

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 obtenir plus d’informations, consultez Rétablissement de liaison de certificat dans IIS

Afficher l’état de l’extension

Vérifiez le statut de votre déploiement d’extension dans le Portail Azure ou à l’aide de PowerShell ou d’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.

Fichier journal Description
C:\WindowsAzure\Logs\WaAppAgent.log` Indique quand des mises à jour se produisent pour l’extension.
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<version la plus récente>\ Affiche l’état du téléchargement du certificat. L’emplacement de téléchargement est toujours le magasin MY de l’ordinateur Windows (certlm.msc).
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<version la plus récente>\RuntimeSettings\ Les journaux du service d’extension de machine virtuelle Key Vault affichent l’état du service akvvm_service.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<version la plus récente>\Status\ Configuration et fichiers binaires du service d’extension de machine virtuelle Key Vault.

Obtenir de l’aide

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