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

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

注释

尝试 VM 辅助，以便更快地进行诊断。建议运行 VM assist for Windows 或 VM assist for Linux。这些基于脚本的诊断工具可帮助你识别影响Azure VM 来宾代理和整体 VM 运行状况的常见问题。

如果你遇到虚拟机性能问题，在联系支持人员之前，请运行这些工具。

操作系统

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

注释

密钥保管库 VM 扩展版本 4.0 不会安装在 Windows Server 2019 或更早版本。

支持的证书

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

PKCS #12
PEM

注释

密钥保管库 VM 扩展将所有证书下载到 Windows 证书存储或 VM 扩展设置中 certificateStoreLocation 属性中指定的位置。

特点

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

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

从 3.0 升级

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

pollingIntervalInS 现在限制为 5 到 60 分钟。默认情况下，每小时执行一次轮询。
linkOnRenewal 已删除。链接总是会发生。
keyExportable 已删除。私钥不再可导出。
requireInitialSync 已删除。仅当安装了所有配置的证书时，该扩展才会报告成功。
无法再配置特定版本的证书。
私钥现在始终通过加密 API：下一代（CNG）存储，而不是通过CAPI。

先决条件

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

具有证书的Azure 密钥保管库实例。有关详细信息，请参阅通过使用 Azure 门户创建“密钥保管库”。
具有分配托管标识的 VM。
必须在 VM 和Azure 虚拟机规模集托管标识的密钥保管库范围级别分配 密钥保管库机密用户角色。此角色可检索证书的机密部分。如需了解更多信息，请参阅以下文章：
- 在 Azure 密钥保管库中的身份验证
- 将 Azure RBAC 的机密、密钥和证书权限用于 Azure 密钥保管库
- 密钥保管库作用域的角色分配

虚拟机规模集应具有以下identity配置：

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

密钥保管库 VM 扩展应具有以下authenticationSettings配置：

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

注释

旧的访问策略权限模型也可用于提供对VM和虚拟机规模集的访问。此方法需要对机密具有“get”和“list”权限的策略。有关详细信息，请参阅分配密钥保管库访问策略。

扩展架构

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

扩展不需要受保护的设置。所有设置均视为公共信息。
观察到的证书 URL 的格式应为 https://myVaultName.vault.azure.cn/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 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.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 架构包括以下属性。

名称	值/示例	数据类型
`apiVersion`	2025-04-01	日期
`publisher`	微软。Azure。KeyVault	字符串
`type`	KeyVaultForWindows	字符串
`typeHandlerVersion`	"4.0"	字符串
`observedCertificates`	[{...}, {...}]	字符串数组
`observedCertificates/url`	“https://myvault.vault.azure.cn/secrets/mycertificate"	字符串
`observedCertificates/certificateStoreName`	我	字符串
`observedCertificates/certificateStoreLocation`	LocalMachine 或 CurrentUser（区分大小写）	字符串
`observedCertificates/accounts`（可选）	[“网络服务”， “本地服务”]	字符串数组
`msiEndpoint`	“http://169.254.169.254/metadata/identity/oauth2/token"	字符串
`msiClientId`	00001111-aaaa-2222-bbbb-3333cccc4444	字符串

模板部署

可以使用 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 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.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中虚拟机和规模集的自动扩展升级。当上述示例中的属性autoUpgradeMinorVersionenableAutomaticUpgrade设置为true时，扩展会自动更新保持最新。

扩展依赖项排序

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

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

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

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

重要

扩展依赖项排序功能与创建系统分配标识并使用该标识更新密钥保管库访问策略的 ARM 模板不兼容。如果尝试在此场景中使用该功能，则会发生死锁，因为密钥保管库访问策略只有在所有扩展启动后才能更新。改为在部署之前使用单个用户分配的 MSI 标识，并使用该标识对你的密钥保管库进行预 ACL 操作。

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"

小窍门

如果扩展部署失败，可能需要先删除现有扩展，然后再重新安装正确的版本。 Azure不允许扩展降级，因此可能需要先删除有故障的扩展：

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 本地。查看日志详细信息以帮助进行故障排除。

日志文件	DESCRIPTION
C：\WindowsAzure\Logs\WaAppAgent.log'	显示扩展更新的时间。
C：\WindowsAzure\Logs\Plugins\Microsoft。Azure。KeyVault.KeyVaultForWindows<最新版本>\	显示证书下载的状态。下载位置始终为 Windows 计算机的 MY 存储位置 (certlm.msc)。
C：\Packages\Plugins\Microsoft。Azure。KeyVault.KeyVaultForWindows<最新版本>\RuntimeSettings\	密钥保管库 VM 扩展服务日志显示akvvm_service服务的状态。
C：\Packages\Plugins\Microsoft。Azure。KeyVault.KeyVaultForWindows<最新版本>\Status\	密钥保管库 VM 扩展服务的配置和二进制文件。

Windows 上的证书安装

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

安装所有中间证书和叶证书，而不考虑存在多少个中间证书。根证书未安装，因为扩展无权执行根安装。服务所有者有责任确保系统信任根证书。
- 末级证书被安装到指定的证书存储（certificateStoreName）和位置（certificateStoreLocation）
- 中间证书颁发机构的证书安装在中继证书机构存储中。
将证书放置在指定的证书存储（certificateStoreName）和位置（certificateStoreLocation）
根据 accounts 配置中指定的权限对私钥应用适当的权限
设置属性 CERT_RENEWAL 以确保在续订证书时 IIS 等应用程序中的证书绑定自动更新。

默认证书存储

如果未指定，则默认情况下，证书安装在以下位置：

商店名称：MY（个人）
应用商店位置：LocalMachine

证书访问控制

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

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

这授予指定帐户读取权限，从而允许以这些标识运行的应用程序使用证书。

证书续订

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

下载新的证书版本。
将其安装在配置的证书存储中。
通过 CERT_RENEWAL 属性维护现有绑定。

管理证书生命周期

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

获取支持

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

Last updated on 2026-05-26

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

操作系统

支持的证书

特点

从 3.0 升级

先决条件

扩展架构

属性值

模板部署

扩展自动升级

扩展依赖项排序

Azure PowerShell部署

在 VM 上部署

在虚拟机规模集实例上部署

Azure CLI部署

在 VM 上部署

在虚拟机规模集实例上部署

排查问题

查看常见问题

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

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

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

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

查看扩展状态

查看日志和配置

Windows 上的证书安装

默认证书存储

证书访问控制

证书续订

管理证书生命周期

获取支持

其他資源