Azure Key Vault-extensie voor virtuele machines voor Windows

  • Artikel

De azure Key Vault-extensie voor virtuele machines (VM's) biedt automatische vernieuwing van certificaten die zijn opgeslagen in een Azure-sleutelkluis. De extensie bewaakt een lijst met waargenomen certificaten die zijn opgeslagen in sleutelkluizen. Wanneer een wijziging wordt gedetecteerd, haalt de extensie de bijbehorende certificaten op en installeert deze. In dit artikel worden de ondersteunde platforms, configuraties en implementatieopties voor de Key Vault-VM-extensie voor Windows beschreven.

Besturingssystemen

De Key Vault VM-extensie ondersteunt de volgende versies van Windows:

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

De Key Vault VM-extensie wordt ook ondersteund op een aangepaste lokale VM. De VM moet worden geüpload en geconverteerd naar een gespecialiseerde installatiekopieën voor gebruik in Azure met behulp van windows Server 2019 core-installatie.

Ondersteunde certificaten

De Key Vault VM-extensie ondersteunt de volgende certificaatinhoudstypen:

  • PKCS #12
  • PEM

Notitie

De Key Vault-VM-extensie downloadt alle certificaten naar het Windows-certificaatarchief of naar de locatie die is opgegeven in de certificateStoreLocation eigenschap in de instellingen van de VM-extensie.

Updates in versie 3.0+

Versie 3.0 van de Key Vault VM-extensie voor Windows voegt ondersteuning toe voor de volgende functies:

  • ACL-machtigingen toevoegen aan gedownloade certificaten
  • Configuratie van certificaatarchief per certificaat inschakelen
  • Persoonlijke sleutels exporteren
  • Ondersteuning voor opnieuw koppelen van IIS-certificaten

Vereisten

Bekijk de volgende vereisten voor het gebruik van de Key Vault VM-extensie voor Windows:

  • Een Azure Key Vault-exemplaar met een certificaat. Zie Een sleutelkluis maken met behulp van Azure Portal voor meer informatie.

  • Een VM met een toegewezen beheerde identiteit.

  • De key Vault-gebruikersrol Geheimen moet worden toegewezen op het bereikniveau van Key Vault voor VM's en beheerde identiteit van Azure Virtual Machine Scale Sets. Met deze rol wordt het gedeelte van een certificaat van een geheim opgehaald. Raadpleeg voor meer informatie de volgende artikelen:

  • Virtuele-machineschaalsets moeten de volgende identity configuratie hebben:

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

  • De Key Vault-VM-extensie moet de volgende authenticationSettings configuratie hebben:

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

Notitie

Het oude machtigingsmodel voor toegangsbeleid kan ook worden gebruikt om toegang te bieden tot VM's en virtuele-machineschaalsets. Voor deze methode is beleid vereist met machtigingen voor ophalen en weergeven voor geheimen. Zie Toegangsbeleid voor Key Vault toewijzen voor meer informatie.

Extensieschema

In de volgende JSON ziet u het schema voor de Key Vault-VM-extensie. Bekijk de volgende belangrijke opmerkingen voordat u de implementatieopties voor schema's bekijkt.

  • Voor de extensie zijn geen beveiligde instellingen vereist. Alle instellingen worden beschouwd als openbare informatie.

  • De URL's van waargenomen certificaten moeten van het formulier https://myVaultName.vault.azure.net/secrets/myCertNamezijn.

    Dit formulier heeft de voorkeur omdat het /secrets pad het volledige certificaat retourneert, inclusief de persoonlijke sleutel, maar het /certificates pad niet. Zie het overzicht van Azure Key Vault-sleutels, geheimen en certificaten voor meer informatie over certificaten.

  • De authenticationSettings eigenschap is vereist voor VM's met een door de gebruiker toegewezen identiteiten.

    Met deze eigenschap geeft u de identiteit op die moet worden gebruikt voor verificatie bij Key Vault. Definieer deze eigenschap met een door het systeem toegewezen identiteit om problemen met een VM-extensie met meerdere identiteiten te voorkomen.

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

Eigenschapswaarden

Het JSON-schema bevat de volgende eigenschappen.

Naam Waarde/voorbeeld Gegevenstype
apiVersion 2022-08-01 datum
publisher Microsoft.Azure.KeyVault tekenreeks
type KeyVaultForWindows tekenreeks
typeHandlerVersion "3.0" tekenreeks
pollingIntervalInS "3600" tekenreeks
linkOnRenewal (optioneel) true boolean
requireInitialSync (optioneel) false boolean
observedCertificates [{...}, {...}] tekenreeksmatrix
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate" tekenreeks
observedCertificates/certificateStoreName MY tekenreeks
observedCertificates/certificateStoreLocation LocalMachine of CurrentUser (hoofdlettergevoelig) tekenreeks
observedCertificates/keyExportable (optioneel) false boolean
observedCertificates/accounts (optioneel) ["Netwerkservice", "Lokale service"] tekenreeksmatrix
msiEndpoint "http://169.254.169.254/metadata/identity/oauth2/token" tekenreeks
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 tekenreeks

Sjabloonimplementatie

Azure VM-extensies kunnen worden geïmplementeerd met ARM-sjablonen (Azure Resource Manager). Sjablonen zijn ideaal bij het implementeren van een of meer virtuele machines waarvoor het vernieuwen van certificaten na de implementatie is vereist. De extensie kan worden geïmplementeerd op afzonderlijke VM's of instanties van virtuele-machineschaalsets. Het schema en de configuratie zijn gebruikelijk voor beide sjabloontypen.

De JSON-configuratie voor een sleutelkluisextensie is genest in de sjabloon virtuele machine of virtuele-machineschaalsets. Voor een VM-resource-extensie is de configuratie genest onder het object van de "resources": [] virtuele machine. Voor een instantie-extensie van virtuele-machineschaalsets is de configuratie genest onder het "virtualMachineProfile":"extensionProfile":{"extensions" :[] object.

De volgende JSON-fragmenten bevatten voorbeeldinstellingen voor een ARM-sjabloonimplementatie van de Key Vault-VM-extensie.

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

Volgorde van uitbreidingsafhankelijkheid

U kunt de Key Vault-VM-extensie inschakelen ter ondersteuning van de volgorde van uitbreidingsafhankelijkheid. De Key Vault VM-extensie rapporteert standaard een geslaagde start zodra de polling begint. U kunt de extensie echter alleen configureren om een geslaagde start te rapporteren nadat de extensie alle certificaten heeft gedownload en geïnstalleerd.

Als u andere extensies gebruikt waarvoor installatie van alle certificaten is vereist voordat ze worden gestart, kunt u de volgorde van uitbreidingsafhankelijkheid inschakelen in de Key Vault VM-extensie. Met deze functie kunnen andere extensies een afhankelijkheid van de Key Vault-VM-extensie declareren.

U kunt deze functie gebruiken om te voorkomen dat andere extensies worden gestart totdat alle afhankelijke certificaten zijn geïnstalleerd. Wanneer de functie is ingeschakeld, probeert de Key Vault VM-extensie voor onbepaalde tijd certificaten te downloaden en te installeren en blijft deze in een overgangsstatus staan totdat alle certificaten zijn geïnstalleerd. Nadat alle certificaten aanwezig zijn, rapporteert de Key Vault VM-extensie een geslaagde start.

Als u de functie voor het ordenen van extensies in de Key Vault-VM-extensie wilt inschakelen, stelt u de secretsManagementSettings eigenschap in:

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

Zie Inrichting van reeksuitbreidingen in virtuele-machineschaalsets voor meer informatie over het instellen van afhankelijkheden tussen extensies.

Belangrijk

De functie voor het ordenen van uitbreidingsafhankelijkheid is niet compatibel met een ARM-sjabloon waarmee een door het systeem toegewezen identiteit wordt gemaakt en een Key Vault-toegangsbeleid met die identiteit wordt bijgewerkt. Als u de functie in dit scenario probeert te gebruiken, treedt er een impasse op omdat het Key Vault-toegangsbeleid pas kan worden bijgewerkt nadat alle extensies zijn gestart. Gebruik in plaats daarvan een door de gebruiker toegewezen MSI-identiteit en vooraf ACL uw sleutelkluizen met die identiteit voordat u implementeert.

Azure PowerShell-implementatie

De AZURE Key Vault VM-extensie kan worden geïmplementeerd met Azure PowerShell. Sla de instellingen van de Key Vault-VM-extensie op in een JSON-bestand (settings.json).

De volgende JSON-fragmenten bevatten voorbeeldinstellingen voor het implementeren van de Key Vault VM-extensie met 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"
   }      
}

Implementeren op een VIRTUELE machine

# 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

Implementeren op een exemplaar van virtuele-machineschaalsets

# 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

Implementatie van Azure CLI

De Azure Key Vault-VM-extensie kan worden geïmplementeerd met behulp van de Azure CLI. Sla de instellingen van de Key Vault-VM-extensie op in een JSON-bestand (settings.json).

De volgende JSON-fragmenten bevatten voorbeeldinstellingen voor het implementeren van de Key Vault VM-extensie met de 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"
        }      
     }

Implementeren op een VIRTUELE machine

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

Implementeren op een exemplaar van virtuele-machineschaalsets

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

Problemen oplossen

Hier volgen enkele suggesties voor het oplossen van implementatieproblemen.

Raadpleeg veelgestelde vragen

Is er een limiet voor het aantal waargenomen certificaten?

Nee De Key Vault VM-extensie beperkt het aantal waargenomen certificaten (observedCertificates) niet.

Wat is de standaardmachtiging wanneer er geen account is opgegeven?

Standaard ontvangen Beheer istrators en SYSTEM Volledig beheer.

Hoe bepaalt u of een certificaatsleutel CAPI1 of CNG is?

De extensie is afhankelijk van het standaardgedrag van de PFXImportCertStore-API. Als een certificaat standaard een kenmerk Provider Name heeft dat overeenkomt met CAPI1, wordt het certificaat geïmporteerd met behulp van CAPI1-API's. Anders wordt het certificaat geïmporteerd met behulp van CNG-API's.

Ondersteunt de extensie automatisch opnieuw koppelen van certificaten?

Ja, de VM-extensie van Azure Key Vault biedt ondersteuning voor automatisch koppelen van certificaten. De Key Vault VM-extensie biedt ondersteuning voor S-channel-binding bij certificaatvernieuwing wanneer de linkOnRenewal eigenschap is ingesteld op waar.

Voor IIS kunt u automatisch opnieuw koppelen configureren door automatische herbinding van certificaatvernieuwingen in IIS in te schakelen. De VM-extensie van Azure Key Vault genereert meldingen over de levenscyclus van certificaten wanneer een certificaat met een overeenkomend SAN is geïnstalleerd. IIS gebruikt deze gebeurtenis om het certificaat automatisch opnieuw te koppelen. Zie Certifcate Rebind in IIS voor meer informatie

Extensiestatus weergeven

Controleer de status van uw extensie-implementatie in Azure Portal of met behulp van PowerShell of de Azure CLI.

Voer de volgende opdrachten uit om de implementatiestatus van extensies voor een bepaalde VIRTUELE machine te zien.

  • Azure PowerShell:

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

  • De Azure CLI:

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

Logboeken en configuratie controleren

De Key Vault VM-extensielogboeken bestaan alleen lokaal op de virtuele machine. Bekijk de logboekdetails voor hulp bij het oplossen van problemen.

Logboekbestand Beschrijving
C:\WindowsAzure\Logs\WaAppAgent.log' Geeft weer wanneer er updates worden uitgevoerd voor de extensie.
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<meest recente versie>\ Geeft de status weer van het downloaden van certificaten. De downloadlocatie is altijd de MY-winkel van de Windows-computer (certlm.msc).
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<meest recente versie>\Runtime Instellingen\ In de logboeken van de Key Vault VM-extensieservice wordt de status van de akvvm_service-service weergegeven.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<meest recente versie>\Status\ De configuratie en binaire bestanden voor de Key Vault VM-extensieservice.

Support krijgen

Hier volgen enkele andere opties om u te helpen bij het oplossen van implementatieproblemen:

  • Neem voor hulp contact op met de Azure-experts op de Q&A- en Stack Overflow-forums.

  • Als u geen antwoord op de site vindt, kunt u een vraag plaatsen voor invoer van Microsoft of andere leden van de community.

  • U kunt ook contact opnemen met Microsoft Ondersteuning. Lees de veelgestelde vragen over het gebruik van ondersteuning voor Azure voor meer informatie over het gebruik van ondersteuning voor Azure ondersteuning voor Azure.