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

  • Artículo

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 las siguientes versiones de Windows:

  • Windows Server 2022
  • Windows Server 2019
  • Windows Server 2016
  • Windows Server 2012

La extensión de máquina virtual Key Vault también se admite en una máquina virtual local personalizada. La máquina virtual debe cargarse y convertirse en una imagen especializada para usarse en Azure mediante una instalación básica de Windows Server 2019.

Certificados admitidos

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

  • PKCS #12
  • PEM

Nota:

La extensión de máquina virtual de Key Vault descarga todos los certificados al almacén de certificados de Windows o a la ubicación especificada en la propiedad certificateStoreLocation en la configuración de la extensión de máquina virtual.

Novedades en la versión 3.0+

La versión 3.0 de la extensión de máquina virtual de Key Vault para Windows incorpora la compatibilidad con las siguientes características:

  • Adición de permisos de ACL a certificados descargados
  • Habilitación de la configuración del almacén de certificados por certificado
  • Exportación de claves privadas
  • Compatibilidad con reenlace de certificados IIS

Requisitos previos

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

Nota:

El modelo anterior de permisos de directiva de acceso también se puede usar para proporcionar acceso a las máquinas virtuales y Virtual Machine Scale Sets. Este método requiere directivas con permisos get y list en secretos. Para más información, consulte Asignación de una directiva de acceso de Key Vault.

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. Toda la configuración se considera información pública.

  • Las direcciones URL de los certificados observados deben tener el formato https://myVaultName.vault.azure.net/secrets/myCertName.

    Se prefiere este formato porque la ruta de acceso /secrets devuelve el certificado completo, incluida la clave privada, mientras que la ruta de acceso /certificates no. Para obtener más información acerca de los certificados, consulte Introducción a las claves, secretos y certificados de Azure Key Vault.

  • La propiedad authenticationSettings es obligatoria para máquinas virtuales con identidades asignadas 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": "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:  "c7373ae5-91c2-4165-8ab6-7381d6e75619">
         }
      }
   }
}

Valores de propiedad

El esquema JSON incluye las siguientes propiedades.

Nombre Valor/ejemplo Tipo de datos
apiVersion 2022-08-01 date
publisher Microsoft.Azure.KeyVault string
type KeyVaultForWindows string
typeHandlerVersion "3.0" string
pollingIntervalInS "3600" string
linkOnRenewal (opcional) true boolean
requireInitialSync (opcional) false boolean
observedCertificates [{...}, {...}] matriz de cadenas
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate" string
observedCertificates/certificateStoreName MY string
observedCertificates/certificateStoreLocation LocalMachine o CurrentUser (distingue mayúsculas de minúsculas) string
observedCertificates/keyExportable (opcional) false boolean
observedCertificates/accounts (opcional) ["Servicio de red", "Servicio local"] matriz de cadenas
msiEndpoint "http://169.254.169.254/metadata/identity/oauth2/token" string
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string

Implementación de plantilla

Las extensiones de VM de Azure pueden implementarse con plantillas de Azure Resource Manager (ARM). Las plantillas son ideales al implementar una o varias máquinas virtuales que requieren la actualización de los certificados tras la implementación. La extensión se puede implementar 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 del almacén de claves está anidada dentro de la máquina virtual o la plantilla de 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": "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: "c7373ae5-91c2-4165-8ab6-7381d6e75619">
         }
      }
   }
}

Orden de las dependencias de la extensión

Puede habilitar la extensión de máquina virtual Key Vault para admitir el orden de dependencias de la extensión. De forma predeterminada, la extensión de máquina virtual de Key Vault notifica un inicio correcto en cuanto comienza el sondeo. Sin embargo, puede configurar la extensión para notificar un inicio correcto solo después de que la extensión descargue e instale todos los certificados.

Si usa otras extensiones que requieren la instalación de todos los certificados antes de que se inicien, puede habilitar el orden de dependencias de la extensión en la extensión de máquina virtual de Key Vault. Esta característica permite que otras extensiones declaren una dependencia en la extensión de máquina virtual de Key Vault.

Puede usar esta característica para evitar que otras extensiones se inicien hasta que se instalen todos los certificados dependientes. Cuando la característica está habilitada, la extensión de máquina virtual de Key Vault reintenta la descarga e instalación de certificados indefinidamente y permanece en el estado En transición, hasta que todos los certificados se instalan correctamente. Una vez que todos los certificados están presentes, la extensión de máquina virtual de Key Vault notifica un inicio correcto.

Para habilitar la característica de ordenación de dependencias de extensión en la extensión de máquina virtual de Key Vault, establezca la propiedad secretsManagementSettings:

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

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

Importante

La característica de ordenación de dependencia de la extensión no es compatible con una plantilla de ARM que crea una identidad asignada por el sistema y actualiza una directiva de acceso de Key Vault con esa identidad. Si intenta usar la característica en este escenario, se produce un interbloqueo porque la directiva de acceso de Key Vault no se puede actualizar hasta después de que se inicien todas las extensiones. En su lugar, debe usar una identidad MSI asignada por el usuario única y establecer una ACL previamente en los almacenes con esa identidad antes de la implementación.

Implementación de Azure PowerShell

La extensión de máquina virtual de Azure Key Vault se puede implementar con 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 con 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":  "c7373ae5-91c2-4165-8ab6-7381d6e75619"
   }      
}

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 "3.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 "3.0" -Setting $settings

# Start the deployment
Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss

Implementación de la CLI de Azure

La extensión de máquina virtual de Azure Key Vault se puede implementar mediante la 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 con la CLI de Azure.

   {   
        "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":  "c7373ae5-91c2-4165-8ab6-7381d6e75619"
        }      
     }

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"

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"

Solución de problemas

Estas son algunas 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?

La extensión depende del comportamiento predeterminado de la API PFXImportCertStore. De manera predeterminada, si un certificado tiene un atributo de nombre de proveedor que coincide con CAPI1, el certificado se importa mediante las API de CAPI1. De lo contrario, el certificado se importa mediante las API de 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 el enlace de canal S en la renovación de certificados cuando la propiedad linkOnRenewal está establecida en true.

Para IIS, puede configurar el reenlace automático habilitando el reenlace automático de renovaciones de certificados en IIS. La extensión de máquina virtual de Azure Key Vault genera notificaciones de ciclo de vida de certificados cuando se instala un certificado con una SAN coincidente. IIS usa este evento para volver a enlazar automáticamente el certificado. Para obtener más información, consulte Reenlazamiento 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.

Archivo de registro Descripción
C:\WindowsAzure\Logs\WaAppAgent.log` Muestra cuándo se producen actualizaciones en la extensión.
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<versión más reciente>\ Muestra el estado de la descarga del certificado. La ubicación de descarga siempre será la ubicación de almacenamiento MY del equipo Windows (certlm.msc).
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<versión más reciente>\RuntimeSettings\ Los registros del servicio de extensión de máquina virtual de Key Vault muestran el estado del servicio akvvm_service.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<versión más reciente>\Status\ La configuración y los archivos binarios del servicio de extensión de máquina virtual de Key Vault.

Obtención de soporte técnico

Estas son otras opciones que le ayudarán a resolver los problemas de implementación: