Расширение виртуальной машины Azure Key Vault для Windows

  • Статья

Расширение виртуальной машины Azure Key Vault обеспечивает автоматическое обновление сертификатов, хранящихся в хранилище ключей Azure. Расширение отслеживает список наблюдаемых сертификатов, хранящихся в хранилищах ключей. При обнаружении изменения расширение извлекает и устанавливает соответствующие сертификаты. В этой статье описываются поддерживаемые платформы, конфигурации и варианты развертывания для расширения виртуальной машины Key Vault для Windows.

Операционные системы

Расширение виртуальной машины Key Vault поддерживает следующие версии Windows:

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

Расширение виртуальной машины Key Vault также поддерживается на пользовательской локальной виртуальной машине. Виртуальная машина должна быть отправлена и преобразована в специализированный образ для использования в Azure с помощью основной установки Windows Server 2019.

Поддерживаемые сертификаты

Расширение виртуальной машины Key Vault поддерживает следующие типы контента сертификата:

  • PKCS #12
  • PEM

Примечание.

Расширение виртуальной машины Key Vault загружает все сертификаты в хранилище сертификатов Windows или в расположение, указанное в certificateStoreLocation свойстве в параметрах расширения виртуальной машины.

Обновления в версии 3.0+

Версия 3.0 расширения виртуальной машины Key Vault для Windows добавляет поддержку следующих функций:

  • Добавление разрешений ACL для скачанных сертификатов
  • Включение конфигурации хранилища сертификатов для каждого сертификата
  • Экспорт закрытых ключей
  • Поддержка повторной привязки сертификата IIS

Необходимые компоненты

Ознакомьтесь со следующими предварительными условиями для использования расширения виртуальной машины Key Vault для Windows:

Примечание.

Старую модель разрешений политики доступа можно также использовать для предоставления доступа к виртуальным машинам и Масштабируемые наборы виртуальных машин. Для этого метода требуется политика с разрешениями на получение и перечисление секретов. Подробнее см. в статье Назначение политики доступа Key Vault.

Схема расширения

В следующем JSON-файле показана схема для расширения виртуальной машины Key Vault. Прежде чем рассмотреть варианты реализации схемы, ознакомьтесь со следующими важными заметками.

  • Для расширения не требуются защищенные параметры. Все параметры считаются общедоступными.

  • URL-адреса наблюдаемых сертификатов должны иметь форму https://myVaultName.vault.azure.net/secrets/myCertName.

    Эта форма предпочтительна, так как /secrets путь возвращает полный сертификат, включая закрытый ключ, но /certificates путь не выполняется. Дополнительные сведения о сертификатах см. в обзоре ключей, секретов и сертификатов Azure Key Vault.

  • Это authenticationSettings свойство требуетсядля виртуальных машин с удостоверениями, назначенными пользователем.

    Это свойство указывает удостоверение, используемое для проверки подлинности в Key Vault. Определите это свойство с удостоверением, назначаемым системой, чтобы избежать проблем с расширением виртуальной машины с несколькими удостоверениями.

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

Значения свойств

Схема JSON содержит следующие свойства.

Имя. Значение или пример Тип данных
apiVersion 2022-08-01 Дата
publisher Microsoft.Azure.KeyVault строка
type KeyVaultForWindows строка
typeHandlerVersion "3.0" строка
pollingIntervalInS "3600" строка
linkOnRenewal (необязательно) true boolean
requireInitialSync (необязательно) false boolean
observedCertificates [{...}, {...}] строка массив
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate" строка
observedCertificates/certificateStoreName MY строка
observedCertificates/certificateStoreLocation LocalMachine или CurrentUser (с учетом регистра) строка
observedCertificates/keyExportable (необязательно) false boolean
observedCertificates/accounts (необязательно) ["Сетевая служба", "Локальная служба"] строка массив
msiEndpoint "http://169.254.169.254/metadata/identity/oauth2/token" строка
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 строка

Развертывание шаблона

Расширения виртуальных машин Azure можно развернуть с помощью шаблонов Azure Resource Manager (ARM). Шаблоны идеально подходят для развертывания одной или нескольких виртуальных машин, требующих обновления сертификатов, выполняемого после развертывания. Расширение можно развернуть на отдельных виртуальных машинах или Масштабируемые наборы виртуальных машин экземплярах. Для обоих типов шаблонов используются общие схема и конфигурация.

Конфигурация JSON для расширения хранилища ключей вложена в шаблон виртуальной машины или Масштабируемые наборы виртуальных машин. Для расширения ресурсов виртуальной машины конфигурация вложена в объект виртуальной "resources": [] машины. Для расширения экземпляра Масштабируемые наборы виртуальных машин конфигурация вложена в "virtualMachineProfile":"extensionProfile":{"extensions" :[] объект.

В следующих фрагментах КОДА JSON приведены примеры параметров для развертывания шаблона ARM расширения виртуальной машины Key Vault.

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

Порядок зависимостей расширения

Вы можете включить расширение виртуальной машины Key Vault для поддержки порядка зависимостей расширений. По умолчанию расширение виртуальной машины Key Vault сообщает об успешном запуске сразу после начала опроса. Однако вы можете настроить расширение, чтобы сообщить об успешном запуске только после скачивания расширения и установки всех сертификатов.

Если вы используете другие расширения, требующие установки всех сертификатов перед их запуском, вы можете включить порядок зависимостей расширения в расширении виртуальной машины Key Vault. Эта функция позволяет другим расширениям объявлять зависимость от расширения виртуальной машины Key Vault.

Эту функцию можно использовать для предотвращения запуска других расширений до тех пор, пока не будут установлены все зависимые сертификаты. Если эта функция включена, расширение виртуальной машины Key Vault повторяет скачивание и установку сертификатов на неопределенный срок и остается в состоянии перехода до тех пор, пока все сертификаты не будут успешно установлены. После того как все сертификаты присутствуют, расширение виртуальной машины Key Vault сообщает об успешном запуске.

Чтобы включить функцию упорядочивания зависимостей расширения в расширении виртуальной машины Key Vault, задайте secretsManagementSettings свойство:

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

Дополнительные сведения о настройке зависимостей между расширениями см. в Масштабируемые наборы виртуальных машин подготовке расширения последовательности.

Важно!

Функция упорядочения зависимостей расширения несовместима с шаблоном ARM, который создает удостоверение, назначаемое системой, и обновляет политику доступа Key Vault с этим удостоверением. Если вы пытаетесь использовать эту функцию в этом сценарии, взаимоблокировка возникает, так как политика доступа к Key Vault не может обновляться до тех пор, пока все расширения не начнутся. Вместо этого перед развертыванием используйте удостоверение MSI , назначаемое одним пользователем, и пред ACL хранилища ключей с этим удостоверением.

Развертывание с помощью Azure PowerShell

Расширение виртуальной машины Azure Key Vault можно развернуть с помощью Azure PowerShell. Сохраните параметры расширения виртуальной машины Key Vault в JSON-файл (settings.json).

В следующих фрагментах JSON приведены примеры параметров для развертывания расширения виртуальной машины Key Vault с помощью 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"
   }      
}

Развертывание на виртуальной машине

# 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

Развертывание в экземпляре Масштабируемые наборы виртуальных машин

# 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

Развертывание с помощью Azure CLI

Расширение виртуальной машины Azure Key Vault можно развернуть с помощью Azure CLI. Сохраните параметры расширения виртуальной машины Key Vault в JSON-файл (settings.json).

В следующих фрагментах JSON приведены примеры параметров для развертывания расширения виртуальной машины Key Vault с помощью 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"
        }      
     }

Развертывание на виртуальной машине

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

Развертывание в экземпляре Масштабируемые наборы виртуальных машин

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

Устранение неполадок

Ниже приведены некоторые рекомендации по устранению неполадок с развертыванием.

Проверка часто задаваемых вопросов

Существует ли ограничение на количество наблюдаемых сертификатов?

№ Расширение виртуальной машины Key Vault не ограничивает количество наблюдаемых сертификатов (observedCertificates).

Что такое разрешение по умолчанию, если учетная запись не указана?

По умолчанию Администратор istrator и SYSTEM получают полный доступ.

Как определить, является ли ключ сертификата CAPI1 или CNG?

Расширение зависит от поведения API PFXImportCertStore по умолчанию. По умолчанию, если сертификат имеет атрибут "Имя поставщика", соответствующий CAPI1, сертификат импортируется с помощью API CAPI1. В противном случае сертификат импортируется с помощью API CNG.

Поддерживает ли расширение автоматическое связывание сертификатов?

Да, расширение виртуальной машины Azure Key Vault поддерживает автоматическую привязку сертификатов. Расширение виртуальной машины Key Vault поддерживает привязку S-канала при обновлении сертификата, если linkOnRenewal свойство имеет значение true.

Для СЛУЖБ IIS можно настроить автоматическую привязку, включив автоматическое повторное связывание обновлений сертификатов в IIS. Расширение виртуальной машины Azure Key Vault создает уведомления о жизненном цикле сертификатов при установке сертификата с соответствующим san. Служба IIS использует это событие для автоматической привязки сертификата. Дополнительные сведения см. в разделе Certifcate Rebind в IIS

Просмотр состояния расширения

Проверьте состояние развертывания расширения в портал Azure или с помощью PowerShell или Azure CLI.

Чтобы просмотреть состояние развертывания расширений для данной виртуальной машины, выполните следующие команды.

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

Просмотр журналов и конфигурации

Журналы расширений виртуальной машины Key Vault существуют только локально на виртуальной машине. Просмотрите сведения о журнале, чтобы помочь в устранении неполадок.

Файл журнала Description
C:\WindowsAzure\Logs\WaAppAgent.log' Показывает, когда обновления происходят в расширении.
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<самая последняя версия>\ Показывает состояние загрузки сертификата. Расположение скачивания всегда является хранилищем MY компьютера Windows (certlm.msc).
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<самая последняя версия>\RuntimeSettings\ В журналах службы расширения Key Vault для виртуальной машины отображается состояние службы akvvm_service.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<самая последняя версия>\Status\ Конфигурация и двоичные файлы для службы расширения виртуальной машины Key Vault.

Поддержка

Ниже приведены некоторые другие варианты, которые помогут устранить проблемы с развертыванием.