Estensione macchina virtuale di Azure Key Vault per Windows

L'estensione macchina virtuale di Azure Key Vault fornisce l'aggiornamento automatico dei certificati archiviati in un insieme di credenziali delle chiavi di Azure. L'estensione monitora un elenco di certificati osservati archiviati negli insiemi di credenziali delle chiavi. Quando rileva una modifica, l'estensione recupera e installa i certificati corrispondenti. Questo articolo descrive le piattaforme, le configurazioni e le opzioni di distribuzione supportate per l'estensione vm di Key Vault per Windows.

Sistemi operativi

L'estensione macchina virtuale Key Vault supporta Windows Server 2022 e Windows Server 2025, sia in AMD64 che in ARM64. In Windows Server 2025 le chiavi private vengono salvate in KeyGuard.

Certificati supportati

L'estensione macchina virtuale Key Vault supporta i tipi di contenuto del certificato seguenti:

• PKCS #12
• PEM

Funzionalità

Estensione macchina virtuale Key Vault per Windows versione 4.0:

• Installa chiavi private in KeyGuard quando è in esecuzione su Windows Server 2025.
• Installa le due versioni più recenti di ogni certificato.
• Esegue la convalida della catena di certificati prima di installare qualsiasi certificato contenente l'utilizzo della chiave estesa (EKU) per l'autenticazione del server TLS, inclusi i certificati che contengono altre EKU insieme (ad esempio l'autenticazione client). Gli errori di convalida della catena generano un errore di provisioning per l'estensione. I certificati senza L'autenticazione server EKU non sono soggetti a questo controllo.

Aggiornamento dalla versione 3.0

Se si esegue l'aggiornamento dalla versione 3.0, le funzionalità seguenti vengono modificate o rimosse:

• pollingIntervalInS è ora limitato a un intervallo compreso tra 5 e 60 minuti. Per impostazione predefinita, il polling viene eseguito una volta ogni ora.
• linkOnRenewal viene rimosso. Il collegamento si verifica sempre.
• keyExportable viene rimosso. Le chiavi private non sono più esportabili.
• requireInitialSync viene rimosso. L'estensione segnala l'esito positivo solo se vengono installati tutti i certificati configurati.
• La configurazione di una versione specifica di un certificato non è più possibile.
• Le chiavi private vengono ora sempre archiviate tramite l'API di crittografia: Next Generation (CNG) anziché CAPI.

Prerequisiti

Esaminare i prerequisiti seguenti per l'uso dell'estensione della macchina virtuale Key Vault per Windows:

• Istanza di Azure Key Vault con un certificato. Per ulteriori informazioni, vedere Crea un Key Vault usando il portale di Azure.

• Macchina virtuale con un'identità gestita assegnata.

• Il ruolo Utente segreti Key Vault deve essere assegnato a livello del Key Vault per l'identità gestita di macchine virtuali e set di scalabilità di macchine virtuali di Azure. Questo ruolo recupera la parte di un segreto di un certificato. Per altre informazioni, vedere gli articoli seguenti:

  • Autenticazione in Azure Key Vault
  • Usare le autorizzazioni del segreto, della chiave e del certificato di Controllo degli accessi in base al ruolo di Azure con Azure Key Vault
  • Assegnazione di ruolo nell'ambito di Key Vault

• I set di scalabilità di macchine virtuali devono avere la configurazione seguente identity :

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

• L'estensione macchina virtuale Key Vault deve avere la configurazione seguente authenticationSettings :

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

Schema dell'estensione

Il codice JSON seguente mostra lo schema per l'estensione di macchina virtuale Key Vault. Prima di prendere in considerazione le opzioni di implementazione dello schema, esaminare le note importanti seguenti.

• L'estensione non richiede impostazioni protette. Tutte le impostazioni sono considerate informazioni pubbliche.

• Gli URL dei certificati osservati devono essere nel formato https://myVaultName.vault.azure.net/secrets/myCertName.

  Questo modulo è preferibile perché il /secrets percorso restituisce il certificato completo, inclusa la chiave privata, ma il /certificates percorso non lo fa. Per altre informazioni sui certificati, vedere Panoramica delle chiavi, dei segreti e dei certificati di Azure Key Vault.

• La authenticationSettings proprietà è necessaria per le macchine virtuali con identità assegnate dall'utente.

  Questa proprietà specifica l'identità da usare per l'autenticazione in Key Vault. Definire questa proprietà con un'identità assegnata dal sistema per evitare problemi con un'estensione di macchina virtuale con più identità.

{
   "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">
         }
      }
   }
}

Valori delle proprietà

Lo schema JSON include le proprietà seguenti.

Distribuzione di template

Le estensioni VM di Azure possono essere distribuite con modelli di ARM (Azure Resource Manager). I modelli sono uno strumento ideale per distribuire una o più macchine virtuali per cui è necessario l'aggiornamento dei certificati successivamente alla distribuzione. L'estensione può essere distribuita in singole macchine virtuali o istanze di set di scalabilità di macchine virtuali. Lo schema e la configurazione sono comuni a entrambi i tipi di modello.

La configurazione JSON per un'estensione dell'insieme di credenziali delle chiavi è annidata all'interno del modello VM o dei set di scalabilità di macchine virtuali. Per un'estensione della risorsa di macchina virtuale, la configurazione viene annidata nell'oggetto macchina virtuale "resources": []. Per un'estensione dell'istanza di set di scalabilità di macchine virtuali, la configurazione è annidata sotto l'oggetto "virtualMachineProfile":"extensionProfile":{"extensions" :[].

I seguenti frammenti di codice JSON forniscono impostazioni di esempio per la distribuzione di un modello ARM con l'estensione VM di 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">
         }
      }
   }
}

Aggiornamento automatico dell'estensione

L'estensione macchina virtuale Key Vault supporta l'aggiornamento automatico delle estensioni per le macchine virtuali e i set di scalabilità in Azure. L'estensione viene mantenuta aggiornata automaticamente quando le autoUpgradeMinorVersion proprietà e enableAutomaticUpgrade negli esempi precedenti vengono impostate su true.

Ordinamento delle dipendenze dell'estensione

L'estensione macchina virtuale Key Vault supporta l'ordinamento delle dipendenze dell'estensione. L'estensione segnala un avvio corretto dopo il download e l'installazione di tutti i certificati.

Se si usano altre estensioni che richiedono l'installazione di certificati prima dell'avvio, è possibile usare l'ordinamento delle dipendenze dell'estensione per dichiarare una dipendenza dall'estensione della macchina virtuale Key Vault.

All'avvio, l'estensione della macchina virtuale Key Vault ritenta il download e l'installazione dei certificati fino a 25 volte con periodi di backoff crescenti, durante i quali rimane in uno stato Transitioning. Se i tentativi vengono esauriti, l'estensione segnala uno stato di errore. Dopo l'installazione di tutti i certificati, l'estensione della macchina virtuale Key Vault segnala un avvio corretto.

Per ulteriori informazioni su come configurare le dipendenze tra le estensioni, vedere La configurazione sequenziale delle estensioni nei Set di scalabilità delle macchine virtuali.

Distribuzione con Azure PowerShell

L'estensione VM di Azure Key Vault può essere distribuita con Azure PowerShell. Salvare le impostazioni dell'estensione VM di Key Vault in un file JSON (settings.json).

I frammenti di codice JSON seguenti forniscono impostazioni di esempio per la distribuzione dell'estensione VM di Key Vault con 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"
   }      
}

Distribuire in una macchina virtuale

# 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

Distribuire in un'istanza di set di scalabilità di macchine virtuali.

# 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 

Distribuzione di interfaccia della riga di comando di Azure

L'estensione VM di Azure Key Vault può essere distribuita usando l'interfaccia della riga di comando di Azure. Salvare le impostazioni dell'estensione VM di Key Vault in un file JSON (settings.json).

I frammenti di codice JSON seguenti forniscono impostazioni di esempio per la distribuzione dell'estensione VM di Key Vault con l'interfaccia della riga di comando di Azure.

   {   
        "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"
        }      
     }

Distribuire in una macchina virtuale

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

Distribuire in un'istanza di set di scalabilità di macchine virtuali.

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

Risolvere i problemi

Ecco alcuni suggerimenti su come risolvere i problemi di distribuzione.

Controllare le domande frequenti

Esiste un limite al numero di certificati osservati?

No. L'estensione della macchina virtuale di Key Vault non limita il numero di certificati osservati (observedCertificates).

Qual è l'autorizzazione predefinita quando non viene specificato alcun account?

Per impostazione predefinita, gli amministratori e SYSTEM ricevono controllo completo.

Come si determina se una chiave del certificato è CAPI1 o CNG?

A partire da Key Vault estensione vm 4.0, le chiavi private per tutti i certificati vengono salvate tramite CNG.

L'estensione supporta la riassociazione automatica dei certificati?

Sì, l'estensione della macchina virtuale di Azure Key Vault supporta la riassociazione automatica dei certificati. L'estensione della macchina virtuale Key Vault supporta l'associazione S-channel al rinnovo del certificato.

Per IIS, è possibile configurare la riassociazione automatica abilitando il riassociamento automatico dei rinnovi dei certificati in IIS. L'estensione macchina virtuale di Azure Key Vault genera notifiche relative al ciclo di vita dei certificati quando viene installato un certificato con una SAN corrispondente. IIS usa questo evento per riassociare automaticamente il certificato. Per altre informazioni, vedere Ribind del certificato in IIS.

Visualizzare lo stato dell'estensione

Controllare lo stato della distribuzione dell'estensione nel portale di Azure oppure usando PowerShell o l'interfaccia della riga di comando di Azure.

Per visualizzare lo stato di distribuzione delle estensioni per una determinata macchina virtuale, usare i comandi seguenti.

• Azure PowerShell:

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

• L’interfaccia della riga di comando di Azure:

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

Esaminare i log e la configurazione

I log dell'estensione della macchina virtuale Key Vault sono disponibili solo localmente sulla macchina virtuale. Esaminare i dettagli del log per facilitare la risoluzione dei problemi.

Installazione del certificato in Windows

L'estensione della macchina virtuale Key Vault per Windows installa i certificati nell'archivio certificati di Windows. Quando un certificato viene scaricato da Key Vault, l'estensione:

1. Installa tutti i certificati intermedi e foglia, indipendentemente da quanti certificati intermedi siano presenti. I certificati radice non vengono installati, perché l'estensione non è autorizzata a eseguire l'installazione radice. È responsabilità del proprietario del servizio assicurarsi che il certificato radice sia attendibile nel sistema.
   • I certificati foglia vengono installati nell'archivio certificati specificato (certificateStoreName) e nel percorso (certificateStoreLocation)
   • I certificati CA intermedi vengono installati nell'archivio Autorità di certificazione intermedie
2. Inserisce i certificati nell'archivio certificati specificato (certificateStoreName) e nel percorso (certificateStoreLocation)
3. Applica le autorizzazioni appropriate alla chiave privata in base all'oggetto accounts specificato nella configurazione
4. Imposta la CERT_RENEWAL proprietà per assicurarsi che le associazioni di certificati nelle applicazioni come IIS vengano aggiornate automaticamente quando vengono rinnovati i certificati.

Store certificati predefiniti

Se non specificato, i certificati vengono installati nei percorsi seguenti per impostazione predefinita:

• Nome store: MY (Personale)
• Posizione store: LocalMachine

Controllo di accesso ai certificati

Per impostazione predefinita, gli amministratori e SYSTEM ricevono le autorizzazioni controllo completo per i certificati installati. È possibile personalizzare l'accesso usando la accounts matrice nella configurazione del certificato:

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

In questo modo si concede l'accesso in lettura agli account specificati, consentendo alle applicazioni in esecuzione in tali identità di usare i certificati.

Rinnovo del certificato

Quando i certificati vengono rinnovati in Key Vault, l'estensione viene eseguita automaticamente:

1. Scarica la nuova versione del certificato.
2. Lo installa nell'archivio certificati configurato.
3. Gestisce le associazioni esistenti tramite la CERT_RENEWAL proprietà .

Gestione del ciclo di vita dei certificati

Per applicazioni come IIS che supportano le notifiche relative al ciclo di vita dei servizi certificati, l'estensione macchina virtuale Key Vault genera Event 1001 nel registro eventi Windows quando viene installato un certificato con un nome alternativo soggetto corrispondente. IIS sottoscrive questo evento per riassociare automaticamente il certificato rinnovato senza interruzioni del servizio. Altre applicazioni e team possono anche restare in ascolto dell'evento 1001 per agire sui rinnovi dei certificati in base alle esigenze. Per altre informazioni, vedere Notifiche relative al ciclo di vita dei servizi certificati.

Ottenere supporto

Ecco alcune altre opzioni che consentono di risolvere i problemi di distribuzione:

• Per assistenza, contattare gli esperti Azure in Microsoft Q& A.

• Se non si trova una risposta nel sito, è possibile pubblicare una domanda per l'input di Microsoft o di altri membri della community.

• È anche possibile contattare il supporto tecnico Microsoft. Per informazioni sull'uso di supporto tecnico di Azure, vedere Come creare una richiesta di supporto tecnico di Azure.