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 Windows Server 2019 und höher. 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

Features

Die Key Vault-VM-Erweiterung für Windows, Version 3.0, unterstützt:

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

• Eine Azure Key Vault-Instanz mit einem Zertifikat. Weitere Informationen finden Sie unter Einen Schlüsseltresor mit dem Azure-Portal erstellen.

• Eine VM mit einer zugewiesenen verwalteten Identität.

• Die Rolle Key Vault-Geheimnisbenutzer muss auf Key Vault-Bereichsebene für VMs und die verwaltete Azure Virtual Machine Scale Sets-Identität zugewiesen werden. Diese Rolle ruft den Zertifikatteil eines Geheimnisses ab. Weitere Informationen finden Sie in den folgenden Artikeln:

  • Authentifizierung in Azure Key Vault
  • Verwenden von Geheimnis-, Schlüssel- und Zertifikatberechtigungen mit Azure Key Vault
  • Rollenzuweisung im Key Vault-Bereich

• Skalierungssätze für virtuelle Computer sollten über die folgende identity Konfiguration verfügen:

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

• Die Key Vault VM-Erweiterung sollte die folgende authenticationSettings Konfiguration haben:

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

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.

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, versucht die Key Vault-VM-Erweiterung das Herunterladen und Installieren von Zertifikaten bis zu 25 Mal mit zunehmenden Backoff-Zeiträumen, während der sie in einem Übergangszustand verbleibt. Wenn alle zulässigen Wiederholungen durchgeführt wurden, meldet die Erweiterung einen Fehler-Zustand. Nachdem alle Zertifikate erfolgreich installiert wurden, 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.

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 VM

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

Zertifikatinstallation unter Windows

Die Key Vault-VM-Erweiterung für Windows installiert Zertifikate im Windows-Zertifikatspeicher. Wenn ein Zertifikat aus Key Vault heruntergeladen wird, ist die Erweiterung wie folgt:

1. Installiert alle Zwischen- und Blattzertifikate, unabhängig davon, wie viele Zwischenzertifikate vorhanden sind. Stammzertifikate sind nicht installiert, da die Erweiterung nicht berechtigt ist, die Stamminstallation durchzuführen. Es liegt in der Verantwortung des Dienstbesitzers, sicherzustellen, dass das Stammzertifikat auf dem System vertrauenswürdig ist.
   • Untergeordnete Zertifikate werden im angegebenen Zertifikatspeicher (certificateStoreName) und Speicherort (certificateStoreLocation) installiert.
   • Zertifikate von Zwischenzertifizierungsstellen werden im Speicher für Zwischenzertifizierungsstellen installiert.
2. Platziert die Zertifikate im angegebenen Zertifikatspeicher (certificateStoreName) und speicherort (certificateStoreLocation)
3. Wendet geeignete Berechtigungen auf den privaten Schlüssel basierend auf dem in der Konfiguration angegebenen accounts an.
4. Legt die linkOnRenewal Eigenschaft (sofern aktiviert) fest, um sicherzustellen, dass Zertifikatbindungen in Anwendungen wie IIS automatisch aktualisiert werden, wenn Zertifikate erneuert werden

Standardzertifikatspeicher

Wenn nicht angegeben, werden Zertifikate standardmäßig an den folgenden Speicherorten installiert:

• Speichername: MY (Persönlich)
• Speicherort: LocalMachine

Zertifikatzugriffskontrolle

Standardmäßig erhalten Administratoren und SYSTEM Vollzugriffsberechtigungen für installierte Zertifikate. Sie können den Zugriff mithilfe des accounts Arrays in der Zertifikatkonfiguration anpassen:

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

Dadurch wird Lesezugriff auf die angegebenen Konten gewährt, sodass Anwendungen, die unter diesen Identitäten ausgeführt werden, die Zertifikate verwenden können.

Zertifikatverlängerung

Wenn Zertifikate im Key Vault erneuert werden, führt die Erweiterung dies automatisch durch.

1. Lädt die neue Zertifikatversion herunter.
2. Installiert es im konfigurierten Zertifikatspeicher.
3. Verwaltet vorhandene Bindungen über das linkOnRenewal Feature, wenn diese aktiviert ist

Verwalten des Zertifikatlebenszyklus

Für Anwendungen wie IIS, die Zertifikatlebenszyklusbenachrichtigungen unterstützen, generiert die Erweiterung Ereignisse, wenn Zertifikate mit übereinstimmenden Subject Alternative Names (SANs) installiert werden, sodass eine automatische Neubindung ohne Unterbrechung des Dienstes möglich ist.

Unterstützung erhalten

Hier finden Sie einige weitere Optionen, die Ihnen bei der Behebung von Bereitstellungsproblemen helfen können:

• Über das Q&A-Forum oder das Stack Overflow-Forum können Sie sich mit Azure-Expert*innen in Verbindung setzen, um Unterstützung zu erhalten.

• Wenn Sie auf der Website keine Antwort finden, können Sie eine Frage an Microsoft oder andere Mitglieder der Community stellen.

• Sie können auch den Microsoft-Support kontaktieren. Informationen zur Nutzung von Azure-Support finden Sie unter Häufig gestellte Fragen zum Azure-Support.