Dela via

Azure Key Vault-tillägg för virtuella datorer för Windows

  • Artikel

Tillägget för den virtuella Azure Key Vault-datorn (VM) ger automatisk uppdatering av certifikat som lagras i ett Azure-nyckelvalv. Tillägget övervakar en lista över observerade certifikat som lagras i nyckelvalv. När den identifierar en ändring hämtar och installerar tillägget motsvarande certifikat. Den här artikeln beskriver de plattformar, konfigurationer och distributionsalternativ som stöds för key vault VM-tillägget för Windows.

Operativsystem

Tillägget för den virtuella Key Vault-datorn stöder följande versioner av Windows:

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

Tillägget för den virtuella Key Vault-datorn stöds också på en anpassad lokal virtuell dator. Den virtuella datorn ska laddas upp och konverteras till en specialiserad avbildning för användning i Azure med hjälp av Windows Server 2019 Core Install.

Certifikat som stöds

Key Vault VM-tillägget stöder följande certifikatinnehållstyper:

  • PKCS #12
  • PEM

Kommentar

Key Vault VM-tillägget laddar ned alla certifikat till Windows-certifikatarkivet eller till den plats som anges i certificateStoreLocation egenskapen i inställningarna för VM-tillägg.

Uppdateringar i version 3.0+

Version 3.0 av Key Vault VM-tillägget för Windows lägger till stöd för följande funktioner:

  • Lägga till ACL-behörigheter för nedladdade certifikat
  • Aktivera konfiguration av certifikatarkiv per certifikat
  • Exportera privata nycklar
  • Stöd för ombindning av IIS-certifikat

Förutsättningar

Granska följande förutsättningar för att använda key vault VM-tillägget för Windows:

  • En Azure Key Vault-instans med ett certifikat. Mer information finns i Skapa ett nyckelvalv med hjälp av Azure-portalen.

  • En virtuell dator med en tilldelad hanterad identitet.

  • Rollen Key Vault Secrets User måste tilldelas på key vault-omfångsnivå för virtuella datorer och azure virtual machine scale sets managed identity. Den här rollen hämtar en hemlighets del av ett certifikat. Mer information finns i följande artiklar:

  • Vm-skalningsuppsättningar bör ha följande identity konfiguration:

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

  • Tillägget för den virtuella Key Vault-datorn bör ha följande authenticationSettings konfiguration:

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

Kommentar

Den gamla behörighetsmodellen för åtkomstprinciper kan också användas för att ge åtkomst till virtuella datorer och vm-skalningsuppsättningar. Den här metoden kräver en princip med behörigheter för hämta och lista för hemligheter. Mer information finns i Tilldela en key vault-åtkomstprincip.

Tilläggsschema

Följande JSON visar schemat för tillägget för den virtuella Key Vault-datorn. Innan du överväger alternativen för schemaimplementering bör du läsa följande viktiga anteckningar.

  • Tillägget kräver inte skyddade inställningar. Alla inställningar betraktas som offentlig information.

  • Observerade certifikat-URL:er ska vara av formuläret https://myVaultName.vault.azure.net/secrets/myCertName.

    Det här formuläret rekommenderas eftersom /secrets sökvägen returnerar det fullständiga certifikatet, inklusive den privata nyckeln, men /certificates sökvägen inte. Mer information om certifikat finns i Översikt över Azure Key Vault-nycklar, hemligheter och certifikat.

  • Egenskapen authenticationSettings krävs för virtuella datorer med alla användartilldelade identiteter.

    Den här egenskapen anger den identitet som ska användas för autentisering till Key Vault. Definiera den här egenskapen med en systemtilldelad identitet för att undvika problem med ett VM-tillägg med flera identiteter.

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

Egenskapsvärden

JSON-schemat innehåller följande egenskaper.

Name Värde/exempel Datatyp
apiVersion 2022-08-01 datum
publisher Microsoft.Azure.KeyVault sträng
type KeyVaultForWindows sträng
typeHandlerVersion "3.0" sträng
pollingIntervalInS "3600" sträng
linkOnRenewal (valfritt) true boolean
requireInitialSync (valfritt) falskt boolean
observedCertificates [{...}, {...}] strängmatris
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate" sträng
observedCertificates/certificateStoreName MY sträng
observedCertificates/certificateStoreLocation LocalMachine eller CurrentUser (skiftlägeskänslig) sträng
observedCertificates/keyExportable (valfritt) falskt boolean
observedCertificates/accounts (valfritt) ["Nätverkstjänst", "Lokal tjänst"] strängmatris
msiEndpoint "http://169.254.169.254/metadata/identity/oauth2/token" sträng
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 sträng

Malldistribution

Azure VM-tillägg kan distribueras med ARM-mallar (Azure Resource Manager). Mallar är idealiska när du distribuerar en eller flera virtuella datorer som kräver uppdatering efter distributionen av certifikat. Tillägget kan distribueras till enskilda virtuella datorer eller vm-skalningsuppsättningar. Schemat och konfigurationen är gemensamma för båda malltyperna.

JSON-konfigurationen för ett nyckelvalvstillägg är kapslad i mallen VM eller Vm Scale Sets. För ett vm-resurstillägg kapslas konfigurationen under objektet för den "resources": [] virtuella datorn. För ett instanstillägg för vm-skalningsuppsättningar kapslas konfigurationen "virtualMachineProfile":"extensionProfile":{"extensions" :[] under objektet.

Följande JSON-kodfragment innehåller exempelinställningar för en ARM-malldistribution av key vault VM-tillägget.

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

Ordning på tilläggsberoende

Du kan aktivera tillägget för den virtuella Key Vault-datorn för att stödja beroendeordning för tillägg. Som standard rapporterar tillägget för den virtuella Key Vault-datorn en lyckad start så snart avsökningen börjar. Du kan dock konfigurera tillägget så att det rapporterar en lyckad start först efter att tillägget har laddat ned och installerat alla certifikat.

Om du använder andra tillägg som kräver installation av alla certifikat innan de startas kan du aktivera tilläggsberoendeordning i key vault VM-tillägget. Med den här funktionen kan andra tillägg deklarera ett beroende av tillägget för den virtuella Key Vault-datorn.

Du kan använda den här funktionen för att förhindra att andra tillägg startar tills alla beroende certifikat har installerats. När funktionen är aktiverad försöker Key Vault VM-tillägget ladda ned och installera certifikat på obestämd tid och förblir i övergångstillstånd tills alla certifikat har installerats. När alla certifikat finns rapporterar tillägget för den virtuella Key Vault-datorn en lyckad start.

Om du vill aktivera funktionen för ordningsföljd för tilläggsberoende i tillägget för den virtuella Key Vault-datorn anger du secretsManagementSettings egenskapen:

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

Mer information om hur du konfigurerar beroenden mellan tillägg finns i Sekvenstilläggetablering i Vm-skalningsuppsättningar.

Viktigt!

Funktionen för beroendeordning för tillägg är inte kompatibel med en ARM-mall som skapar en systemtilldelad identitet och uppdaterar en Key Vault-åtkomstprincip med den identiteten. Om du försöker använda funktionen i det här scenariot uppstår ett dödläge eftersom åtkomstprincipen för Key Vault inte kan uppdateras förrän alla tillägg har startats. Använd i stället en MSI-identitet med en användare och en pre-ACL för dina nyckelvalv med den identiteten innan du distribuerar.

Azure PowerShell-distribution

Azure Key Vault VM-tillägget kan distribueras med Azure PowerShell. Spara inställningar för Key Vault VM-tillägg till en JSON-fil (settings.json).

Följande JSON-kodfragment innehåller exempelinställningar för att distribuera tillägget för den virtuella Key Vault-datorn med 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"
   }      
}

Distribuera på en virtuell dator

# 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

Distribuera på en vm-skalningsuppsättningsinstans

# 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

Azure CLI-distribution

Azure Key Vault VM-tillägget kan distribueras med hjälp av Azure CLI. Spara inställningar för Key Vault VM-tillägg till en JSON-fil (settings.json).

Följande JSON-kodfragment innehåller exempelinställningar för distribution av key vault VM-tillägget med 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"
        }      
     }

Distribuera på en virtuell dator

# Start the deployment
az vm extension set --name "KeyVaultForWindows" `
 --publisher Microsoft.Azure.KeyVault `
 --resource-group "<resourcegroup>" `
 --vm-name "<vmName>" `
 --settings "@settings.json"

Distribuera på en vm-skalningsuppsättningsinstans

# Start the deployment
az vmss extension set --name "KeyVaultForWindows" `
 --publisher Microsoft.Azure.KeyVault `
 --resource-group "<resourcegroup>" `
 --vmss-name "<vmssName>" `
 --settings "@settings.json"

Felsöka problem

Här följer några förslag på hur du felsöker distributionsproblem.

Kontrollera vanliga frågor och svar

Finns det en gräns för antalet observerade certifikat?

Nej. Tillägget för den virtuella Key Vault-datorn begränsar inte antalet observerade certifikat (observedCertificates).

Vad är standardbehörigheten när inget konto har angetts?

Som standard får administratörer och SYSTEM fullständig kontroll.

Hur avgör du om en certifikatnyckel är CAPI1 eller CNG?

Tillägget förlitar sig på standardbeteendet för PFXImportCertStore-API:et. Om ett certifikat som standard har ett providernamnattribut som matchar MED CAPI1 importeras certifikatet med hjälp av CAPI1-API:er. Annars importeras certifikatet med hjälp av CNG-API:er.

Stöder tillägget automatisk ombindning av certifikat?

Ja, azure Key Vault VM-tillägget stöder automatisk ombindning av certifikat. Tillägget för den virtuella Key Vault-datorn stöder S-kanalbindning vid certifikatförnyelse när linkOnRenewal egenskapen är inställd på true.

För IIS kan du konfigurera automatisk ombindning genom att aktivera automatisk ombindning av certifikatförnyelser i IIS. Azure Key Vault VM-tillägget genererar meddelanden om certifikatets livscykel när ett certifikat med ett matchande SAN har installerats. IIS använder den här händelsen för att automatiskt ombinda certifikatet. Mer information finns i Certifcate Rebind i IIS

Visa tilläggsstatus

Kontrollera statusen för tilläggsdistributionen i Azure-portalen eller med hjälp av PowerShell eller Azure CLI.

Om du vill se distributionstillståndet för tillägg för en viss virtuell dator kör du följande kommandon.

  • Azure PowerShell:

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

  • The Azure CLI:

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

Granska loggar och konfiguration

Key Vault VM-tilläggsloggarna finns bara lokalt på den virtuella datorn. Granska logginformationen för att få hjälp med felsökning.

Loggfil beskrivning
C:\WindowsAzure\Logs\WaAppAgent.log' Visar när uppdateringar inträffar i tillägget.
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<senaste version>\ Visar status för nedladdning av certifikat. Nedladdningsplatsen är alltid Windows-datorns MY Store (certlm.msc).
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<senaste version>\RuntimeSettings\ Tjänstloggarna för Key Vault VM-tillägget visar status för akvvm_service-tjänsten.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<senaste version>\Status\ Konfigurationen och binärfilerna för key vault VM-tilläggstjänsten.

Få support

Här följer några andra alternativ som hjälper dig att lösa distributionsproblem:

  • Om du vill ha hjälp kontaktar du Azure-experterna på Q&A- och Stack Overflow-forumen.

  • Om du inte hittar något svar på webbplatsen kan du skicka en fråga för indata från Microsoft eller andra medlemmar i communityn.

  • Du kan också kontakta Microsoft Support. Information om hur du använder Azure-support finns i Vanliga frågor och svar om Azure-support.