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.
• Non è più possibile configurare una versione specifica di un certificato.
• L'estensione ora archivia sempre le chiavi private usando 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.

• Assegnare il ruolo Utente dei segreti di Key Vault nell'ambito di Key Vault all'identità gestita per la macchina virtuale o per i set di scalabilità di macchine virtuali di Azure. Questo ruolo recupera la parte segreta 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

• Configurare i set di scalabilità di macchine virtuali con la seguente identity configurazione:

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

• Configurare l'estensione macchina virtuale Key Vault con la configurazione seguenteauthenticationSettings:

  "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 informazioni pubbliche.

• Usare il modulo https://myVaultName.vault.azure.net/secrets/myCertName per gli URL dei certificati osservati.

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

Valori delle proprietà

Lo schema JSON include le proprietà seguenti.

Distribuzione di template

Distribuire le estensioni delle macchine virtuali di Azure tramite i modelli di Azure Resource Manager (ARM). I modelli sono ideali quando si distribuiscono una o più macchine virtuali che richiedono l'aggiornamento post-distribuzione dei certificati. È possibile distribuire l'estensione 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 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">
         }
      }
   }
}

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. Azure mantiene automaticamente aggiornata l'estensione quando si impostano le proprietà autoUpgradeMinorVersion e enableAutomaticUpgrade su true negli esempi precedenti.

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 altre informazioni sulla configurazione delle dipendenze tra le estensioni, vedere Provisioning delle estensioni di sequenza in set di scalabilità di macchine virtuali.

Distribuzione con Azure PowerShell

Distribuire l'estensione macchina virtuale Azure Key Vault usando 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 macchina virtuale Key Vault tramite 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

Distribuire l'estensione macchina virtuale Azure Key Vault usando il 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 macchina virtuale Key Vault usando il 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>"

Risoluzione dei problemi

Usare questi suggerimenti per 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, l'estensione salva le chiavi private per tutti i certificati usando 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 l'estensione scarica un certificato da Key Vault, è possibile:

1. Installa tutti i certificati intermedi e foglia, indipendentemente da quanti certificati intermedi siano presenti. L'estensione non installa i certificati radice perché non è autorizzata a installarli. Assicurarsi che il certificato radice sia attendibile sul sistema.
   • Installa i certificati foglia nell'archivio certificati specificato (certificateStoreName) e nella posizione specificata (certificateStoreLocation).
   • Installa i certificati delle CA intermedie 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à in modo che le associazioni di certificati nelle applicazioni, ad esempio IIS, vengano aggiornate automaticamente quando vengono rinnovati i certificati.

Archivi dei certificati predefiniti

Per impostazione predefinita, l'estensione installa i certificati nei percorsi seguenti:

• Nome archivio: MY (Personale).
• Posizione dell'archivio: 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"]

Questa configurazione concede l'accesso in lettura agli account specificati, che consente 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. Installa il certificato nell'archivio certificati configurato.
3. Gestisce le associazioni esistenti utilizzando la CERT_RENEWAL proprietà .

Gestione del ciclo di vita dei certificati

Per le applicazioni come IIS che supportano le notifiche relative al ciclo di vita dei servizi certificati, l'estensione della macchina virtuale Key Vault genera l'evento 1001 nel registro eventi Windows quando installa un certificato con un nome alternativo soggetto corrispondente. IIS sottoscrive questo evento per riassociare automaticamente il certificato rinnovato senza interrompere il 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

Microsoft fornisce supporto solo per la versione principale 3.0 e successive dell'estensione macchina virtuale Key Vault. Se si usa la versione 1.0, eseguire l'aggiornamento alla versione più recente prima di richiedere supporto.

Usare queste altre opzioni per 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.