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

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

Det Key Vault VM-tillägget stöder Windows Server 2022 och Windows Server 2025 på både AMD64 och ARM64. På Windows Server 2025 sparas privata nycklar i KeyGuard.

Certifikat som stöds

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

• PKCS #12
• PEM

Egenskaper

Det Key Vault VM-tillägget för Windows version 4.0:

• Installerar privata nycklar i KeyGuard om det körs på Windows Server 2025.
• Installerar de två senaste versionerna av varje certifikat.
• Utför validering av certifikatkedjan innan du installerar ett certifikat som innehåller TLS Server Authentication Extended Key Usage (EKU), inklusive certifikat som har andra EKU:er bredvid sig (till exempel klientautentisering). Valideringsfel i kedjan resulterar i ett tilldelningsfel för tillägget. Certifikat utan EKU för serverautentisering omfattas inte av den här kontrollen.

Uppgradera från 3.0

Om du uppdaterar från 3.0 ändras eller tas följande funktioner bort:

• pollingIntervalInS är nu begränsad till mellan 5 och 60 minuter. Som standard utförs avsökningen en gång i timmen.
• linkOnRenewal tas bort. Länkning sker alltid.
• keyExportable tas bort. Privata nycklar kan inte längre exporteras.
• requireInitialSync tas bort. Tillägget rapporterar enbart lyckat resultat om alla konfigurerade certifikat har installerats framgångsrikt.
• Det går inte längre att konfigurera en specifik version av ett certifikat.
• Privata nycklar lagras nu alltid via kryptografi-API: Nästa generation (CNG) i stället för CAPI.

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. Rollen hämtar en hemlighetens del av ett certifikat. Mer information finns i följande artiklar:

  • Autentisering i Azure Key Vault
  • Använda Azure RBAC-behörigheter för hemlighet, nyckel och certifikat med Azure Key Vault
  • Nyckelvalvets omfångsrolltilldelning

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

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

Egenskapsvärden

JSON-schemat innehåller följande egenskaper.

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

Automatisk uppgradering av tillägg

Det Key Vault VM-tillägget stöder automatisk tilläggsuppgradering för virtuella datorer och skalningsuppsättningar i Azure. Tillägget hålls uppdaterat automatiskt när autoUpgradeMinorVersion egenskaperna och enableAutomaticUpgrade i föregående exempel anges till true.

Tilläggsberoendens ordning

Det Key Vault VM-tillägget stöder fältordning av tilläggsberoenden. Tillägget rapporterar en lyckad start när det har laddat ned och installerat alla certifikat.

Om du använder andra tillägg som kräver installation av certifikat innan de startas kan du använda tilläggsberoendeordning för att deklarera ett beroende av Key Vault VM-tillägget.

När den startar försöker Key Vault VM-tillägget ladda ned och installera certifikaten upp till 25 gånger med ökande återhämtningsperioder, under vilka det förblir i ett ö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.

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

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

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 "4.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 "4.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": {
          "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"
        }      
     }

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" `
 --version "4.0"

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" `
 --version "4.0"

az vm extension delete --name "KeyVaultForWindows" --resource-group "<resourcegroup>" --vm-name "<vmName>"

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?

Från och med Key Vault VM-tillägg 4.0 sparas de privata nycklarna för alla certifikat via CNG.

Stöder tillägget automatisk ombindning av certifikat?

Ja, azure Key Vault VM-tillägget stöder automatisk ombindning av certifikat. Det Key Vault VM-tillägget stöder S-kanalbindning vid certifikatförnyelse.

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. För mer information, se Ombindning av certifikat 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>
  

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

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:

1. 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
2. Placerar certifikaten i det angivna certifikatarkivet (certificateStoreName) och platsen (certificateStoreLocation)
3. Tillämpar lämpliga behörigheter på den privata nyckeln baserat på den accounts som anges i konfigurationen
4. CERT_RENEWAL Anger egenskapen 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:

1. Laddar ned den nya certifikatversionen.
2. Installerar det i det konfigurerade certifikatarkivet.
3. Underhåller befintliga bindningar via egenskapen CERT_RENEWAL .

Hantera certifikatets livscykel

För program som IIS som stöder certifikattjänsters livscykelmeddelanden genererar Key Vault VM-tillägget Event 1001 i Windows händelseloggen när ett certifikat med ett matchande alternativt ämnesnamn (SAN) installeras. IIS prenumererar på den här händelsen för att automatiskt ombinda det förnyade certifikatet utan tjänstavbrott. Andra applikationer och team kan också lyssna efter händelse 1001 för att agera på certifikatsförnyelser efter behov. Mer information finns i Livscykelmeddelanden för Certifikattjänster.

Få support

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

• Kontakta Azure experter på Microsoft Q& A.

• 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 Så här skapar du en Azure support begäran.