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

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

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

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

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

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

• PKCS #12
• PEM

Функции

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

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

Предпосылки

Ознакомьтесь со следующими предварительными условиями для использования расширения виртуальной машины 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": "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">
         }
      }
   }
}

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

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

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

Расширения виртуальных машин 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: "00001111-aaaa-2222-bbbb-3333cccc4444">
         }
      }
   }
}

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

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

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

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

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

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

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

Развертывание с помощью 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":  "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 "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":  "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"

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

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

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

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

Как определить, является ли ключ сертификата 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 существуют только локально на виртуальной машине. Просмотрите сведения о журнале, чтобы помочь в устранении неполадок.

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

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

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

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

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

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

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

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

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

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

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

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

1. Скачивает новую версию сертификата
2. Устанавливает его в настроенном хранилище сертификатов
3. Поддерживает существующие привязки через функцию linkOnRenewal, если она включена.

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

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

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

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

• Чтобы получить помощь, обратитесь к экспертам Azure на форумах Q&A и Stack Overflow.

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

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