Estensione di macchina virtuale Key Vault per Windows

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

Sistema operativo

L Key Vault di macchina virtuale supporta le versioni seguenti di Windows:

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

L Key Vault di macchina virtuale virtuale è supportata anche nella macchina virtuale locale personalizzata caricata e convertita in un'immagine specializzata da usare in Azure tramite l'installazione di Windows Server 2019 Core.

Tipi di contenuto del certificato supportati

  • PKCS #12
  • PEM

Prerequisiti

  • Key Vault istanza con certificato. Vedere Creare un Key Vault
  • Alla macchina virtuale deve essere assegnata un'identità gestita
  • I Key Vault di accesso devono essere impostati con segreti e l'autorizzazione per l'identità gestita della macchina virtuale o del set di sicurezza delle macchine virtuali per recuperare la parte del getlist certificato di un segreto. Vedere How to Authenticate to Key Vault and Assign a Key Vault access policy (Come eseguire l'autenticazione Key Vault e Assegnare un criterio di accesso remoto).
  • I set di scalabilità di macchine virtuali devono avere l'impostazione di identità seguente:
"identity": {
  "type": "UserAssigned",
  "userAssignedIdentities": {
    "[parameters('userAssignedIdentityResourceId')]": {}
  }
}
  • L'estensione AKV deve avere questa impostazione:
"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. L'estensione non richiede impostazioni protette. Tutte le impostazioni sono considerate informazioni pubbliche. L'estensione richiede un elenco di certificati monitorati, la frequenza di polling e l'archivio certificati di destinazione. In particolare:

    {
      "type": "Microsoft.Compute/virtualMachines/extensions",
      "name": "KVVMExtensionForWindows",
      "apiVersion": "2019-07-01",
      "location": "<location>",
      "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
      ],
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForWindows",
      "typeHandlerVersion": "1.0",
      "autoUpgradeMinorVersion": true,
      "settings": {
        "secretsManagementSettings": {
          "pollingIntervalInS": <string specifying polling interval in seconds, e.g: "3600">,
          "certificateStoreName": <certificate store name, e.g.: "MY">,
          "linkOnRenewal": <Only Windows. This feature ensures s-channel binding when certificate renews, without necessitating a re-deployment.  e.g.: false>,
          "certificateStoreLocation": <certificate store location, currently it works locally only e.g.: "LocalMachine">,
          "requireInitialSync": <initial synchronization of certificates e..g: true>,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: "https://myvault.vault.azure.net/secrets/mycertificate"
        },
        "authenticationSettings": {
                "msiEndpoint":  <Optional MSI endpoint e.g.: "http://169.254.169.254/metadata/identity">,
                "msiClientId":  <Optional MSI identity e.g.: "c7373ae5-91c2-4165-8ab6-7381d6e75619">
        }
       }
      }
    }

Nota

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

Ciò è dovuto al fatto che il percorso /secrets restituisce il certificato completo, inclusa la chiave privata, mentre il percorso /certificates non lo restituisce. Altre informazioni sui certificati sono disponibili qui: Certificati Key Vault

Importante

La proprietà 'authenticationSettings' è obbligatoria solo per le macchine virtuali con identità assegnate dall'utente. Specifica l'identità da usare per l'autenticazione Key Vault.

Importante

Se si specifica "msiClientId", la proprietà "msiEndpoint" è obbligatoria. In genere il valore deve essere impostato su http://169.254.169.254/metadata/identity/oauth2/token .

Valori delle proprietà

Nome Valore/Esempio Tipo di dati
apiVersion 2019-07-01 Data
publisher Microsoft.Azure.KeyVault string
type KeyVaultForWindows string
typeHandlerVersion 1.0 INT
pollingIntervalInS 3600 string
certificateStoreName MY string
linkOnRenewal false boolean
certificateStoreLocation LocalMachine o CurrentUser (con distinzione tra maiuscole e minuscole) string
requireInitialSync true boolean
observedCertificates ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"] Matrice di stringhe
msiEndpoint http://169.254.169.254/metadata/identity string
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string

Distribuzione del modello

Le estensioni macchina virtuale di Azure possono essere distribuite con i modelli di 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 in 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 macchina virtuale deve essere annidata all'interno del frammento delle risorse della macchina virtuale del modello, in particolare nell'oggetto "resources": [] per il modello di macchina virtuale e nell'oggetto "virtualMachineProfile":"extensionProfile":{"extensions" :[] nel caso di un set di scalabilità di macchine virtuali.

Nota

L'estensione macchina virtuale richiede l'assegnazione dell'identità gestita dal sistema o dall'utente per l'autenticazione nell'insieme di credenziali delle chiavi. Vedere Come eseguire l'autenticazione per Key Vault e assegnare criteri Key Vault di accesso.

    {
      "type": "Microsoft.Compute/virtualMachines/extensions",
      "name": "KeyVaultForWindows",
      "apiVersion": "2019-07-01",
      "location": "<location>",
      "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
      ],
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForWindows",
      "typeHandlerVersion": "1.0",
      "autoUpgradeMinorVersion": true,
      "settings": {
        "secretsManagementSettings": {
          "pollingIntervalInS": <string specifying polling interval in seconds, e.g: "3600">,
          "certificateStoreName": <certificate store name, e.g.: "MY">,
          "certificateStoreLocation": <certificate store location, currently it works locally only e.g.: "LocalMachine">,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"]>
        }      
      }
      }
    }

Ordinamento delle dipendenze dell'estensione

L'Key Vault macchina virtuale virtuale supporta l'ordinamento delle estensioni, se configurata. Per impostazione predefinita, l'estensione segnala che è stata avviata correttamente non appena è stato avviato il polling. Tuttavia, può essere configurato in modo da attendere fino a quando non viene scaricato correttamente l'elenco completo dei certificati prima di segnalare un avvio corretto. Se altre estensioni dipendono dall'installazione del set completo di certificati prima dell'avvio, l'abilitazione di questa impostazione consentirà a tali estensioni di dichiarare una dipendenza dall'Key Vault predefinita. Ciò impedirà l'avvio di tali estensioni fino a quando non sono stati installati tutti i certificati da cui dipendono. L'estensione ritenterà il download iniziale per un periodo illimitato e rimarrà in Transitioning uno stato .

Per attivare questa opzione, impostare quanto segue:

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

Nota

L'uso di questa funzionalità non è compatibile con un modello arm che crea un'identità assegnata dal sistema e aggiorna un criterio Key Vault di accesso con tale identità. In questo modo si verifica un deadlock perché i criteri di accesso dell'insieme di credenziali non possono essere aggiornati fino all'avvio di tutte le estensioni. È invece consigliabile usare una singola identità dell'identità del servizio msi assegnata dall'utente e pre-ACL degli insiemi di credenziali con tale identità prima della distribuzione.

Distribuzione con Azure PowerShell

Avviso

I client PowerShell spesso aggiungono a nel file \ settings.json, causando l'esito negativo di akvvm_service con l'errore I caratteri e aggiuntivi saranno visibili nel "[CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.\" portale, in \"Estensioni in Impostazioni . Per evitare questo problema, $settings inizializzare come HashTable PowerShell:

$settings = @{
    "secretsManagementSettings" = @{ 
        "pollingIntervalInS"       = "<pollingInterval>"; 
        "certificateStoreName"     = "<certStoreName>"; 
        "certificateStoreLocation" = "<certStoreLoc>"; 
        "observedCertificates"     = @("<observedCert1>", "<observedCert2>") } }

È possibile usare Azure PowerShell per distribuire l'estensione di macchina virtuale Key Vault in una macchina virtuale o un set di scalabilità di macchine virtuali esistente.

  • Per distribuire l'estensione in una macchina virtuale:

        # Build settings
        $settings = '{"secretsManagementSettings": 
        { "pollingIntervalInS": "' + <pollingInterval> + 
        '", "certificateStoreName": "' + <certStoreName> + 
        '", "certificateStoreLocation": "' + <certStoreLoc> + 
        '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
        $extName =  "KeyVaultForWindows"
        $extPublisher = "Microsoft.Azure.KeyVault"
        $extType = "KeyVaultForWindows"
    
    
        # Start the deployment
        Set-AzVmExtension -TypeHandlerVersion "1.0" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings
    
    
  • Per distribuire l'estensione in un set di scalabilità di macchine virtuali:

    
        # Build settings
        $settings = '{"secretsManagementSettings": 
        { "pollingIntervalInS": "' + <pollingInterval> + 
        '", "certificateStoreName": "' + <certStoreName> + 
        '", "certificateStoreLocation": "' + <certStoreLoc> + 
        '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
        $extName = "KeyVaultForWindows"
        $extPublisher = "Microsoft.Azure.KeyVault"
        $extType = "KeyVaultForWindows"
    
        # Add Extension to VMSS
        $vmss = Get-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName>
        Add-AzVmssExtension -VirtualMachineScaleSet $vmss  -Name $extName -Publisher $extPublisher -Type $extType -TypeHandlerVersion "1.0" -Setting $settings
    
        # Start the deployment
        Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss 
    
    

Distribuzione dell'interfaccia della riga di comando di Azure

Per distribuire l'estensione macchina virtuale di Key Vault in una macchina virtuale o un set di scalabilità di macchine virtuali esistente è possibile usare l'interfaccia della riga di comando di Azure.

  • Per distribuire l'estensione in una macchina virtuale:

       # Start the deployment
         az vm extension set --name "KeyVaultForWindows" `
         --publisher Microsoft.Azure.KeyVault `
         --resource-group "<resourcegroup>" `
         --vm-name "<vmName>" `
         --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'
    
  • Per distribuire l'estensione in un set di scalabilità di macchine virtuali:

          # Start the deployment
          az vmss extension set --name "KeyVaultForWindows" `
           --publisher Microsoft.Azure.KeyVault `
           --resource-group "<resourcegroup>" `
           --vmss-name "<vmName>" `
           --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'
    

Tenere presenti le restrizioni e i requisiti seguenti:

  • Restrizioni relative all'insieme di credenziali:
    • Deve essere già presente al momento della distribuzione
    • I Key Vault di accesso devono essere impostati per l'identità VM/VMSS usando un'identità gestita. Vedere How to Authenticate to Key Vault and Assign a Key Vault access policy.

Risoluzione dei problemi e supporto

Domande frequenti

  • Esiste un limite per il numero di certificati osservati che è possibile configurare? No, Key Vault'estensione vm non ha un limite al numero di observedCertificates.

Risolvere problemi

I dati sullo stato delle distribuzioni dell'estensione possono essere recuperati nel portale di Azure e tramite Azure PowerShell. Per visualizzare lo stato di distribuzione delle estensioni per una macchina virtuale specifica, eseguire il comando seguente tramite Azure PowerShell.

Azure PowerShell

Get-AzVMExtension -VMName <vmName> -ResourceGroupname <resource group name>

Interfaccia della riga di comando di Azure

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

Log e configurazione

I Key Vault di estensione della macchina virtuale esistono solo in locale nella macchina virtuale e sono più informativi quando si tratta di risoluzione dei problemi

Location Descrizione
C:\WindowsAzure\Log\WaAppAgent.log Indica quando si è verificato un aggiornamento dell'estensione.
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows < versione più recente > \ Visualizza lo stato del download del certificato. Il percorso di download sarà sempre Windows my store del computer (certlm.msc).
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows versione più < recente > \RuntimeSettings\ I Key Vault del servizio estensione vm mostrano lo stato del servizio akvvm_service macchina virtuale.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows versione più < recente > \Status\ La configurazione e i file binari per il Key Vault di estensione della macchina virtuale.

Supporto

Per ricevere assistenza in relazione a qualsiasi punto di questo articolo, contattare gli esperti di Azure nei forum MSDN e Stack Overflow relativi ad Azure. In alternativa, è possibile archiviare un evento imprevisto di supporto tecnico di Azure. Accedere al sito del supporto di Azure e selezionare l'opzione desiderata per ottenere supporto. Per informazioni sull'uso del supporto di Azure, leggere le Domande frequenti sul supporto di Azure.