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 2019 y versiones posteriores. 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 n.º 12
• PEM

Características

La extensión de máquina virtual de Key Vault para Windows versión 3.0 admite:

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

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

• Debe asignarse el rol Usuario de secretos de Key Vault en el ámbito de Key Vault para las máquinas virtuales y la identidad administrada de Azure Virtual Machine Scale Sets. Este rol recupera la parte de un secreto 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

• Virtual Machine Scale Sets debe tener la configuración identity siguiente:

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

• La extensión de máquina virtual de Key Vault debe tener la configuración authenticationSettings siguiente:

  "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. 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 más información sobre los certificados, consulte Información general sobre claves, secretos y certificados de Azure Key Vault.

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

Valores de propiedad

El esquema JSON incluye las siguientes propiedades.

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

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 reintentará la descarga e instalación de certificados hasta 25 veces con períodos de retroceso crecientes, durante los que permanece en estado de transición . Si se agotan los reintentos, la extensión notificará 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 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, consulte Aprovisionamiento de extensiones de secuencia en virtual Machine Scale Sets.

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

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 se basa en el 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, configure 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 Certifcate Rebind 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 se descarga un certificado desde Key Vault, la extensión:

1. Instala todos los certificados intermedios y hoja, independientemente del número de certificados intermedios que estén presentes. Los certificados raíz no están instalados, ya que la extensión no está autorizada para realizar la instalación raíz. Es responsabilidad del propietario del servicio asegurarse de que el certificado raíz es de confianza en el sistema.
   • Los certificados de nodo final se instalan en el almacén de certificados especificado (certificateStoreName) y en la ubicación (certificateStoreLocation)
   • Los certificados de entidad de certificación intermedios se instalan en el almacén de entidades 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 según el accounts especificado en la configuración.
4. Establece la linkOnRenewal propiedad (si está habilitada) para asegurarse de que los enlaces de certificado en aplicaciones como IIS se actualizan automáticamente cuando se renuevan los certificados.

Almacenes predeterminados de certificados

Si no se especifica, los certificados se instalan en las siguientes ubicaciones de forma predeterminada:

• Nombre de la tienda: MY (Personal)
• Ubicación del almacén: 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"]

Esto concede acceso de lectura a las cuentas especificadas, lo que permite a las aplicaciones que se ejecutan en esas identidades usar 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. Lo instala en el almacén de certificados configurado.
3. Mantiene los enlaces existentes a través de la linkOnRenewal característica si está habilitado.

Administración del ciclo de vida de los certificados

En el caso de aplicaciones como IIS que admiten notificaciones de ciclo de vida de certificados, la extensión genera eventos cuando se instalan certificados con nombres alternativos de firmante (SAN) coincidentes, lo que permite el reenlace automático sin interrupción del servicio.

Obtención de soporte técnico

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

• Para obtener ayuda, póngase en contacto con los expertos de Azure en los foros de Q&A y Stack Overflow.

• 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 más información sobre el uso del soporte técnico de Azure, lea las preguntas más frecuentes sobre el soporte técnico de Azure.