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

2025-05-20

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 Windows Server 2019 och senare. 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

Anmärkning

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.

Egenskaper

Key Vault VM-tillägget för Windows version 3.0 stöder:

Lägga till ACL-behörigheter för nedladdade certifikat
Aktivera konfiguration för certifikatlagring för varje 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-nivå för virtuella datorer och hanterad identitet för Azure Virtual Machine Scale Sets. 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 konfigurationer:

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

Anmärkning

Den gamla behörighetsmodellen för åtkomstprinciper kan också användas för att ge åtkomst till virtuella maskiner och Virtual Machine Scale Sets. Den här metoden kräver en princip med hämta och lista behörigheter för hemligheter. Mer information finns i Tilldela en åtkomstprincip för Key Vault.

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 authenticationSettingskrä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:  "00001111-aaaa-2222-bbbb-3333cccc4444">
         }
      }
   }
}

Egenskapsvärden

JSON-schemat innehåller följande egenskaper.

Namn	Värde/exempel	Datatyp
`apiVersion`	2022-08-01	datum
`publisher`	Microsoft.Azure.KeyVault	snöre
`type`	KeyVaultForWindows	snöre
`typeHandlerVersion`	"3.0"	snöre
`pollingIntervalInS`	"3600"	snöre
`linkOnRenewal` (valfritt)	sann	booleskt
`requireInitialSync` (valfritt)	falskt	booleskt
`observedCertificates`	[{...}, {...}]	strängmatris
`observedCertificates/url`	"https://myvault.vault.azure.net/secrets/mycertificate"	snöre
`observedCertificates/certificateStoreName`	MIN	snöre
`observedCertificates/certificateStoreLocation`	LocalMachine eller CurrentUser (skiftlägeskänslig)	snöre
`observedCertificates/keyExportable` (valfritt)	falskt	booleskt
`observedCertificates/accounts` (valfritt)	["Nätverkstjänst", "Lokal tjänst"]	strängmatris
`msiEndpoint`	"http://169.254.169.254/metadata/identity/oauth2/token"	snöre
`msiClientId`	00001111-aaaa-2222-bbbb-3333cccc4444	snöre

Malltillämpning

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 instanser av spridningsuppsättningar av virtuella datorer. 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 i Virtuella maskinskalningsuppsättningar kapslas konfigurationen in under "virtualMachineProfile":"extensionProfile":{"extensions" :[]-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: "00001111-aaaa-2222-bbbb-3333cccc4444">
         }
      }
   }
}

Tilläggsberoendens ordning

Du kan aktivera tillägget för den virtuella Key Vault-datorn för att stödja beroendeordning för tillägg. Som standardinställning rapporterar Key Vault VM-tillägget en lyckad start så snart pollingen 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. Den här funktionen gör det möjligt för andra tillägg att deklarera ett beroende av Key Vault VM-tillägget.

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 certifikaten igen upp till 25 gånger med ökande backoff-perioder, under vilka det förblir i övergångstillstånd . Om återförsöken är uttömda rapporterar tillägget ett feltillstånd . När alla certifikat har installerats rapporterar tillägget för den virtuella Key Vault-datorn en lyckad start.

Om du vill aktivera funktionen för beroendetilläggsordning i Key Vault VM-tillägget anger du secretsManagementSettings egenskapen:

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

Mer information om hur du konfigurerar beroenden mellan tillägg finns i sekvenstilläggs förberedelse i Skalningsuppsättningar för virtuella maskiner.

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 istället en enkelanvändartilldelad MSI-identitet och för-ACL:a 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":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }      
}

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 instans av en skalningsuppsättning för virtuella maskiner

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

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":  "00001111-aaaa-2222-bbbb-3333cccc4444"
        }      
     }

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 instans av en skalningsuppsättning för virtuella maskiner

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

Felsökning av problemen

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 Portal 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.

Certifikatinstallation i Windows

Key Vault VM-tillägget för Windows installerar certifikat i Windows-certifikatarkivet. När ett certifikat laddas ned från Key Vault är filtillägget:

Installerar alla mellanliggande certifikat och lövcertifikat, oavsett hur många mellanliggande certifikat som finns. Rotcertifikat installeras inte eftersom tillägget inte har behörighet att utföra rotinstallationen. Det är tjänstägarens ansvar att se till att rotcertifikatet betros i systemet.
- Lövcertifikat installeras i det angivna certifikatarkivet (certificateStoreName) och platsen (certificateStoreLocation)
- Mellanliggande CA-certifikat installeras i lagringsplatsen för mellanliggande certifikatutfärdare
Placerar certifikaten i det angivna certifikatarkivet (certificateStoreName) och platsen (certificateStoreLocation)
Tillämpar lämpliga behörigheter på den privata nyckeln baserat på den accounts som anges i konfigurationen
Anger egenskapen (om den linkOnRenewal är aktiverad) för att säkerställa att certifikatbindningar i program som IIS uppdateras automatiskt när certifikat förnyas

Standardcertifikatlager

Om det inte anges installeras certifikaten på följande platser som standard:

Butiksnamn: MY (Personlig)
Butiksplats: LocalMachine

Åtkomstkontroll för certifikat

Administratörer och SYSTEM får som standard fullständig behörighet för installerade certifikat. Du kan anpassa åtkomsten med hjälp av matrisen accounts i certifikatkonfigurationen:

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

Detta ger läsåtkomst till de angivna kontona, vilket gör att program som körs under dessa identiteter kan använda certifikaten.

Certifikatförnyelse

När certifikat förnyas i Key Vault: tillägget automatiskt:

Laddar ned den nya certifikatversionen
Installerar den i det konfigurerade certifikatarkivet
Upprätthåller befintliga bindningar via funktionen linkOnRenewal om den är aktiverad

Hantera certifikatets livscykel

För program som IIS som stöder meddelanden om certifikatlivscykel genererar tillägget händelser när certifikat med matchande alternativa ämnesnamn (SAN) installeras, vilket möjliggör automatisk ombindning utan avbrott i tjä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.

Dela via

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

Operativsystem

Certifikat som stöds

Egenskaper

Förutsättningar

Tilläggsschema

Egenskapsvärden

Malltillämpning

Tilläggsberoendens ordning

Azure PowerShell-distribution

Distribuera på en virtuell dator

Distribuera på en instans av en skalningsuppsättning för virtuella maskiner

Azure CLI-utplacering

Distribuera på en virtuell dator

Distribuera på en instans av en skalningsuppsättning för virtuella maskiner

Felsökning av problemen

Kontrollera vanliga frågor och svar

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

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

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

Stöder tillägget automatisk ombindning av certifikat?

Visa tilläggsstatus

Granska loggar och konfiguration

Certifikatinstallation i Windows

Standardcertifikatlager

Åtkomstkontroll för certifikat

Certifikatförnyelse

Hantera certifikatets livscykel

Få support

Feedback

Ytterligare resurser