Compartilhar via

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 do Key Vault dá suporte às seguintes versões do Windows:

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

A extensão de VM do Key Vault também tem suporte em uma VM local personalizada. A VM deve ser carregada e convertida em uma imagem especializada para uso no Azure usando a instalação principal do Windows Server 2019.

Certificados com suporte

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

  • PKCS #12
  • PEM

Observação

A extensão de VM do Key Vault baixa todos os certificados para o repositório de certificados do Windows ou para o local especificado na certificateStoreLocation propriedade nas configurações de extensão da VM.

Atualizações na versão 3.0+

A versão 3.0 da extensão de VM do Key Vault para Windows adiciona suporte aos seguintes recursos:

  • Adicionar permissões de ACL a certificados baixados
  • Habilitar a configuração do Repositório de Certificados por certificado
  • Exportar chaves privadas
  • Suporte à reassociação de certificado do IIS

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 a parte do segredo de um certificado. Para obter mais informações, consulte os seguintes artigos:

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

Observação

O antigo modelo de permissão de política de acesso também pode ser usado para fornecer acesso a VMs e Conjuntos de Dimensionamento de Máquinas Virtuais do Microsoft Azure. Esse método requer uma política com permissões obter e lista em segredos. Para obter mais informações, consulte Atribuir uma política de acesso do Key Vault.

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

O esquema JSON inclui as propriedades a seguir.

Nome Valor/exemplo Tipo de dados
apiVersion 2022-08-01 date
publisher Microsoft.Azure.KeyVault cadeia de caracteres
type KeyVaultForWindows cadeia de caracteres
typeHandlerVersion "3.0" cadeia de caracteres
pollingIntervalInS "3600" cadeia de caracteres
linkOnRenewal (opcional) verdadeiro booleano
requireInitialSync (opcional) falso booleano
observedCertificates [{...}, {...}] matriz de cadeia de caracteres
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate" cadeia de caracteres
observedCertificates/certificateStoreName MEU string
observedCertificates/certificateStoreLocation LocalMachine ou CurrentUser (sensível a maiúsculas e minúsculas) cadeia de caracteres
observedCertificates/keyExportable (opcional) falso booleano
observedCertificates/accounts (opcional) ["Serviço de Rede", "Serviço Local"] matriz de cadeia de caracteres
msiEndpoint "http://169.254.169.254/metadata/identity/oauth2/token" cadeia de caracteres
msiClientId 00001111-aaaa-2222-bbbb-3333cccc4444 string

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

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

Você pode habilitar a extensão de máquina virtual do Key Vault para dar suporte à ordenação de dependência de extensões. Por padrão, a extensão de VM do Key Vault relata um início bem-sucedido assim que a sondagem começa. No entanto, você pode configurar a extensão para relatar um início bem-sucedido somente depois que a extensão baixar e instalar todos os certificados.

Se você usar outras extensões que exijam a instalação de todos os certificados antes de serem iniciadas, você poderá habilitar a ordenação de dependências de extensões na extensão de VM do Key Vault. Esse recurso permite que outras extensões declarem uma dependência na extensão da VM do Key Vault.

Você pode usar esse recurso para impedir que outras extensões sejam iniciadas até que todos os certificados dependentes sejam instalados. Quando o recurso está habilitado, a extensão de VM do Key Vault tenta baixar e instalar certificados indefinidamente e permanece em um estado de transição , até que todos os certificados sejam instalados com êxito. Depois que todos os certificados estiverem presentes, a extensão de VM do Key Vault relatará um início bem-sucedido.

Para habilitar o recurso de ordenação de dependência de extensão na extensão da VM do Key Vault, defina a propriedade secretsManagementSettings:

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

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.

Importante

O recurso de ordenação de dependência de extensão não é compatível com um modelo ARM que cria uma identidade atribuída pelo sistema e atualiza uma política de acesso do Key Vault com essa identidade. Se você tentar usar o recurso nesse cenário, ocorrerá um deadlock porque a política de acesso do Key Vault não poderá ser atualizada até que todas as extensões sejam iniciadas. Em vez disso, use uma identidade MSI atribuída a um único usuário e configure previamente o ACL de seus cofres de chaves com essa identidade antes de implantar.

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

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 "3.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 "3.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": {
          "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"
        }      
     }

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"

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"

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?

A extensão depende do comportamento padrão da API PFXImportCertStore. Por padrão, se um certificado tiver um atributo nome de provedor que corresponda ao CAPI1, o certificado será importado usando APIs CAPI1. Caso contrário, o certificado será importado usando APIs 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 Key Vault VM oferece suporte à vinculação de canal S na renovação de certificado quando a propriedade linkOnRenewal é definida como verdadeira.

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 Certifcate Rebind in 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.

Arquivo de log Descrição
C:\WindowsAzure\Logs\WaAppAgent.log' Mostra quando ocorrem atualizações na extensão.
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows< versão >mais recente\ Mostra o status do download do certificado. O local de download é sempre o my store do computador Windows (certlm.msc).
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<versão mais recente>\RuntimeSettings\ Os logs de serviço da Extensão de VM do Key Vault mostram o status do serviço akvvm_service.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<versão mais recente>\Status\ A configuração e os binários para o serviço de Extensão de VM do Key Vault.

Obtenha suporte

Aqui estão algumas outras opções para ajudá-lo a resolver problemas de implantação: