Azure Key Vault-VM-Erweiterung für Windows

  • Artikel

Die Key Vault-VM-Erweiterung ermöglicht automatische Aktualisierung von Zertifikaten, die in einer Azure Key Vault-Instanz 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. Die VM sollte hochgeladen und in ein spezielles Image für die Verwendung in Azure konvertiert werden, indem die Windows Server 2019-Basisinstallation verwendet wird.

Unterstützte Zertifikate

Die Key Vault-VM-Erweiterung 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 certificateStoreLocation-Eigenschaft in den Einstellungen der VM-Erweiterung angegeben wurde.

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:

  • Eine Azure Key Vault-Instanz mit einem Zertifikat. Weitere Informationen finden Sie unter Erstellen eines Schlüsseltresors im Azure-Portal.

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

  • Virtual Machine Scale Sets sollte die folgende identity-Konfiguration aufweisen:

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

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

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

Hinweis

Das alte Zugriffsrichtlinien-Berechtigungsmodell kann auch verwendet werden, um Zugriff auf VMs und Virtual Machine Scale Sets zu ermöglichen. Diese Methode erfordert eine Richtlinie mit get- und list-Berechtigungen für Geheimnisse. Weitere Informationen finden Sie unter Zuweisen einer Key Vault-Zugriffsrichtlinie.

Erweiterungsschema

Im folgenden JSON-Code ist das Schema für die Key Vault-VM-Erweiterung dargestellt. Bevor Sie die Optionen für die Schemaimplementierung in Betracht ziehen, lesen Sie die folgenden wichtigen Hinweise.

  • Die Erweiterung erfordert keine geschützten Einstellungen. Alle Einstellungen werden als öffentliche Informationen betrachtet.

  • Die URLs der berücksichtigten Zertifikate müssen das folgende Format aufweisen: https://myVaultName.vault.azure.net/secrets/myCertName.

    Dieses Format wird bevorzugt, weil der Pfad /secrets das vollständige Zertifikat einschließlich des privaten Schlüssels zurückgibt, der Pfad /certificates hingegen nicht. Weitere Informationen zu Zertifikaten finden Sie in der Übersicht über Schlüssel, Geheimnisse und Zertifikate in Azure Key Vault.

  • Die authenticationSettings-Eigenschaft ist erforderlich, wenn Sie VMs mit beliebigen benutzerseitig zugewiesenen Identitäten verwenden.

    Diese Eigenschaft gibt die Identität an, die für die Authentifizierung bei Key Vault verwendet werden soll. Definieren Sie diese Eigenschaft mit einer systemseitig 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:  "c7373ae5-91c2-4165-8ab6-7381d6e75619">
         }
      }
   }
}

Eigenschaftswerte

Das JSON-Schema enthält die folgenden Eigenschaften.

Name Beispiel/Wert Datentyp
apiVersion 01.08.2022 date
publisher Microsoft.Azure.KeyVault Zeichenfolge
type KeyVaultForWindows Zeichenfolge
typeHandlerVersion "3.0" Zeichenfolge
pollingIntervalInS "3600" Zeichenfolge
linkOnRenewal (optional) true boolean
requireInitialSync (optional) false boolean
observedCertificates [{...}, {...}] Zeichenfolgenarray
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate" Zeichenfolge
observedCertificates/certificateStoreName MY Zeichenfolge
observedCertificates/certificateStoreLocation LocalMachine oder CurrentUser (Groß-/Kleinschreibung beachten) Zeichenfolge
observedCertificates/keyExportable (optional) false boolean
observedCertificates/accounts (optional) ["Netzwerkdienst", "Lokaler Dienst"] Zeichenfolgenarray
msiEndpoint "http://169.254.169.254/metadata/identity/oauth2/token" Zeichenfolge
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 Zeichenfolge

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 einzelnen VMs oder in Virtual Machine Scale Sets-Instanzen bereitgestellt werden. Das Schema und die Konfiguration sind für beide Vorlagentypen gleich.

Die JSON-Konfiguration für eine Schlüsseltresorerweiterung ist in der Vorlage für VMs oder Virtual Machine Scale Sets geschachtelt. Bei einer VM-Ressourcenerweiterung wird die Konfiguration unter dem Objekt "resources": [] der VM geschachtelt. Bei einer Virtual Machine Scale Sets-Instanzerweiterung wird die Konfiguration unter dem "virtualMachineProfile":"extensionProfile":{"extensions" :[]-Objekt geschachtelt.

Die folgenden JSON-Codeschnipsel enthalten Beispieleinstellungen für eine ARM-Vorlagenbereitstellung der Key Vault-VM-Erweiterung.

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

Reihenfolge von Erweiterungsabhängigkeiten

Sie können die Key Vault VM-Erweiterung aktivieren, um eine Reihenfolge von Erweiterungsabhängigkeiten zu unterstützen. Standardmäßig meldet die Key Vault-VM-Erweiterung einen erfolgreichen Start, sobald der Abruf beginnt. Sie können die Erweiterung jedoch so konfigurieren, dass erst ein erfolgreicher Start gemeldet wird, nachdem die Erweiterung alle Zertifikate heruntergeladen und installiert hat.

Wenn Sie andere Erweiterungen verwenden, die die Installation aller Zertifikate erfordern, bevor sie gestartet werden, können Sie die Reihenfolge von Erweiterungsabhängigkeiten 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, bevor alle abhängigen Zertifikate installiert wurden. Wenn das Feature aktiviert ist, wiederholt die Key Vault VM-Erweiterung die Versuche zum 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 das Feature für die Reihenfolge von Erweiterungen in der Key Vault-VM-Erweiterung zu aktivieren:

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

Weitere Informationen zum Festlegen von Abhängigkeiten zwischen Erweiterungen finden Sie unter Sequenzielle Bereitstellung von Erweiterungen in Virtual Machine Scale Sets.

Wichtig

Das Feature für die Reihenfolge von Erweiterungen ist nicht mit einer ARM-Vorlage kompatibel, die eine systemseitig 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, weil 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":  "c7373ae5-91c2-4165-8ab6-7381d6e75619"
   }      
}

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":  "c7373ae5-91c2-4165-8ab6-7381d6e75619"
        }      
     }

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"

Behandeln von Problemen

Hier finden Sie einige Vorschläge zur Behandlung von Bereitstellungsproblemen.

Überprüfen häufig gestellter Fragen

Gibt es eine Beschränkung für die Anzahl der berücksichtigten Zertifikate?

Nein. Die Key Vault-VM-Erweiterung weist keinen Grenzwert für die Anzahl der berücksichtigten Zertifikate (observedCertificates) auf.

Wie lautet die Standardberechtigung, wenn kein Konto angegeben wird?

Standardmäßig erhalten Administratoren und SYSTEM Vollzugriff.

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

Die Erweiterung basiert auf dem Standardverhalten der PFXImportCertStore-API. Wenn ein Zertifikat ein Attribut „Provider Name“ (Anbietername) aufweist, das mit CAPI1 übereinstimmt, wird das Zertifikat standardmäßig mithilfe der CAPI1-APIs importiert. Andernfalls wird das Zertifikat mithilfe von CNG-APIs importiert.

Unterstützt die Erweiterung die automatische Neubindung von Zertifikaten?

Ja, die Erweiterung für Azure Key Vault-VMs unterstützt die automatische Neubindung von Zertifikaten. Die Erweiterung für Key Vault-VMs unterstützt die S-Kanalbindung bei der Zertifikaterneuerung, wenn die Eigenschaft linkOnRenewal auf „TRUE“ festgelegt ist.

Für Internetinformationsdienste (Internet Information Services, IIS) können Sie die automatische Neubindung konfigurieren, indem Sie die automatische Neubindung von Zertifikaterneuerungen in IIS aktivieren. Die Erweiterung für Azure Key Vault-VMs generiert Lebenszyklusbenachrichtigungen für Zertifikate, wenn ein Zertifikat mit einem entsprechenden SAN (Storage Area Network) installiert wird. IIS verwendet dieses Ereignis zum automatischen Neubinden des Zertifikats. Weitere Informationen finden Sie unter Neubinden von Zertifikaten 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>

  • Azure CLI:

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

Überprüfen von Protokollen und der Konfiguration

Die Key Vault-VM-Erweiterungsprotokolle sind nur lokal auf der VM vorhanden. Überprüfen Sie die Protokolldetails, die Sie bei der Problembehandlung unterstützen.

Protokolldatei BESCHREIBUNG
C:\WindowsAzure\Logs\WaAppAgent.log` Zeigt an, wenn Updates für die Erweiterung erfolgen.
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 Konfigurations- und die Binärdateien für den Key Vault-VM-Erweiterungsdienst.

Support

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