适用于 Windows 的Azure 密钥保管库虚拟机扩展

Azure 密钥保管库虚拟机（VM）扩展提供Azure key vault中存储的证书的自动刷新。 该扩展会监视 Key Vault 中存储的已观察到的证书列表。 检测到更改后，该扩展会检索并安装相应的证书。 本文介绍适用于 Windows 的 密钥保管库 VM 扩展支持的平台、配置和部署选项。

操作系统

密钥保管库 VM 扩展支持 AMD64 和 ARM64 上的 Windows Server 2022 和 Windows Server 2025。 在 Windows Server 2025 上，私钥保存在 KeyGuard 中。

支持的证书

密钥保管库 VM 扩展支持以下证书内容类型：

• PKCS #12
• PEM

特点

Windows版本 4.0 的 密钥保管库 VM 扩展：

• 如果在 Windows Server 2025 上运行，请将私钥安装到 KeyGuard 中。
• 安装每个证书的两个最新版本。
• 在安装包含 TLS 服务器身份验证扩展密钥用法 (EKU) 的证书之前，执行证书链验证，包括那些同时包含其他 EKU 的证书（例如，客户端身份验证）。 链验证错误会导致扩展的预配失败。 没有服务器身份验证 EKU 的证书不受此检查的约束。

从 3.0 升级

如果要从 3.0 更新，将更改或删除以下功能：

• pollingIntervalInS 现在限制为 5 到 60 分钟。 默认情况下，每小时执行一次轮询。
• linkOnRenewal 已删除 。 链接总是会发生。
• keyExportable 已删除 。 私钥不再可导出。
• requireInitialSync 已删除 。 仅当安装了所有配置的证书时，该扩展才会报告成功。
• 不能再配置特定版本的证书。
• 该扩展现在始终使用 Cryptography API: Next Generation (CNG) 而非 CAPI 来存储私钥。

先决条件

查看以下先决条件，了解如何使用适用于 Windows 的 密钥保管库 VM 扩展：

• 具有证书的Azure 密钥保管库实例。 有关详细信息，请参阅 通过使用 Azure 门户创建“密钥保管库”。

• 具有分配托管标识的 VM。

• 将 密钥保管库 机密用户 角色在 密钥保管库 作用域级别分配给 VM 或 Azure 虚拟机规模集的托管标识。 此角色检索证书的机密部分。 如需了解更多信息，请参阅以下文章：

  • 在 Azure 密钥保管库 中的身份验证
  • 将 Azure RBAC 的机密、密钥和证书权限用于 Azure 密钥保管库
  • 密钥保管库 作用域的角色分配

• 使用以下identity配置虚拟机规模集：

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

• 使用以下authenticationSettings配置来配置 密钥保管库 VM 扩展：

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

扩展架构

以下 JSON 显示了密钥保管库 VM 扩展的架构。 在考虑架构实现选项之前，请查看以下重要说明。

• 扩展不需要受保护的设置。 所有设置均为公开信息。

• 对已发现的证书 URL 使用 https://myVaultName.vault.azure.net/secrets/myCertName 格式。

  首选此格式是因为 /secrets 路径会返回完整证书（包括私钥），但 /certificates 路径不会。 有关证书的详细信息，请参阅 Azure 密钥保管库 密钥、机密和证书概述。

• 对于具有任何用户分配标识的虚拟机，authenticationSettings 属性是必需的。

  此属性指定要用于密钥保管库身份验证的标识。 使用系统分配的标识定义此属性，以避免 VM 扩展存在多个标识的问题。

{
   "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 Key Vault 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.cn/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.cn/secrets/mycertificate2">,
                    "certificateStoreName": <Example: "MY">,
                    "certificateStoreLocation": <Example: "CurrentUser">,
                    "accounts": <Example: ["Local Service"]>
                },
                {
                    "url": <Example: "https://myvault.vault.azure.cn/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 资源管理器 （ARM） 模板部署Azure VM 扩展。 部署需要部署证书后刷新的一个或多个虚拟机时，模板是理想的选择。 可以将扩展部署到单个 VM 或虚拟机规模集实例。 架构和配置对于这两种模板类型通用。

用于 Key Vault 扩展的 JSON 配置嵌套在虚拟机或虚拟机规模集模板中。 对于 VM 资源扩展，该配置嵌套在 "resources": [] 虚拟机对象下。 对于虚拟机规模集实例扩展，配置嵌套在 "virtualMachineProfile":"extensionProfile":{"extensions" :[] 对象下。

以下 JSON 代码片段为 KEY VAULT VM 扩展的 ARM 模板部署提供示例设置。

{
   "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 Key Vault 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.cn/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.cn/secrets/mycertificate2">,
                    "certificateStoreName": <Example: "MY">,
                    "certificateStoreLocation": <Example: "CurrentUser">,
                    "accounts": <Example: ["Local Service"]>
                },
                {
                    "url": <Example: "https://myvault.vault.azure.cn/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">
         }
      }
   }
}

扩展自动升级

密钥保管库 VM 扩展支持Azure中虚拟机和规模集的自动扩展升级。 当你将前面示例中的 autoUpgradeMinorVersion 和 enableAutomaticUpgrade 属性设置为 true 时，Azure 会自动使扩展保持最新状态。

扩展依赖项排序

密钥保管库 VM 扩展支持扩展依赖项排序。 扩展会在下载并安装所有证书后报告成功启动。

如果在开始之前使用其他需要安装证书的扩展，则可以使用扩展依赖项排序来声明对 密钥保管库 VM 扩展的依赖项。

启动时，密钥保管库 VM 扩展会重试多达 25 次下载和安装证书，并且在每次重试之间增加后退时间，在此期间它仍处于 Transitioning 状态。 如果重试次数已用尽，扩展会报告 错误 状态。 成功安装所有证书后，密钥保管库 VM 扩展会报告成功启动。

有关在扩展之间设置依赖项的详细信息，请参阅虚拟机规模集中的序列扩展预配。

Azure PowerShell部署

使用 Azure PowerShell 部署Azure 密钥保管库 VM 扩展。 将KEY VAULT VM 扩展设置保存到 JSON 文件（settings.json）。

以下 JSON 代码片段提供了使用 PowerShell 部署密钥保管库 VM 扩展的示例设置。

{
   "secretsManagementSettings": {
   "observedCertificates":
   [
      {
          "url": "https://<examplekv>.vault.azure.cn/secrets/certificate1",
          "certificateStoreName": "MY",
          "certificateStoreLocation": "LocalMachine",
          "accounts": [
             "Network Service"
          ]
      },
      {
          "url": "https://<examplekv>.vault.azure.cn/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"
   }
}

在 VM 上部署

# 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 CLI部署Azure 密钥保管库 VM 扩展。 将KEY VAULT VM 扩展设置保存到 JSON 文件（settings.json）。

以下 JSON 代码片段提供了使用 Azure CLI 部署 密钥保管库 VM 扩展的示例设置。

   {
        "secretsManagementSettings": {
          "observedCertificates": [
            {
                "url": "https://<examplekv>.vault.azure.cn/secrets/certificate1",
                "certificateStoreName": "MY",
                "certificateStoreLocation": "LocalMachine",
                "accounts": [
                    "Network Service"
                ]
            },
            {
                "url": "https://<examplekv>.vault.azure.cn/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"
        }
     }

在 VM 上部署

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

故障排查

使用这些建议排查部署问题。

查看常见问题

观察到的证书数量有限制吗？

否。 密钥保管库 VM 扩展不会限制观察到的证书数（observedCertificates）。

未指定帐户时的默认权限是什么？

默认情况下，管理员和 SYSTEM 将获得完全控制。

如何确定证书密钥是 CAPI1 还是 CNG？

从 密钥保管库 VM 扩展 4.0 开始，该扩展使用 CNG 保存所有证书的私钥。

该扩展是否支持证书自动重新绑定？

是的，Azure 密钥保管库 VM 扩展支持证书自动绑定。 密钥保管库 VM 扩展支持证书续订时 S 通道绑定。

对于 IIS，您可以通过在 IIS 中启用证书续订的自动重新绑定功能来配置自动绑定。 安装具有匹配 SAN 的证书时，Azure 密钥保管库 VM 扩展会生成证书生命周期通知。 IIS 使用此事件自动重新绑定证书。 有关详细信息，请参阅 IIS 中的证书重新绑定。

查看扩展状态

在Azure portal或使用 PowerShell 或Azure CLI检查扩展部署的状态。

若要查看给定 VM 的扩展部署状态，请运行以下命令。

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

查看日志和配置

密钥保管库 VM 扩展日志仅存在于 VM 本地。 查看日志详细信息以帮助进行故障排除。

在 Windows 上安装证书

适用于 Windows 的 密钥保管库 VM 扩展将证书安装到 Windows 证书存储中。 当扩展从密钥保管库下载证书时，它会：

1. 安装所有中间证书和叶证书，而不考虑存在多少个中间证书。 该扩展不会安装根证书，因为它无权安装它们。 确保系统信任该根证书。
   • 在指定的证书存储（）和位置（certificateStoreNamecertificateStoreLocation）中安装叶证书。
   • 在“中间证书颁发机构”证书存储区中安装中间 CA 证书。
2. 将证书置于指定的证书存储区（certificateStoreName）和位置（certificateStoreLocation）。
3. 根据 accounts 配置中指定的权限对私钥应用适当的权限。
4. CERT_RENEWAL设置属性，以便在续订证书时 IIS 等应用程序中的证书绑定自动更新。

默认证书存储

默认情况下，该扩展在以下位置安装证书：

• 商店名称：MY（个人）。
• 存储位置：LocalMachine。

证书访问控制

默认情况下，管理员和 SYSTEM 接收对已安装证书的完全控制权限。 您可以通过使用证书配置中的 accounts 数组来自定义访问权限：

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

此配置向指定账户授予读取权限，从而允许以这些身份运行的应用程序使用证书。

证书续订

当证书在密钥保管库中续订时，扩展会自动：

1. 下载新的证书版本。
2. 在配置的证书存储中安装证书。
3. 使用 CERT_RENEWAL 属性维护现有绑定。

管理证书生命周期

对于支持证书服务生命周期通知的 IIS 等应用程序，密钥保管库 VM 扩展在使用匹配的使用者可选名称（SAN）安装证书时，会在Windows事件日志中引发事件 1001。 IIS 订阅此事件以自动重新绑定续订的证书，而不会中断服务。 其他应用程序和团队还可以监听事件 1001，根据需要对证书续订采取行动。 有关详细信息，请参阅 证书服务生命周期通知。

获取支持

如果在本文中的任何时间点需要更多帮助，可以联系 Azure 支持 Azure 专家。 或者，可以提交Azure 支持事件。 转到 Azure 支持 网站并提交请求。 有关使用Azure Support的信息，请阅读 Azure 支持 FAQ。