Freigeben über

Azure Key Vault-VM-Erweiterung für Windows

Die Azure Key Vault Virtual Machine (VM)-Erweiterung bietet eine automatische Aktualisierung von Zertifikaten, die in einem Azure Key Vault gespeichert sind. Die Erweiterung überwacht eine Liste der in Schlüsseltresoren gespeicherten, berücksichtigten Zertifikate. Wenn eine Änderung erkannt wird, ruft die Erweiterung die entsprechenden Zertifikate ab und installiert sie. In diesem Artikel werden die unterstützten Plattformen, Konfigurationen und Bereitstellungsoptionen für die Key Vault-VM-Erweiterung für Windows beschrieben.

Betriebssysteme

Die Key Vault-VM-Erweiterung unterstützt die folgenden Versionen von Windows:

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

Die Key Vault-VM-Erweiterung wird auch auf einer benutzerdefinierten lokalen VM unterstützt. Der virtuelle Computer sollte mithilfe der Windows Server 2019-Kerninstallation in ein spezielles Image für die Verwendung in Azure hochgeladen und konvertiert werden.

Unterstützte Zertifikate

Die Vm-Erweiterung Key Vault unterstützt die folgenden Zertifikatinhaltstypen:

  • PKCS #12
  • PEM

Hinweis

Die Key Vault-VM-Erweiterung lädt alle Zertifikate in den Windows-Zertifikatspeicher oder an den Speicherort herunter, der in der Eigenschaft in den certificateStoreLocation VM-Erweiterungseinstellungen angegeben ist.

Aktualisierungen in Version 3.0+

Version 3.0 der Key Vault-VM-Erweiterung für Windows bietet Unterstützung für die folgenden Features:

  • Hinzufügen von ACL-Berechtigungen zu heruntergeladenen Zertifikaten
  • Aktivieren der Zertifikatspeicherkonfiguration pro Zertifikat
  • Exportieren privater Schlüssel
  • Unterstützung für die erneute Bindung von IIS-Zertifikaten

Voraussetzungen

Überprüfen Sie die folgenden Voraussetzungen für die Verwendung der Key Vault-VM-Erweiterung für Windows:

Hinweis

Das alte Zugriffsrichtlinienberechtigungsmodell kann auch verwendet werden, um Zugriff auf VMs und VM Scale Sets bereitzustellen. Für diese Methode ist eine Richtlinie mit get- und list-Berechtigungen für Geheimnisse erforderlich. Weitere Informationen finden Sie unter Zuweisen einer Zugriffsrichtlinie für den Schlüsseltresor.

Erweiterungsschema

Im folgenden JSON-Code ist das Schema für die Key Vault-VM-Erweiterung dargestellt. Bevor Sie die Schemaimplementierungsoptionen berücksichtigen, lesen Sie die folgenden wichtigen Hinweise.

  • Für die Erweiterung sind keine geschützten Einstellungen erforderlich. Alle Einstellungen werden als öffentliche Informationen betrachtet.

  • Beobachtete Zertifikat-URLs sollten dem Formular https://myVaultName.vault.azure.net/secrets/myCertNamezugeordnet sein.

    Dieses Formular wird bevorzugt, da der /secrets Pfad das vollständige Zertifikat zurückgibt, einschließlich des privaten Schlüssels, aber /certificates der Pfad nicht. Weitere Informationen zu Zertifikaten finden Sie unter Azure Key Vault-Schlüssel, Geheimschlüssel und Zertifikatübersicht.

  • Die authenticationSettings Eigenschaft ist für VMs mit allen vom Benutzer zugewiesenen Identitätenerforderlich.

    Diese Eigenschaft gibt die Identität an, die für die Authentifizierung für Key Vault verwendet werden soll. Definieren Sie diese Eigenschaft mit einer vom System zugewiesenen Identität, um Probleme mit einer VM-Erweiterung mit mehreren Identitäten zu vermeiden.

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

Immobilienwerte

Das JSON-Schema enthält die folgenden Eigenschaften.

Name Beispiel/Wert Datentyp
apiVersion 01.08.2022 Datum
publisher Microsoft.Azure.KeyVault Schnur
type KeyVaultForWindows Schnur
typeHandlerVersion "3.0" Schnur
pollingIntervalInS "3600" Schnur
linkOnRenewal (wahlweise) Wahr Boolescher Wert
requireInitialSync (wahlweise) Falsch Boolescher Wert
observedCertificates [{...}, {...}] Zeichenfolgenarray
observedCertificates/url „https://myvault.vault.azure.net/secrets/mycertificate" Schnur
observedCertificates/certificateStoreName MEIN Schnur
observedCertificates/certificateStoreLocation LocalMachine oder CurrentUser (Groß-/Kleinschreibung beachten) Schnur
observedCertificates/keyExportable (wahlweise) Falsch Boolescher Wert
observedCertificates/accounts (wahlweise) ["Netzwerkdienst"; "Lokaler Dienst"] Zeichenfolgenarray
msiEndpoint „http://169.254.169.254/metadata/identity/oauth2/token" Schnur
msiClientId 00001111-aaaa-2222-bbbb-3333cccc44444 Schnur

Bereitstellung von Vorlagen

Azure VM-Erweiterungen können mithilfe von Azure Resource Manager-Vorlagen (ARM-Vorlagen) bereitgestellt werden. Vorlagen sind ideal, wenn Sie virtuelle Computer bereitstellen, für die nach der Bereitstellung eine Aktualisierung der Zertifikate erforderlich ist. Die Erweiterung kann auf einzelne VMs oder Instanzen von Virtual Machine Scale Sets bereitgestellt werden. Das Schema und die Konfiguration sind für beide Vorlagentypen gleich.

Die JSON-Konfiguration für eine Key Vault-Erweiterung ist in der VM- oder Virtual Machine Scale Sets-Vorlage eingebettet. Bei einer VM-Ressourcenerweiterung wird die Konfiguration unter dem Objekt des "resources": [] virtuellen Computers geschachtelt. Bei einer Instanzerweiterung von Virtual Machine Scale Sets wird die Konfiguration unter dem "virtualMachineProfile":"extensionProfile":{"extensions" :[]-Objekt verschachtelt.

Die folgenden JSON-Codeausschnitte stellen Beispieleinstellungen für eine ARM-Vorlagenbereitstellung der Key Vault-VM-Erweiterung bereit.

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

Reihenfolge von Erweiterungsabhängigkeiten

Sie können die Vm-Erweiterung Key Vault aktivieren, um die Sortierung von Abhängigkeitserweiterungen zu unterstützen. Standardmäßig meldet die Key Vault-VM-Erweiterung einen erfolgreichen Start, sobald die Abfrage beginnt. Sie können die Erweiterung jedoch so konfigurieren, dass ein erfolgreicher Start erst nach dem Herunterladen der Erweiterung und der Installation aller Zertifikate angezeigt wird.

Wenn Sie andere Erweiterungen verwenden, die erfordern, dass alle Zertifikate installiert sind, bevor sie ausgeführt werden, können Sie die Abhängigkeitsreihenfolge der Erweiterungen in der Key Vault-VM-Erweiterung aktivieren. Dieses Feature ermöglicht es anderen Erweiterungen, eine Abhängigkeit von der Key Vault-VM-Erweiterung zu deklarieren.

Sie können dieses Feature verwenden, um zu verhindern, dass andere Erweiterungen gestartet werden, bis alle abhängigen Zertifikate installiert sind. Wenn das Feature aktiviert ist, wiederholt die Vm-Erweiterung Key Vault das Herunterladen und Installieren von Zertifikaten auf unbestimmte Zeit und verbleibt in einem Übergangszustand , bis alle Zertifikate erfolgreich installiert wurden. Nachdem alle Zertifikate vorhanden sind, meldet die Key Vault-VM-Erweiterung einen erfolgreichen Start.

Legen Sie die secretsManagementSettings Eigenschaft fest, um die Erweiterungsabhängigkeits-Sortierungsfunktion in der Vm-Erweiterung Key Vault zu aktivieren:

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

Weitere Informationen zum Einrichten von Abhängigkeiten zwischen Erweiterungen finden Sie unter Bereitstellung der Sequenz-Erweiterung in virtuellen Computer-Skalierungssätzen.

Von Bedeutung

Die Erweiterungsabhängigkeits-Sortierungsfunktion ist nicht mit einer ARM-Vorlage kompatibel, die eine vom System zugewiesene Identität erstellt und eine Key Vault-Zugriffsrichtlinie mit dieser Identität aktualisiert. Wenn Sie versuchen, das Feature in diesem Szenario zu verwenden, tritt ein Deadlock auf, da die Key Vault-Zugriffsrichtlinie erst aktualisiert werden kann, nachdem alle Erweiterungen gestartet wurden. Verwenden Sie stattdessen eine einzelne benutzerseitig zugewiesene MSI-Identität, und wenden Sie vor der Bereitstellung eine Zugriffssteuerungsliste mit dieser Identität auf Ihre Schlüsseltresore an.

Azure PowerShell-Bereitstellung

Die Azure Key Vault-VM-Erweiterung kann mit Azure PowerShell bereitgestellt werden. Speichern Sie die Key Vault-VM-Erweiterungseinstellungen in einer JSON-Datei (settings.json).

Die folgenden JSON-Codeschnipsel enthalten Beispieleinstellungen für die Bereitstellung der Key Vault-VM-Erweiterung mit 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"
   }      
}

Bereitstellen auf einer VM

# 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

Bereitstellen in einer Virtual Machine Scale Sets-Instanz

# 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

Bereitstellung mithilfe der Azure-Befehlszeilenschnittstelle

Die Azure Key Vault-VM-Erweiterung kann mit der Azure CLI bereitgestellt werden. Speichern Sie die Key Vault-VM-Erweiterungseinstellungen in einer JSON-Datei (settings.json).

Die folgenden JSON-Codeschnipsel enthalten Beispieleinstellungen für die Bereitstellung der Key Vault-VM-Erweiterung mit der 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"
        }      
     }

Bereitstellen auf einer virtuellen Maschine

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

Bereitstellen in einer Virtual Machine Scale Sets-Instanz

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

Probleme beheben

Hier finden Sie einige Vorschläge für die Behandlung von Bereitstellungsproblemen.

Häufig gestellte Fragen überprüfen

Gibt es eine Beschränkung der Anzahl beobachteter Zertifikate?

Nein. Die Vm-Erweiterung "Key Vault" beschränkt nicht die Anzahl der beobachteten Zertifikate (observedCertificates).

Was ist die Standardberechtigung, wenn kein Konto angegeben wird?

Standardmäßig erhalten Administratoren und SYSTEM vollzugriff.

Wie bestimmen Sie, ob ein Zertifikatschlüssel CAPI1 oder CNG ist?

Die Erweiterung basiert auf dem Standardverhalten der PFXImportCertStore-API. Wenn ein Zertifikat standardmäßig über ein Anbieternamen-Attribut verfügt, das mit CAPI1 übereinstimmt, wird das Zertifikat mithilfe von CAPI1-APIs importiert. Andernfalls wird das Zertifikat mithilfe von CNG-APIs importiert.

Unterstützt die Erweiterung die automatische Neubindung des Zertifikats?

Ja, die Azure Key Vault-VM-Erweiterung unterstützt die automatische Neubindung von Zertifikaten. Die Vm-Erweiterung Key Vault unterstützt die S-Kanalbindung bei der Zertifikatverlängerung, wenn die linkOnRenewal Eigenschaft auf "true" festgelegt ist.

Für IIS können Sie die automatische Neubindung konfigurieren, indem Sie die automatische Neubindung von Zertifikatverlängerungen in IIS aktivieren. Die Azure Key Vault-VM-Erweiterung generiert Zertifikatlebenszyklusbenachrichtigungen, wenn ein Zertifikat mit einem übereinstimmenden SAN installiert wird. IIS verwendet dieses Ereignis, um das Zertifikat automatisch neu zu binden. Weitere Informationen finden Sie unter Certifcate Rebind in IIS

Anzeigen des Erweiterungsstatus

Überprüfen Sie den Status Ihrer Erweiterungsbereitstellung im Azure-Portal oder mithilfe von PowerShell oder der Azure CLI.

Führen Sie den folgenden Befehl aus, um den Bereitstellungsstatus von Erweiterungen für eine bestimmte VM anzuzeigen.

  • Azure PowerShell:

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

  • Die Azure CLI:

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

Überprüfen von Protokollen und Konfigurationen

Die Key Vault-VM-Erweiterungsprotokolle sind nur lokal auf der VM vorhanden. Überprüfen Sie die Protokolldetails, um hilfe bei der Problembehandlung zu erhalten.

Protokolldatei BESCHREIBUNG
C:\WindowsAzure\Logs\WaAppAgent.log' Zeigt an, wann Aktualisierungen an der Erweiterung vorgenommen werden.
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<neueste Version>\ Zeigt den Status des Zertifikatdownloads an. Der Speicherort für den Download ist immer der persönliche Windows-Speicher („certlm.msc“) des Computers.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<neueste Version>\RuntimeSettings\ Die Key Vault-VM-Erweiterungsdienstprotokolle zeigen den Status des Diensts „akvvm_service“ an.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<neueste Version>\Status\ Die Konfiguration und Binärdateien für den Key Vault-VM-Erweiterungsdienst.

Unterstützung erhalten

Im Folgenden finden Sie einige weitere Optionen, mit denen Sie Bereitstellungsprobleme beheben können: