Estensione macchina virtuale di Azure Key Vault per Windows

  • Articolo

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 le versioni seguenti di Windows:

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

L'estensione macchina virtuale Key Vault è supportata anche in una macchina virtuale locale personalizzata. La macchina virtuale deve essere caricata e convertita in un'immagine specializzata da usare in Azure usando l'installazione principale di Windows Server 2019.

Certificati supportati

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

  • PKCS #12
  • PEM

Nota

L'estensione della macchina virtuale Key Vault scarica tutti i certificati nell'archivio certificati di Windows o nel percorso specificato nella certificateStoreLocation proprietà nelle impostazioni dell'estensione della macchina virtuale.

Aggiornamenti nella versione 3.0+

La versione 3.0 dell'estensione macchina virtuale Key Vault per Windows aggiunge il supporto per le funzionalità seguenti:

  • Aggiungere autorizzazioni ACL per i certificati scaricati
  • Abilitare la configurazione dell'archivio certificati per ogni certificato
  • Esportare chiavi private
  • Supporto di ribind dei certificati IIS

Prerequisiti

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

Nota

Il modello di autorizzazione dei criteri di accesso precedente può essere usato anche per fornire l'accesso alle macchine virtuali e alle set di scalabilità di macchine virtuali. Questo metodo richiede criteri con autorizzazioni get ed list per i segreti. Per ulteriori informazioni, vedere Assegnare un criterio di accesso di Key Vault.

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

Valori delle proprietà

Lo schema JSON include le proprietà seguenti.

Nome Valore/Esempio Tipo di dati
apiVersion 2022-08-01 data
publisher Microsoft.Azure.KeyVault string
type KeyVaultForWindows string
typeHandlerVersion "3.0" string
pollingIntervalInS "3600" string
linkOnRenewal (facoltativo) true boolean
requireInitialSync (facoltativo) false boolean
observedCertificates [{...}, {...}] Matrice di stringhe
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate" string
observedCertificates/certificateStoreName MY string
observedCertificates/certificateStoreLocation LocalMachine o CurrentUser (con distinzione tra maiuscole e minuscole) string
observedCertificates/keyExportable (facoltativo) false boolean
observedCertificates/accounts (facoltativo) ["Servizio di rete", "Servizio locale"] Matrice di stringhe
msiEndpoint "http://169.254.169.254/metadata/identity/oauth2/token" string
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string

Distribuzione modelli

Le estensioni vm di Azure possono essere distribuite con modelli di Azure Resource Manager (ARM). 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 della macchina virtuale o set di scalabilità di macchine virtuali modello. Per un'estensione della risorsa macchina virtuale, la configurazione viene annidata nell'oggetto "resources": [] macchina virtuale. Per un'estensione dell'istanza di set di scalabilità di macchine virtuali, la configurazione viene annidata sotto l'oggetto "virtualMachineProfile":"extensionProfile":{"extensions" :[] .

I frammenti di codice JSON seguenti forniscono impostazioni di esempio per la distribuzione di un modello di Resource Manager dell'estensione macchina virtuale 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">
         }
      }
   }
}

Ordinamento delle dipendenze dell'estensione

È possibile abilitare l'estensione della macchina virtuale di Key Vault per supportare l'ordinamento delle dipendenze dell'estensione. Per impostazione predefinita, l'estensione della macchina virtuale Key Vault segnala un avvio riuscito non appena inizia il polling. Tuttavia, è possibile configurare l'estensione per segnalare un avvio riuscito solo dopo il download dell'estensione e l'installazione di tutti i certificati.

Se si usano altre estensioni che richiedono l'installazione di tutti i certificati prima dell'avvio, è possibile abilitare l'ordinamento delle dipendenze dell'estensione nell'estensione della macchina virtuale di Key Vault. Questa funzionalità consente ad altre estensioni di dichiarare una dipendenza dall'estensione della macchina virtuale di Key Vault.

È possibile usare questa funzionalità per impedire l'avvio di altre estensioni fino a quando non vengono installati tutti i certificati dipendenti. Quando la funzionalità è abilitata, l'estensione della macchina virtuale Key Vault ritenta il download e l'installazione dei certificati per un periodo illimitato e rimane in uno stato di transizione , fino a quando non vengono installati tutti i certificati. Dopo che tutti i certificati sono presenti, l'estensione della macchina virtuale di Key Vault segnala un avvio corretto.

Per abilitare la funzionalità di ordinamento delle dipendenze dell'estensione nell'estensione della macchina virtuale di Key Vault, impostare la secretsManagementSettings proprietà :

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

Per altre informazioni su come configurare le dipendenze tra le estensioni, vedere Provisioning delle estensioni di sequenza in set di scalabilità di macchine virtuali.

Importante

La funzionalità di ordinamento delle dipendenze dell'estensione non è compatibile con un modello di Resource Manager che crea un'identità assegnata dal sistema e aggiorna i criteri di accesso di Key Vault con tale identità. Se si tenta di usare la funzionalità in questo scenario, si verifica un deadlock perché i criteri di accesso di Key Vault non possono essere aggiornati fino all'avvio di tutte le estensioni. Usare invece un'identità msi assegnata dall'utente singolo e pre-ACL gli insiemi di credenziali delle chiavi con tale identità prima di eseguire la distribuzione.

Distribuzione con Azure PowerShell

L'estensione vm di Azure Key Vault può essere distribuita con Azure PowerShell. Salvare le impostazioni dell'estensione macchina virtuale 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": {
   "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"
   }      
}

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 "3.0" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings

Eseguire la distribuzione 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 "3.0" -Setting $settings

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

Distribuzione dell'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 macchina virtuale 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": {
          "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"
        }      
     }

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"

Eseguire la distribuzione 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"

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?

L'estensione si basa sul comportamento predefinito dell'API PFXImportCertStore. Per impostazione predefinita, se un certificato ha un attributo Provider Name corrispondente a CAPI1, il certificato viene importato usando le API CAPI1. In caso contrario, il certificato viene importato usando le API 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 quando la linkOnRenewal proprietà è impostata su true.

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 Certifcate Rebind 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, eseguire 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 dell'insieme di credenziali delle chiavi esistono solo in locale nella macchina virtuale. Esaminare i dettagli del log per facilitare la risoluzione dei problemi.

File di log Descrizione
C:\WindowsAzure\Logs\WaAppAgent.log' Mostra quando si verificano aggiornamenti all'estensione.
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<versione> più recente\ Mostra lo stato del download del certificato. Il percorso di download è sempre l'archivio MY del computer Windows (certlm.msc).
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<versione> più recente\RuntimeSettings\ I log del servizio dell'estensione macchina virtuale key vault mostrano lo stato del servizio akvvm_service.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<versione> più recente\Status\ Configurazione e file binari per il servizio dell'estensione della macchina virtuale di Key Vault.

Ottenere supporto

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