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

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

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

Расширение виртуальной машины Key Vault поддерживает Windows Server 2022 и Windows Server 2025 в AMD64 и ARM64. В Windows Server 2025 г. закрытые ключи сохраняются в KeyGuard.

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

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

• PKCS #12
• PEM

Функции

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

• Устанавливает закрытые ключи в KeyGuard, если работает на Windows Server 2025.
• Устанавливает две последние версии каждого сертификата.
• Выполняет проверку цепочки сертификатов перед установкой любого сертификата, содержащего расширенное использование ключа для проверки подлинности сервера TLS (EKU), включая сертификаты, которые имеют другие EKU, например, клиентскую аутентификацию. Ошибки проверки цепочки приводят к сбою развертывания расширения. Сертификаты без EKU проверки подлинности сервера не подлежат этой проверке.

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

При обновлении с версии 3.0 следующие функции изменяются или удаляются:

• pollingIntervalInS теперь ограничено в диапазоне от 5 до 60 минут. По умолчанию опрос выполняется один раз в час.
• linkOnRenewal удален. Связывание всегда осуществляется.
• keyExportable удален. Закрытые ключи больше не экспортируются.
• requireInitialSync удален. Расширение сообщает об успешном выполнении только в том случае, если установлены все настроенные сертификаты.
• Настройка определенной версии сертификата больше не возможна.
• Закрытые ключи теперь всегда хранятся через API шифрования: следующее поколение (CNG) вместо CAPI.

Предпосылки

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

• Экземпляр Azure Key Vault с сертификатом. Дополнительные сведения см. в статье "Создание хранилища ключей" с помощью портала Azure.

• Виртуальная машина с назначенным управляемым удостоверением.

• Роль пользователя секретов Key Vault должна быть назначена на уровне хранилища ключей для управляемого удостоверения виртуальных машин и масштабируемых наборов виртуальных машин Azure. Эта роль извлекает секретную часть сертификата. Дополнительные сведения см. в следующих статьях:

  • Проверка подлинности в Azure Key Vault
  • Использование секрета, ключа и сертификата Azure RBAC с помощью Azure Key Vault
  • Назначение ролей области Key Vault

• Масштабируемые наборы виртуальных машин должны иметь следующую identity конфигурацию:

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

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

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

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

В следующем 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": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForWindows",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "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">,
                    "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">
         }
      }
   }
}

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

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

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

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

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

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

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KeyVaultForWindows",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForWindows",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "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">,
                    "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">
         }
      }
   }
}

Автоматическое обновление расширения

Расширение виртуальной машины Key Vault поддерживает автоматическое обновление расширений для виртуальных машин и наборов масштабирования в Azure. Расширение обновляется автоматически, когда свойства autoUpgradeMinorVersion и enableAutomaticUpgrade в предыдущих примерах заданы на true.

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

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

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

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

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

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

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

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

{   
   "secretsManagementSettings": {
   "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",
          "accounts": [
             "Network Service",
             "Local Service"
          ]
      }
   ]},
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity/oauth2/token",
      "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }      
}

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

# Build settings
$settings = (get-content -raw ".\settings.json")
$extName =  "KeyVaultForWindows"
$extPublisher = "Microsoft.Azure.KeyVault"
$extType = "KeyVaultForWindows"
 
# Start the deployment
Set-AzVmExtension -TypeHandlerVersion "4.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 "4.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": {
          "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",                
                "accounts": [
                    "Network Service",
                    "Local Service"
                ]
            }
        ]
        },
          "authenticationSettings": {
          "msiEndpoint":  "http://169.254.169.254/metadata/identity/oauth2/token",
          "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
        }      
     }

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

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

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

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

az vm extension delete --name "KeyVaultForWindows" --resource-group "<resourcegroup>" --vm-name "<vmName>"

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

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

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

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

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

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

По умолчанию администраторы и СИСТЕМА получают полный доступ.

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

Начиная с расширения виртуальной машины Key Vault версии 4.0 закрытые ключи для всех сертификатов сохраняются через CNG.

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

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

Для IIS можно настроить автопривязку, включив автоматическое обновление сертификатов в IIS. Расширение виртуальной машины Azure Key Vault создаёт уведомления о жизненном цикле сертификатов, когда установлен сертификат с соответствующим SAN. Служба IIS использует это событие для автоматического восстановления привязки сертификата. Дополнительные сведения см. в "Повторном связывании сертификатов в 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 существуют только локально на виртуальной машине. Просмотрите сведения о журнале, чтобы помочь в устранении неполадок.

Установка сертификата в Windows

Расширение виртуальной машины Key Vault для Windows устанавливает сертификаты в хранилище сертификатов Windows. При скачивании сертификата из Key Vault, расширение файла:

1. Устанавливает все промежуточные и конечные сертификаты независимо от количества промежуточных сертификатов. Корневые сертификаты не установлены, так как расширение не авторизовано для выполнения корневой установки. Это ответственность владельца службы, чтобы убедиться, что корневой сертификат является доверенным в системе.
   • Конечные сертификаты устанавливаются в указанное хранилище сертификатов (certificateStoreName) и место назначения (certificateStoreLocation)
   • Промежуточные сертификаты ЦС устанавливаются в хранилище промежуточных центров сертификации
2. Помещает сертификаты в указанное хранилище сертификатов (certificateStoreName) и расположение (certificateStoreLocation)
3. Применяет соответствующие разрешения к закрытому ключу, исходя из значений, указанных accounts в конфигурации.
4. CERT_RENEWAL Задает свойство, чтобы убедиться, что привязки сертификатов в таких приложениях, как IIS, автоматически обновляются при продлении сертификатов.

Хранилища сертификатов по умолчанию

Если сертификат не указан, сертификаты устанавливаются в следующих расположениях по умолчанию:

• Имя хранилища: MY (Личное)
• Расположение магазина: LocalMachine

Управление доступом к сертификату

По умолчанию администраторы и СИСТЕМА получают разрешения полного управления для установленных сертификатов. Вы можете настроить доступ с помощью массива accounts в конфигурации сертификата:

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

Это обеспечивает доступ на чтение к указанным учетным записям, позволяя приложениям, работающим под этими удостоверениями, использовать сертификаты.

Продление сертификата

При продлении сертификатов в Key Vault расширение автоматически:

1. Загружает новую версию сертификата.
2. Устанавливает его в настроенном хранилище сертификатов.
3. Сохраняет существующие привязки через CERT_RENEWAL свойство.

Управление жизненным циклом сертификата

Для таких приложений, как IIS, поддерживающих уведомления жизненного цикла служб сертификатов, расширение виртуальной машины Key Vault вызывает Event 1001 в журнале событий Windows при установке сертификата с соответствующим альтернативным именем субъекта (SAN). IIS подписывается на это событие, чтобы автоматически повторно привязать обновленный сертификат без прерывания работы службы. Другие приложения и группы также могут прослушивать событие 1001, чтобы действовать на продление сертификатов по мере необходимости. Дополнительные сведения см. в разделе "Уведомления жизненного цикла служб сертификатов".

Получите поддержку

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

• Чтобы получить помощь, обратитесь к экспертам Azure в Microsoft Q& A.

• Если вы не найдете ответ на сайте, вы можете опубликовать вопрос для ввода от Корпорации Майкрософт или других членов сообщества.

• Вы также можете связаться с служба поддержки Майкрософт. Сведения об использовании поддержки Azure см. в статье Как создать запрос в поддержку Azure.