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.x:

• Instala chaves privadas no KeyGuard se estiver em execução no Windows Server 2025 e o KeyGuard estiver operacional.
• 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 e certificados autoassinados (em que o assunto e o emissor são idênticos) não estão sujeitos a essa verificação.
• Encadeia todos os certificados no computador que se originam do mesmo objeto de certificado Key Vault para a versão mais recente desse certificado.
• Dá suporte a uma substituição opcional de autenticação por certificado, que permite que cada certificado monitorado se autentique no Key Vault com uma identidade gerenciada diferente da identidade padrão da extensão. Para obter mais informações, consulte Esquema de extensão.

Atualizando de 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 extensão vota 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 instalar todos os certificados configurados.
• Você não pode mais configurar uma versão específica de um certificado.
• A extensão agora sempre armazena chaves privadas usando a 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.

• Atribua a função Usuário de Segredos do Key Vault no nível do escopo do Key Vault à identidade gerenciada da VM ou dos Conjuntos de Dimensionamento de Máquinas Virtuais do Azure. Essa função recupera a 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

• Configure os Conjuntos de dimensionamento de máquinas virtuais com a seguinte configuração identity:

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

• Configure a extensão de 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 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 informações públicas.

• As URLs de certificado observadas devem usar o formulário https://myVaultName.vault.azure.net/secrets/myCertName.

  Esse formulário é necessário 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. Você não pode especificar uma versão específica do certificado.

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

• 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 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 propriedades a seguir.

Implantação de modelo

Implante Azure extensões de VM usando modelos Azure Resource Manager (ARM). Os modelos são ideais quando você implanta uma ou mais máquinas virtuais que exigem a atualização pós-implantação de certificados. Você pode implantar a extensão em VMs individuais ou em 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 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 de VM do Key Vault oferece suporte à atualização automática da extensão para máquinas virtuais e conjuntos de dimensionamento no Azure. O Azure mantém a extensão atualizada automaticamente quando você define as propriedades autoUpgradeMinorVersion e enableAutomaticUpgrade como true nos exemplos anteriores.

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 retirada crescentes, durante os quais permanece em um estado Em transição. 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, consulte o provisionamento sequencial de extensões em Conjuntos de Dimensionamento de Máquinas Virtuais.

Implantação do Azure PowerShell

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

Os snippets JSON a seguir fornecem configurações de exemplo para implantar a extensão de VM Key Vault usando 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

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

Os snippets JSON a seguir fornecem configurações de exemplo para implantar a extensão de VM Key Vault usando o 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

Use essas sugestões para 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, a extensão salva chaves privadas para todos os certificados usando 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 do 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 do ciclo de vida do certificado quando instala um certificado renovado para o mesmo objeto de certificado do Key Vault que um certificado existente. 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 do certificado no Windows

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

1. Instala todos os certificados intermediários e folhas, independentemente de quantos certificados intermediários estão presentes. A extensão não instala certificados raiz porque não está autorizado a instalá-los. Verifique se o certificado raiz é confiável no sistema.
   • Instala certificados folha no repositório de certificados especificado (certificateStoreName) e no local (certificateStoreLocation).
   • Instala certificados de AC intermediários no repositório de 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 no accounts especificado na configuração.
4. Define a propriedade para que as CERT_RENEWAL associações de certificado em aplicativos como o IIS sejam atualizadas automaticamente quando os certificados forem renovados. Um certificado é encadeado à versão mais recente que se origina do mesmo objeto de certificado Key Vault, identificado pela URL base secreta Key Vault do certificado. Certificados que correspondem a diferentes objetos de certificado Key Vault nunca são vinculados uns aos outros.

Repositórios de certificados padrão

Por padrão, a extensão instala certificados nos seguintes locais:

• Nome da loja: MY (Pessoal).
• Local da loja: 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"]

Essa configuração concede acesso de leitura às contas especificadas, o que permite que aplicativos em execução nessas identidades usem 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 certificado no repositório de certificados configurado.
3. Mantém as associações existentes usando a 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 gera o Evento 1001 no Log de Eventos do Windows quando instala um certificado renovado para o mesmo objeto de certificado Key Vault que um certificado existente (vinculando o novo certificado ao seu antecessor). O IIS se inscreve nesse evento para reassociar automaticamente o certificado renovado sem interromper o 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

Microsoft fornece suporte apenas para a versão principal 3.0 e posterior da extensão de VM Key Vault. Se você estiver usando a versão 1.0, atualize para a versão mais recente antes de solicitar suporte.

Use estas outras opções para ajudar 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.