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

A extensão VM (máquina virtual) 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 detecta 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 com suporte para a extensão de VM do Key Vault para Windows.

Sistemas operacionais

A extensão de VM Key Vault dá suporte a Windows Server 2022 e Windows Server 2025, tanto no AMD64 quanto no ARM64. No Windows Server 2025, as chaves privadas são salvas no KeyGuard.

Certificados com suporte

A extensão de VM do Key Vault dá suporte aos seguintes tipos de conteúdo de certificado:

• PKCS #12
• PEM

Features

A extensão de VM Key Vault para Windows versão 4.0:

• Instala chaves privadas no KeyGuard se estiver em execução no Windows Server 2025.
• Instala as duas versões mais recentes de cada certificado.
• Executa a validação da cadeia de certificados antes de instalar qualquer certificado que contenha o EKU (Uso de Chave Estendida) da Autenticação do Servidor TLS, incluindo certificados que carregam outras EKUs junto com ele (como a Autenticação de Cliente). Erros de validação de cadeia resultam em falha de provisionamento para a extensão. Certificados sem a EKU de Autenticação de Servidor não estão sujeitos a essa verificação.

Atualizando a partir da 3.0

Se você estiver atualizando a partir da 3.0, os seguintes recursos serão alterados ou removidos:

• pollingIntervalInS agora está limitado a entre 5 e 60 minutos. Por padrão, a sondagem é executada uma vez a cada hora.
• linkOnRenewal foi removido. A vinculação sempre ocorre.
• keyExportable foi removido. Chaves privadas não são mais exportáveis.
• requireInitialSync foi removido. A extensão só relatará êxito se todos os certificados configurados estiverem instalados.
• A configuração de uma versão específica de um certificado não é mais possível.
• As chaves privadas agora são sempre armazenadas por meio da API de Criptografia: CNG (Próxima Geração) em vez de CAPI.

Pré-requisitos

Examine os seguintes pré-requisitos para usar a extensão de VM do Key Vault 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.

• A função Usuário de segredos do Key Vault deve ser atribuída no nível de escopo do Key Vault para VMs e identidades gerenciadas de Conjuntos de Dimensionamento de Máquinas Virtuais do Microsoft Azure. Essa função recupera uma parte secreta de um certificado. Para obter mais informações, consulte os seguintes artigos:

  • Autenticação do Azure Key Vault
  • Use o segredo, a chave e as permissões de certificado do Azure RBAC com o Azure Key Vault
  • Atribuição de função no escopo do Key Vault

• Os Conjuntos de Dimensionamento de Máquinas Virtuais devem ter a seguinte identity configuração:

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

• A extensão de VM do Key Vault deve ter 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 para a extensão da VM de Key Vault. Antes de considerar as opções de implementação de esquema, examine as notas importantes a seguir.

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

• As URLs de certificados observados devem ser no formato https://myVaultName.vault.azure.net/secrets/myCertName.

  Esse formulário é preferencial porque o /secrets caminho retorna o certificado completo, incluindo a chave privada, mas o /certificates caminho não. Para obter mais informações sobre certificados, consulte a visão geral de chaves, segredos e certificados do Azure Key Vault.

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

  Essa propriedade especifica a identidade a ser usada para autenticação no Key Vault. Defina essa propriedade com uma identidade atribuída pelo sistema para evitar problemas com uma extensão de VM com várias 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 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">,
                    "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">
         }
      }
   }
}

Valores de propriedade

O esquema JSON inclui as propriedades a seguir.

Implantação de modelo

As extensões da VM do Azure podem ser implantadas com modelos do Azure Resource Manager (ARM). Modelos são ideais ao implantar uma ou mais máquinas virtuais que exigem renovação de certificados pós-implantação. A extensão pode ser implantada em VMs individuais ou instâncias de 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 é aninhada dentro do modelo VM ou Conjuntos de Dimensionamento de Máquinas Virtuais do Microsoft Azure. Para uma extensão de recurso da VM, a configuração "resources": [] é aninhada no objeto da máquina virtual. Para uma extensão de instância de Conjuntos de Dimensionamento de Máquinas Virtuais do Microsoft Azure, a configuração é aninhada sob o objeto "virtualMachineProfile":"extensionProfile":{"extensions" :[].

Os snippets JSON a seguir fornecem configurações de exemplo para uma implantação de modelo ARM da extensão do Key Vault para VM.

{
   "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.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 de VM Key Vault dá suporte à Atualização Automática de Extensão para máquinas virtuais e conjuntos de dimensionamento em Azure. A extensão é mantida atualizada automaticamente quando as propriedades autoUpgradeMinorVersion e os enableAutomaticUpgrade exemplos anteriores são definidos como true.

Ordenação de dependência da extensão

A extensão de VM Key Vault suporta a ordenação das dependências das extensões. A extensão relata um início bem-sucedido depois de baixar e instalar todos os certificados.

Se você usar outras extensões que exigem a instalação de certificados antes de serem iniciadas, poderá usar a ordem de dependência de extensão para declarar uma dependência na extensão de VM do Key Vault.

Na inicialização, a extensão de VM do Key Vault tenta baixar e instalar certificados até 25 vezes com períodos de recuo crescentes, durante os quais permanece em um estado Transitioning. Se as novas tentativas estiverem esgotadas, a extensão relatará um estado de erro . Depois que todos os certificados forem instalados com êxito, a extensão de VM do Key Vault relatará um início bem-sucedido.

Para obter mais informações sobre como configurar dependências entre extensões, confira Provisionamento de extensão de sequência em Conjuntos de Dimensionamento de Máquinas Virtuais.

Implantação do Azure PowerShell

A extensão da VM do Azure Key Vault pode ser implantada com o Azure PowerShell. Salve as configurações de extensão da VM do Key Vault em um arquivo JSON (settings.json).

Os trechos JSON a seguir fornecem configurações de exemplo para implantar a extensão da VM do Key Vault com o 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áquinas Virtuais do Microsoft Azure

# 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 

Implantação da CLI do Azure

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

Os trechos JSON a seguir fornecem configurações de exemplo para implantar a extensão da VM do Key Vault com 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áquinas Virtuais do Microsoft Azure

# 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

Abaixo algumas sugestões de como solucionar problemas de implantação.

Verificar perguntas frequentes

Há um limite no número de certificados observados?

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

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

Por padrão, administradores e SYSTEM recebem controle total.

Como você determina se uma chave de certificado é CAPI1 ou CNG?

Começando com Key Vault extensão de VM 4.0, as chaves privadas para todos os certificados são salvas por meio de CNG.

A extensão oferece suporte à reassociação automática de certificados?

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

Para o IIS, você pode configurar a reassociação automática habilitando a reassociação automática de renovações de certificado no IIS. A extensão de VM do Azure Key Vault gera notificações de ciclo de vida de certificado quando um certificado com uma SAN correspondente é instalado. O IIS usa este evento para refazer a vinculação do certificado automaticamente. Para obter mais informações, consulte Certificate Rebind no IIS.

Exibir o status da extensão

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

Para exibir o estado de implantação de extensões para 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 logs e configuração

Os logs de extensão da VM do Key Vault existem apenas localmente na VM. Examine os detalhes do log para ajudar na solução de problemas.

Instalação de certificado no Windows

A extensão de VM do Key Vault para Windows instala certificados no repositório de certificados do Windows. Quando um certificado é baixado do Key Vault, a extensão:

1. Instala todos os certificados intermediários e folhas, independentemente de quantos certificados intermediários estão presentes. Os certificados raiz não estão instalados, pois a extensão não está autorizada a executar a instalação raiz. É responsabilidade do proprietário do serviço garantir que o certificado raiz seja confiável no sistema.
   • Os certificados folha são instalados no repositório de certificados (certificateStoreName) e no local (certificateStoreLocation) especificados
   • Os certificados da Autoridade de certificação intermediária são instalados no repositório Autoridades de Certificação Intermediárias
2. Coloca os certificados no repositório de certificados especificado (certificateStoreName) e local (certificateStoreLocation)
3. Aplica permissões apropriadas à chave privada com base na configuração accounts especificada
4. Define a propriedade para garantir que as CERT_RENEWAL associações de certificado em aplicativos como o IIS sejam atualizadas automaticamente quando os certificados forem renovados.

Repositórios de certificados padrão

Se não for especificado, os certificados serão instalados nos seguintes locais por padrão:

• Nome da Loja: MY (Pessoal)
• Local de Armazenamento: LocalMachine

Controle de acesso ao certificado

Por padrão, administradores e SYSTEM recebem permissões de Controle Total em certificados instalados. Você pode personalizar o acesso usando a accounts matriz na configuração do certificado:

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

Isso concede acesso de leitura às contas especificadas, permitindo que aplicativos em execução sob essas identidades utilizem os certificados.

Renovação de certificado

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

1. Baixa a nova versão do certificado.
2. Instala-o no repositório de certificados configurado.
3. Mantém as associações existentes por meio da CERT_RENEWAL propriedade.

Gerenciando o ciclo de vida do certificado

Para aplicativos como o IIS que dão suporte a Notificações de Ciclo de Vida dos Serviços de Certificado, a extensão de VM Key Vault registra o Evento 1001 no Log de Eventos do Windows quando um certificado com um Nome Alternativo da Entidade (SAN) correspondente é instalado. O IIS registra-se neste evento para reassociar automaticamente o certificado renovado sem interrupção do serviço. Outros aplicativos e equipes também podem escutar o Evento 1001 para atuar em renovações de certificado conforme necessário. Para obter mais informações, consulte Notificações do ciclo de vida dos Serviços de Certificados.

Obtenha suporte

Abaixo algumas outras opções para ajudar você a resolver problemas de implantação:

• Para obter assistência, entre em contato com os especialistas do Azure em Microsoft Q& A.

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

• Você também pode entrar em contato com o Suporte da Microsoft. Para obter informações sobre como usar Suporte do Azure, consulte Como criar uma solicitação Suporte do Azure.