Extensión de máquina virtual de Azure Key Vault para Windows

La extensión de máquina virtual (VM) de Azure Key Vault proporciona la actualización automática de los certificados almacenados en una instancia de Azure Key Vault. La extensión supervisa la lista de certificados observados almacenados en los almacenes de claves. Al detectar un cambio, la extensión recupera e instala los certificados correspondientes. Este artículo describe las plataformas compatibles, configuraciones y opciones de implementación de la extensión de máquina virtual de Key Vault para Windows.

Sistemas operativos

La extensión de máquina virtual de Key Vault admite Windows Server 2022 y Windows Server 2025, tanto en AMD64 como en ARM64. En Windows Server 2025, las claves privadas se guardan en KeyGuard.

Certificados admitidos

La extensión de máquina virtual de Key Vault admite los siguientes tipos de contenido de certificado:

• PKCS n.º 12
• PEM

Características

La extensión de máquina virtual Key Vault para Windows versión 4.x:

• Instala claves privadas en KeyGuard si se ejecuta en Windows Server 2025 y KeyGuard está operativo.
• Instala las dos versiones más recientes de cada certificado.
• Realiza la validación de la cadena de certificados antes de instalar cualquier certificado que contenga el uso extendido de clave de autenticación del servidor TLS (EKU), incluidos los certificados que llevan otras EKU junto con él (como la autenticación de cliente). Los errores de validación de cadena generan un error de aprovisionamiento en la extensión. Los certificados sin la EKU de autenticación del servidor y los certificados autofirmados (donde el firmante y el emisor son idénticos), no están sujetos a esta comprobación.
• Encadena todos los certificados de la máquina que se originan desde el mismo objeto de certificado Key Vault a la versión más reciente de ese certificado.
• Admite una anulación opcional de la autenticación para cada certificado, que permite que cada certificado supervisado se autentique con Key Vault con una identidad administrada distinta de la identidad administrada predeterminada de la extensión. Para obtener más información, vea Esquema de extensión.

Actualización desde la versión 3.0

Si va a actualizar desde la versión 3.0, se cambian o quitan las siguientes características:

• pollingIntervalInS ahora está limitado a entre 5 y 60 minutos. De forma predeterminada, la extensión realiza una consulta cada hora.
• Se ha eliminado linkOnRenewal. La vinculación siempre se produce.
• Se ha eliminado keyExportable. Las claves privadas ya no se pueden exportar.
• Se ha eliminado requireInitialSync. La extensión solo informa del éxito si instala todos los certificados configurados.
• Ya no puede configurar una versión específica de un certificado.
• La extensión ahora siempre almacena claves privadas mediante Cryptography API: Next Generation (CNG) en lugar de CAPI.

Requisitos previos

Revise los siguientes requisitos previos para usar la extensión de máquina virtual de Key Vault para Windows:

• Una instancia de Azure Key Vault con un certificado. Para más información, consulte Creación de un almacén de claves mediante Azure Portal.

• Una máquina virtual con una identidad administrada asignada.

• Asigne el rol Usuario de secretos de Key Vault en el nivel de ámbito de Key Vault a la identidad administrada de la máquina virtual o de los Virtual Machine Scale Sets. Este rol recupera la parte secreta de un certificado. Para más información, consulte los siguientes artículos.

  • Autenticación en Azure Key Vault
  • Utilice los permisos de secreto, clave y certificado de RBAC de Azure con Azure Key Vault
  • Asignación de roles en el ámbito de Key Vault

• Configure los conjuntos de escalado de máquinas virtuales con la siguiente identity configuración:

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

• Configure la extensión de máquina virtual Key Vault con la siguiente authenticationSettings configuración:

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

Esquema de extensión

El siguiente JSON muestra el esquema para la extensión de máquina virtual de Key Vault. Antes de tener en cuenta las opciones de implementación del esquema, revise las siguientes notas importantes.

• La extensión no requiere una configuración protegida. Todas las configuraciones son información pública.

• Las direcciones URL de certificado observadas deben usar el formulario https://myVaultName.vault.azure.net/secrets/myCertName.

  Este formulario es necesario porque la /secrets ruta de acceso devuelve el certificado completo, incluida la clave privada, pero la /certificates ruta de acceso no. Para más información sobre los certificados, consulte Información general sobre claves, secretos y certificados de Azure Key Vault. No se puede especificar una versión específica del certificado.

• El host de dirección URL debe ser un host de Azure Key Vault reconocido.

• La authenticationSettings propiedad es necesaria para las máquinas virtuales con cualquier identidad asignada por el usuario.

  Esta propiedad especifica la identidad que se usará para la autenticación en Key Vault. Defina esta propiedad con una identidad asignada por el sistema para evitar problemas con una extensión de máquina virtual con varias identidades.

{
   "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.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"]>,
                    "authenticationOverride": <Optional. Overrides authenticationSettings for this certificate only, so it can authenticate with a different managed identity. Example: {"msiClientId": "11112222-bbbb-3333-cccc-4444dddd5555"}>
                },
                {
                    "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">
         }
      }
   }
}

Valores de propiedad

El esquema JSON incluye las siguientes propiedades.

Implementación de plantilla

Implemente Azure extensiones de máquina virtual mediante plantillas de Azure Resource Manager (ARM). Las plantillas son ideales cuando se implementan una o varias máquinas virtuales que requieren una actualización posterior a la implementación de certificados. Puede implementar la extensión en máquinas virtuales individuales o en instancias de Virtual Machine Scale Sets. El esquema y la configuración son comunes para ambos tipos de plantilla.

La configuración JSON de una extensión de almacén de claves está anidada dentro de la plantilla VM o Virtual Machine Scale Sets. Para una extensión de recursos de máquina virtual, la configuración se anida en el objeto de máquina virtual "resources": []. Para una extensión de instancia de Virtual Machine Scale Sets, la configuración se anida bajo el "virtualMachineProfile":"extensionProfile":{"extensions" :[] objeto.

Los siguientes fragmentos de código JSON proporcionan una configuración de ejemplo para una implementación de plantilla de ARM de la extensión de máquina virtual de 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 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.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">
         }
      }
   }
}

Actualización automática de extensiones

La extensión de máquina virtual Key Vault admite la actualización automática de extensiones para máquinas virtuales y conjuntos de escalado en Azure. Azure mantiene la extensión actualizada automáticamente al establecer las autoUpgradeMinorVersion propiedades y enableAutomaticUpgrade en los ejemplos anteriores en true.

Orden de las dependencias de la extensión

La extensión de máquina virtual Key Vault admite el orden de dependencias de extensión. La extensión informa de un inicio correcto después de descargar e instalar todos los certificados.

Si usa otras extensiones que requieren la instalación de certificados antes de que se inicien, puede usar el orden de dependencia de extensión para declarar una dependencia en la extensión de máquina virtual de Key Vault.

En el inicio, la extensión de máquina virtual Key Vault reintenta la descarga e instalación de certificados hasta 25 veces con períodos de retroceso crecientes, durante los cuales permanece en un estado Transitioning. Si se agotan los reintentos, la extensión notifica un estado error . Una vez instalados correctamente todos los certificados, la extensión de máquina virtual de Key Vault notifica un inicio correcto.

Para obtener más información sobre cómo configurar dependencias entre extensiones, consulte Aprovisionamiento de extensiones de secuencia en Virtual Machine Scale Sets.

Implementación de Azure PowerShell

Implemente la extensión de máquina virtual de Azure Key Vault mediante Azure PowerShell. Guarde la configuración de la extensión de la máquina virtual de Key Vault en un archivo JSON (settings.json).

Los siguientes fragmentos de código JSON proporcionan una configuración de ejemplo para implementar la extensión de máquina virtual de Key Vault mediante 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"
   }
}

Implementación en una máquina virtual

# 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

Implementación en una instancia de Virtual Machine Scale Sets

# 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

Implementación de la CLI de Azure

Implemente la extensión de máquina virtual de Azure Key Vault mediante el CLI de Azure. Guarde la configuración de la extensión de la máquina virtual de Key Vault en un archivo JSON (settings.json).

Los siguientes fragmentos de código JSON proporcionan una configuración de ejemplo para implementar la extensión de máquina virtual de Key Vault mediante el CLI de Azure.

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

Implementación en una máquina virtual

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

Implementación en una instancia de Virtual Machine Scale Sets

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

Solucionar problemas

Use estas sugerencias para solucionar problemas de implementación.

Compruebe las preguntas más frecuentes

¿Hay un límite en el número de certificados observados?

No. No, la extensión de VM de Key Vault no tiene un límite en cuanto al número de certificados observados (observedCertificates).

¿Cuál es el permiso predeterminado cuando no se especifica ninguna cuenta?

De forma predeterminada, los administradores y SYSTEM reciben control total.

¿Cómo se determina si una clave de certificado es CAPI1 o CNG?

A partir de Key Vault extensión de máquina virtual 4.0, la extensión guarda claves privadas para todos los certificados mediante CNG.

¿La extensión admite el reenlace automático de certificados?

Sí, la extensión de máquina virtual de Azure Key Vault admite el reenlace automático de certificados. La extensión de máquina virtual de Key Vault admite la comunicación con el canal S en la renovación de certificados.

Para IIS, configure el reenlace automático habilitando el reenlace automático de renovaciones de certificados en IIS. La extensión de máquina virtual Azure Key Vault genera notificaciones de ciclo de vida de certificados cuando instala un certificado renovado para el mismo objeto de certificado Key Vault que un certificado existente. IIS usa este evento para volver a enlazar automáticamente el certificado. Para obtener más información, consulte Reenlace de certificados en IIS.

Consulta del estado de la extensión

Compruebe el estado de la implementación de la extensión en Azure Portal, o mediante PowerShell o la CLI de Azure.

Para ver el estado de implementación de las extensiones de una máquina virtual determinada, ejecute los comandos siguientes.

• Azure PowerShell:

  Get-AzVMExtension -ResourceGroupName <myResourceGroup> -VMName <myVM> -Name <myExtensionName>
  

• La CLI de Azure:

  az vm get-instance-view --resource-group <myResourceGroup> --name <myVM> --query "instanceView.extensions"
  

Revisión de registros y configuración

Los registros de extensión de máquina virtual de Key Vault solo existen localmente en la máquina virtual. Revise los detalles del registro para obtener ayuda para solucionar problemas.

Instalación de certificados en Windows

La extensión de máquina virtual de Key Vault para Windows instala certificados en el almacén de certificados de Windows. Cuando la extensión descarga un certificado de Key Vault, es:

1. Instala todos los certificados intermedios y hoja, independientemente del número de certificados intermedios que estén presentes. La extensión no instala certificados raíz porque no está autorizado para instalarlos. Asegúrese de que el certificado raíz sea de confianza en el sistema.
   • Instala los certificados de hoja en el almacén de certificados especificado (certificateStoreName) y en la ubicación indicada (certificateStoreLocation).
   • Instala los certificados de CA intermedios en el almacén de autoridades de certificación intermedias.
2. Coloca los certificados en el almacén de certificados especificado (certificateStoreName) y la ubicación (certificateStoreLocation).
3. Aplica los permisos adecuados a la clave privada en función del accounts especificado en la configuración.
4. Establece la CERT_RENEWAL propiedad para que los enlaces de certificado en aplicaciones como IIS se actualicen automáticamente cuando se renuevan los certificados. Un certificado queda vinculado a la versión más reciente procedente del mismo objeto de certificado de Key Vault, identificado por la dirección URL base del secreto del certificado de Key Vault. Los certificados que corresponden a diferentes Key Vault objetos de certificado nunca se vinculan entre sí.

Almacenes de certificados predeterminados

De forma predeterminada, la extensión instala certificados en las siguientes ubicaciones:

• Nombre de la tienda: MY (Personal).
• Ubicación de la tienda: LocalMachine.

Control de acceso a certificados

De forma predeterminada, los administradores y SYSTEM reciben permisos de control total en los certificados instalados. Puede personalizar el acceso mediante la accounts matriz en la configuración del certificado:

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

Esta configuración concede acceso de lectura a las cuentas especificadas, lo que permite que las aplicaciones que se ejecutan en esas identidades usen los certificados.

Renovación de certificados

Cuando los certificados se renuevan en Key Vault, la extensión se realiza automáticamente:

1. Descarga la nueva versión del certificado.
2. Instala el certificado en el almacén de certificados configurado.
3. Mantiene los enlaces existentes mediante la CERT_RENEWAL propiedad .

Administración del ciclo de vida de los certificados

En el caso de aplicaciones como IIS que admiten notificaciones de ciclo de vida de servicios de certificados, la extensión de máquina virtual de Key Vault genera el evento 1001 en el registro de eventos de Windows cuando instala un certificado renovado para el mismo objeto de certificado de Key Vault que un certificado existente (vinculando el nuevo certificado a su predecesor). IIS se suscribe a este evento para volver a enlazar automáticamente el certificado renovado sin interrumpir el servicio. Otras aplicaciones y equipos también pueden escuchar el evento 1001 para actuar en las renovaciones de certificados según sea necesario. Para obtener más información, consulte Notificaciones del ciclo de vida de Servicios de Certificados.

Obtención de soporte técnico

Microsoft solo proporciona compatibilidad con la versión principal 3.0 y posteriores de la extensión de máquina virtual de Key Vault. Si usa la versión 1.0, actualice a la versión más reciente antes de solicitar soporte técnico.

Use estas otras opciones para ayudar a resolver problemas de implementación:

• Para obtener ayuda, póngase en contacto con los expertos Azure en Microsoft Q& A.

• Si encontrase respuestas en este sitio, publique una pregunta dirigida a Microsoft o a otros miembros de la comunidad.

• También puede ponerse en contacto con el soporte técnico de Microsoft. Para obtener información sobre el uso de Soporte técnico de Azure, vea How to create an Soporte técnico de Azure request.