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

  • Artigo

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 operativos

A extensão Key Vault VM suporta as seguintes versões do Windows:

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

A extensão de VM do Cofre da Chave também é suportada 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 suportados

A extensão de VM do Cofre da Chave suporta os seguintes tipos de conteúdo de certificado:

  • PKCS #12
  • PEM

Nota

A extensão VM do Cofre da Chave baixa todos os certificados para o armazenamento 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 Key Vault VM para Windows adiciona suporte para os 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 à Religação de Certificados do IIS

Pré-requisitos

Analise os seguintes pré-requisitos para usar a extensão de VM do Cofre da Chave 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 Cofre da Chave deve ser atribuída no nível de escopo do Cofre da Chave para VMs e identidade gerenciada dos Conjuntos de Escala de Máquina Virtual do Azure. Essa função recupera a parte de um certificado de um segredo. Para obter mais informações, consulte os seguintes artigos que podem estar em inglês:

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

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

  • A extensão Key Vault VM deve ter a seguinte authenticationSettings configuração:

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

Nota

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áquina Virtual. Este método requer uma política com permissões get e list em segredos. Para obter mais informações, consulte Atribuir uma política de acesso ao Cofre da Chave.

Esquema de extensão

O JSON a seguir mostra o esquema para a extensão de VM do Cofre da Chave. 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 configurações são consideradas informações públicas.

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

    Este formulário é preferido porque o caminho retorna o certificado completo, incluindo a chave privada, mas o /secrets/certificates caminho não. Para obter mais informações sobre certificados, consulte Visão geral de chaves, segredos e certificados 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 essa propriedade com uma identidade atribuída ao 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:  "c7373ae5-91c2-4165-8ab6-7381d6e75619">
         }
      }
   }
}

Valores de propriedade

O esquema JSON inclui as seguintes propriedades.

Nome Valor/Exemplo Tipo de dados
apiVersion 2022-08-01 data
publisher Microsoft.Azure.KeyVault string
type KeyVaultForWindows string
typeHandlerVersion "3.0" string
pollingIntervalInS "3600" string
linkOnRenewal (opcional) verdadeiro boolean
requireInitialSync (opcional) false boolean
observedCertificates [{...}, {...}] matriz de cadeia de caracteres
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate" string
observedCertificates/certificateStoreName MY string
observedCertificates/certificateStoreLocation LocalMachine ou CurrentUser (diferencia maiúsculas de minúsculas) string
observedCertificates/keyExportable (opcional) false boolean
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" string
msiClientId C7373AE5-91C2-4165-8AB6-7381D6E75619 string

Implementação de modelos

As extensões de VM do Azure podem ser implantadas com modelos do Azure Resource Manager (ARM). Os modelos são ideais ao implantar uma ou mais máquinas virtuais que exigem atualização pós-implantação de certificados. A extensão pode ser implantada em VMs individuais ou instâncias de Conjuntos de Escala de Máquina Virtual. O esquema e a configuração são comuns a ambos os tipos de modelo.

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

Os trechos JSON a seguir fornecem configurações de exemplo para uma implantação de modelo ARM da extensão VM do Cofre da Chave.

{
   "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: "c7373ae5-91c2-4165-8ab6-7381d6e75619">
         }
      }
   }
}

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

Você pode habilitar a extensão de VM do Cofre da Chave para dar suporte à ordem de dependência de extensão. Por padrão, a extensão de VM do Cofre da Chave 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 iniciados, poderá habilitar a ordem de dependência de extensão na extensão VM do Cofre de Chaves. Esse recurso permite que outras extensões declarem uma dependência na extensão de VM do Cofre da Chave.

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 VM do Cofre da Chave tenta baixar e instalar novamente os 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 Cofre da Chave relatará um início bem-sucedido.

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

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

Para obter mais informações sobre como configurar dependências entre extensões, consulte Provisionamento de extensão de sequência em conjuntos de escala de máquina virtual.

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 ao sistema e atualiza uma política de acesso ao Cofre da Chave com essa identidade. Se você tentar usar o recurso nesse cenário, ocorrerá um impasse porque a política de acesso do Cofre da Chave não pode ser atualizada até que todas as extensões sejam iniciadas. Em vez disso, use uma identidade MSI atribuída por um único usuário e pré-ACL seus cofres de chaves com essa identidade antes de implantar.

Implantação do Azure PowerShell

A extensão de VM do Azure Key Vault pode ser implantada com o Azure PowerShell. Salve as configurações de extensão de 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 de VM do Cofre da Chave 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":  "c7373ae5-91c2-4165-8ab6-7381d6e75619"
   }      
}

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á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 "3.0" -Setting $settings

# Start the deployment
Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss

Implementação da CLI do Azure

A extensão de VM do Azure Key Vault pode ser implantada usando a CLI do Azure. Salve as configurações de extensão de 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 de VM do Cofre da Chave 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":  "c7373ae5-91c2-4165-8ab6-7381d6e75619"
        }      
     }

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áquina Virtual

# Start the deployment
az vmss extension set --name "KeyVaultForWindows" `
 --publisher Microsoft.Azure.KeyVault `
 --resource-group "<resourcegroup>" `
 --vmss-name "<vmssName>" `
 --settings "@settings.json"

Resolver problemas

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

Consulte as perguntas frequentes

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

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

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 de VM do Azure Key Vault gera notificações de ciclo de vida do certificado quando um certificado com uma SAN correspondente é instalado. O IIS usa esse evento para revincular automaticamente o certificado. Para obter mais informações, consulte Certifcate Rebind 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>

  • A 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 Cofre da Chave existem apenas localmente na VM. Reveja os detalhes do registo para ajudar na resolução de problemas.

Ficheiro de registo Description
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 a loja MY do computador Windows (certlm.msc).
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<versão> mais recente\RuntimeSettings\ Os logs do serviço Key Vault VM Extension 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 Key Vault VM Extension.

Obter suporte

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

  • Para obter assistência, contacte os especialistas do Azure nos fóruns de Perguntas e Respostas e Estouro de Pilha.

  • 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 obter informações sobre como usar o suporte do Azure, leia as Perguntas frequentes de suporte do Azure.