Extensão de máquina virtual do Azure Key Vault para Windows

A extensão de máquina virtual (VM) do Azure Key Vault fornece atualização automática de certificados armazenados em um cofre de chaves do Azure. A extensão monitora uma lista de certificados observados armazenados em cofres de chaves. Quando deteta uma alteração, a extensão recupera e instala os certificados correspondentes. Este artigo descreve as plataformas, configurações e opções de implantação suportadas para a extensão de VM do Cofre da Chave para Windows.

Sistemas operacionais

A extensão Key Vault VM suporta Windows Server 2022 e Windows Server 2025, tanto em AMD64 como em ARM64. No Windows Server 2025, as chaves privadas são guardadas no KeyGuard.

Certificados suportados

A extensão de VM do Cofre de Chaves suporta os seguintes tipos de conteúdos de certificados:

• PKCS #12
• PEM

Caraterísticas

A extensão Key Vault VM para Windows versão 4.x:

• Instala chaves privadas no KeyGuard se estiver a correr no Windows Server 2025 e o KeyGuard estiver operacional.
• Instala as duas versões mais recentes de cada certificado.
• Realiza a validação da cadeia de certificados antes de instalar qualquer certificado que contenha o TLS Server Authentication Extended Key Usage (EKU), incluindo certificados que transportam outros EKUs juntamente (como a Autenticação do Cliente). Erros de validação em cadeia resultam numa falha de provisionamento para a extensão. Certificados sem a EKU de Autenticação do Servidor, e certificados auto-assinados (onde o sujeito e o emissor são idênticos), não estão sujeitos a esta verificação.
• Associa todos os certificados na máquina que têm origem no mesmo objeto de certificado do Key Vault à versão mais recente desse certificado.
• Suporta uma substituição opcional da autenticação para cada certificado, que permite que certificados monitorizados individualmente se autentiquem junto do Key Vault com uma identidade gerida diferente da identidade gerida predefinida da extensão. Para mais informações, consulte Esquema de extensão.

Atualização da versão 3.0

Se estiver a atualizar a partir da 3.0, as seguintes funcionalidades são alteradas ou removidas:

• pollingIntervalInS está agora limitado a entre 5 e 60 minutos. Por predefinição, a extensão verifica uma vez por hora.
• linkOnRenewal é removido. A ligação ocorre sempre.
• keyExportable é removido. As chaves privadas já não são exportáveis.
• requireInitialSync é removido. A extensão só reporta sucesso se instalar todos os certificados configurados.
• Já não pode configurar uma versão específica de um certificado.
• A extensão agora armazena sempre as chaves privadas usando a Cryptography API: Next Generation (CNG) em vez de CAPI.

Pré-requisitos

Analise os seguintes pré-requisitos para usar a extensão de Máquina Virtual (VM) do Cofre de Chaves para Windows:

• Uma instância do Azure Key Vault com um certificado. Para obter mais informações, consulte Criar um cofre de chaves usando o portal do Azure.

• Uma VM com uma identidade gerenciada atribuída.

• Atribua o papel Utilizador de Segredos do Key Vault ao nível do âmbito do Key Vault à identidade gerida da VM ou dos Conjuntos de Dimensionamento de Máquinas Virtuais do Azure. Esta função recupera a parte secreta de um certificado. Para obter mais informações, consulte os seguintes artigos:

  • Autenticação no Cofre da Chave do Azure
  • Utilizar permissões de segredo, chave e certificado do Controlo de Acesso Baseado em Funções (RBAC) do Azure com o Azure Key Vault
  • Atribuição de função no escopo do Key Vault

• Configure os Conjuntos de Dimensionamento de Máquinas Virtuais utilizando a seguinte identity configuração:

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

• Configure a extensão da VM Key Vault com a seguinte authenticationSettings configuração:

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

Esquema de extensão

O JSON a seguir mostra o esquema da extensão de VM do Key Vault. Antes de considerar as opções de implementação do esquema, revise as seguintes observações importantes.

• A extensão não requer configurações protegidas. Todas as definições são informação pública.

• Os URLs de certificados observados devem usar o formulário https://myVaultName.vault.azure.net/secrets/myCertName.

  Este formulário é obrigatório porque o /secrets path devolve o certificado completo, incluindo a chave privada, mas o /certificates path não. Para obter mais informações sobre certificados, consulte Visão geral de chaves, segredos e certificados do Azure Key Vault. Não podes especificar uma versão específica do certificado.

• O host URL deve ser um host reconhecido do Azure Key Vault.

• A authenticationSettings propriedade é necessária para VMs com identidades atribuídas ao usuário.

  Esta propriedade especifica a identidade a ser usada para autenticação no Cofre da Chave. Defina esta propriedade com uma identidade atribuída pelo sistema para evitar problemas com uma extensão de VM com múltiplas 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 propriedade

O esquema JSON inclui as seguintes propriedades.

Implementação de modelos

Implemente extensões VM do Azure utilizando templates do Azure Resource Manager (ARM). Os modelos são ideais quando implementa uma ou mais máquinas virtuais que requerem uma atualização pós-implementação dos certificados. Pode implementar a extensão em VMs individuais ou instâncias do Conjuntos de Dimensionamento de Máquinas Virtuais. O esquema e a configuração são comuns a ambos os tipos de modelo.

A configuração JSON para uma extensão do cofre de chaves está inserida dentro do modelo de VM ou Conjuntos de Escala de Máquina Virtual. Para uma extensão de recurso de VM, a configuração é aninhada dentro do objeto de máquina virtual "resources": []. Para uma extensão de instância do Conjuntos de Dimensionamento de Máquinas Virtuais, a configuração é aninhada sob o "virtualMachineProfile":"extensionProfile":{"extensions" :[] objeto.

Os trechos JSON a seguir fornecem configurações de exemplo para um modelo de implantação ARM da extensão de máquina virtual do Cofre de Chaves.

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

Atualização automática de extensão

A extensão VM Key Vault suporta a atualização automática de extensões para máquinas virtuais e conjuntos de escala no Azure. O Azure mantém a extensão atualizada automaticamente quando defines as autoUpgradeMinorVersion propriedades e enableAutomaticUpgrade nos exemplos anteriores como true.

Ordenação de dependências de extensões

A extensão VM Key Vault suporta ordenação de dependências de extensão. A extensão reporta um arranque bem-sucedido após descarregar e instalar todos os certificados.

Se usares outras extensões que exijam a instalação de certificados antes de começarem, podes usar a ordem de dependência de extensões para declarar uma dependência na extensão VM do Key Vault.

No arranque, a extensão VM Key Vault tenta descarregar e instalar certificados até 25 vezes, com períodos de recuo crescentes, durante os quais permanece num estado Transição. Se as tentativas forem esgotadas, a extensão reporta um estado de Erro . Depois que todos os certificados forem instalados com êxito, a extensão de VM do Cofre da Chave relatará um início bem-sucedido.

Para mais informações sobre a configuração de dependências entre extensões, consulte Provisão de extensões de sequência em Conjuntos de Dimensionamento de Máquinas Virtuais.

Implantação do Azure PowerShell

Implemente a extensão VM do Azure Key Vault usando Azure PowerShell. Salve as configurações de extensão de VM do Key Vault em um arquivo JSON (settings.json).

Os seguintes excertos JSON fornecem exemplos de definições para a implementação da extensão VM Key Vault usando 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"
   }
}

Implantar em uma 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

Implantar em uma instância de Conjuntos de Dimensionamento de Máquina Virtual

# 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

Implementação da CLI do Azure

Implemente a extensão VM do Azure Key Vault usando a CLI do Azure. Salve as configurações de extensão de VM do Key Vault em um arquivo JSON (settings.json).

Os seguintes excertos JSON fornecem exemplos de definições para a implementação da extensão VM Key Vault utilizando a CLI do 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"
        }
     }

Implantar em uma 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"

Implantar em uma instância de Conjuntos de Dimensionamento de Máquina Virtual

# 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 sugestões para resolver problemas de implementação.

Consulte as perguntas frequentes

Existe um limite para o número de certificados observados?

Não. A extensão Key Vault VM não limita o número de certificados observados (observedCertificates).

Qual é a permissão padrão quando nenhuma conta é especificada?

Por padrão, os Administradores e o SISTEMA recebem Controle Total.

Como determinar se uma chave de certificado é CAPI1 ou CNG?

A partir da extensão 4.0 da Key Vault VM, a extensão guarda chaves privadas para todos os certificados usando CNG.

A extensão suporta a revinculação automática do certificado?

Sim, a extensão de VM do Azure Key Vault dá suporte à revinculação automática de certificados. A extensão VM Key Vault suporta a ligação do canal S na renovação do certificado.

Para o IIS, você pode configurar a revinculação automática habilitando a revinculação automática de renovações de certificados no IIS. A extensão VM do Azure Key Vault gera Notificações do Ciclo de Vida dos Certificados quando instala um certificado renovado para o mesmo objeto de certificado do Key Vault que um certificado existente. O IIS usa esse evento para revincular automaticamente o certificado. Para mais informações, consulte Reencadernação de Certificados no IIS.

Ver estado da extensão

Verifique o status da sua implantação de extensão no portal do Azure ou usando o PowerShell ou a CLI do Azure.

Para ver o estado de implantação das extensões de uma determinada VM, execute os seguintes comandos.

• Azure PowerShell:

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

• CLI do Azure:

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

Revisar registros e configuração

Os registos de extensão da VM do Key Vault existem apenas localmente na VM. Reveja os detalhes do registo para ajudar na resolução de problemas.

Instalação de certificados no Windows

A extensão de VM do Cofre da Chave para Windows instala certificados no armazenamento de certificados do Windows. Quando a extensão descarrega um certificado do Key Vault, ela:

1. Instala todos os certificados intermediários e finais, independentemente de quantos certificados intermediários estejam presentes. A extensão não instala certificados raiz porque não está autorizada a instalá-los. Certifique-se de que o certificado raiz é confiável no sistema.
   • Instala certificados de folha no armazenamento de certificados especificado (certificateStoreName) e na localização especificada (certificateStoreLocation).
   • Instala certificados CA intermédios na loja de Autoridades Certificadoras Intermédias.
2. Coloca os certificados no armazenamento de certificados especificados (certificateStoreName) e na localização (certificateStoreLocation).
3. Aplica permissões apropriadas à chave privada com base no accounts especificado na configuração.
4. Define a CERT_RENEWAL propriedade para que as ligações de certificados em aplicações como o IIS sejam atualizadas automaticamente quando os certificados são renovados. Um certificado está encadeado à versão mais recente que se origina do mesmo objeto certificado do Key Vault, identificado pela URL base secreta do Key Vault do certificado. Certificados que correspondem a diferentes objetos de certificados do Key Vault nunca estão ligados entre si.

Arquivos de certificados predefinidos

Por defeito, a extensão instala certificados nas seguintes localizações:

• Nome da loja: MY (Pessoal).
• Localização da loja: LocalMachine.

Controlo de acesso a certificados

Por padrão, Administradores e SYSTEM recebem permissões de Controle Total nos certificados instalados. Pode personalizar o acesso usando o accounts array na configuração do certificado:

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

Esta configuração concede acesso de leitura às contas especificadas, o que permite que aplicações a correr sob essas identidades utilizem os certificados.

Renovação do certificado

Quando os certificados são renovados no Key Vault, a extensão automaticamente:

1. Descarrega a nova versão do certificado.
2. Instala o certificado na loja de certificados configurada.
3. Mantém as fixações existentes utilizando a CERT_RENEWAL propriedade.

Gerir o ciclo de vida dos certificados

Para aplicações como o IIS que suportam Notificações do Ciclo de Vida dos Serviços de Certificação, a extensão VM Key Vault levanta o Evento 1001 no Registo de Eventos do Windows quando instala um certificado renovado para o mesmo objeto de certificado Key Vault que um certificado existente (ligando o novo certificado ao seu antecessor). O IIS subscreve este evento para reassociar automaticamente o certificado renovado sem interromper o serviço. Outras aplicações e equipas também podem monitorizar o Evento 1001 para atuar nas renovações de certificados quando necessário. Para mais informações, consulte Notificações do Ciclo de Vida dos Serviços de Certificados.

Obter suporte

A Microsoft oferece suporte apenas para a versão principal 3.0 e posteriores da extensão VM Key Vault. Se estiveres a usar a versão 1.0, atualiza para a versão mais recente antes de pedir suporte.

Use estas outras opções para ajudar a resolver problemas de implementação:

• Para assistência, contacte os especialistas Azure em Microsoft Q& A.

• Se você não encontrar uma resposta no site, poderá postar uma pergunta para entrada da Microsoft ou de outros membros da comunidade.

• Também pode contactar o Suporte da Microsoft. Para informações sobre a utilização de suporte do Azure, veja Como criar um pedido de suporte do Azure.