Gerenciar o Cofre da Chave usando a CLI do Azure

  • Artigo

Este artigo aborda como começar a trabalhar com o Azure Key Vault usando a CLI do Azure. Você pode ver informações sobre:

  • Como criar um contêiner protegido (um cofre) no Azure
  • Adicionar uma chave, segredo ou certificado ao cofre de chaves
  • Registrando um aplicativo com o Microsoft Entra ID
  • Autorizando um aplicativo a usar uma chave ou segredo
  • Definindo políticas avançadas de acesso do cofre de chaves
  • Trabalhando com módulos de segurança de hardware (HSMs)
  • Eliminar o cofre de chaves e as chaves e segredos associados
  • Comandos diversos da interface de linha de comando entre plataformas do Azure

O Cofre de Chaves do Azure chave está disponível na maior parte das regiões. Para obter mais informações, consulte a página de preços do Cofre de Chaves.

Nota

Este artigo não inclui instruções sobre como escrever o aplicativo do Azure que uma das etapas inclui, que mostra como autorizar um aplicativo a usar uma chave ou segredo no cofre de chaves.

Para obter uma visão geral do Azure Key Vault, consulte O que é o Azure Key Vault?) Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

Pré-requisitos

Para usar os comandos da CLI do Azure neste artigo, você deve ter os seguintes itens:

  • Uma subscrição do Microsoft Azure. Se não tiver uma, pode inscrever-se numa avaliação gratuita.
  • CLI do Azure versão 2.0 ou posterior. Para instalar a versão mais recente, consulte Instalar a CLI do Azure.
  • Um aplicativo que será configurado para usar a chave ou senha que você cria neste artigo. Uma aplicação de exemplo está disponível a partir do Centro de Transferências da Microsoft. Para obter instruções, consulte o arquivo Leiame incluído.

Obter ajuda com a Interface de Linha de Comandos entre Plataformas do Azure

Este artigo pressupõe que você esteja familiarizado com a interface de linha de comando (Bash, Terminal, Prompt de comando).

O parâmetro --help ou -h pode ser usado para exibir a ajuda para comandos específicos. Como alternativa, o formato de ajuda do Azure [comando] [opções] também pode ser usado. Em caso de dúvida sobre os parâmetros necessários para um comando, consulte a ajuda. Por exemplo, todos os comandos a seguir retornam as mesmas informações:

az account set --help
az account set -h

Também pode ler os seguintes artigos para se familiarizar com o Azure Resource Manager na Interface de Linha de Comandos entre Plataformas do Azure:

Como criar um contêiner protegido (um cofre) no Azure

Os cofres são contêineres seguros apoiados por módulos de segurança de hardware. Os cofres centralizam o armazenamento dos segredos das aplicações, o que ajuda a reduzir as possibilidades de perda acidental de informações de segurança. Os cofres de chaves também controlam e registam o acesso a tudo o que está armazenado nos mesmos. O Azure Key Vault pode processar pedidos e renovações de certificados Transport Layer Security (TLS), proporcionando as funcionalidades inerentes a uma solução de gestão de ciclo de vida de certificados robusta. Nas próximas etapas, você criará um cofre.

Ligar às suas subscrições

Para entrar interativamente, use o seguinte comando:

az login

Para entrar usando uma conta organizacional, você pode passar seu nome de usuário e senha.

az login -u username@domain.com -p password

Se você tiver mais de uma assinatura e precisar especificar qual usar, digite o seguinte para ver as assinaturas da sua conta:

az account list

Especifique uma assinatura com o parâmetro de assinatura.

az account set --subscription <subscription name or ID>

Para obter mais informações sobre como configurar a Interface de Linha de Comando entre Plataformas do Azure, consulte Instalar a CLI do Azure.

Criar um novo grupo de recursos

Ao usar o Gerenciador de Recursos do Azure, todos os recursos relacionados são criados dentro de um grupo de recursos. Você pode criar um cofre de chaves em um grupo de recursos existente. Se quiser usar um novo grupo de recursos, você pode criar um novo.

az group create -n "ContosoResourceGroup" -l "East Asia"

O primeiro parâmetro é o nome do grupo de recursos e o segundo parâmetro é o local. Para obter uma lista de todos os locais possíveis, digite:

az account list-locations

Registrar o provedor de recursos do Key Vault

Poderá ver o erro "A subscrição não está registada para utilizar o espaço de nomes 'Microsoft.KeyVault'" quando tenta criar um novo cofre de chaves. Se essa mensagem for exibida, verifique se o provedor de recursos do Cofre da Chave está registrado em sua assinatura. Esta é uma operação única para cada subscrição.

az provider register -n Microsoft.KeyVault

Criar um cofre de chaves

Use o az keyvault create comando para criar um cofre de chaves. Este script tem três parâmetros obrigatórios: um nome de grupo de recursos, um nome de cofre de chaves e a localização geográfica.

Para criar um novo cofre com o nome ContosoKeyVault, no grupo de recursos ContosoResourceGroup, residente no local do Leste Asiático , digite:

az keyvault create --name "ContosoKeyVault" --resource-group "ContosoResourceGroup" --location "East Asia"

A saída deste comando mostra as propriedades do cofre de chaves que você criou. As duas propriedades mais importantes são:

  • name: No exemplo, o nome é ContosoKeyVault. Você usará esse nome para outros comandos do Cofre da Chave.
  • vaultUri: No exemplo, o URI é https://contosokeyvault.vault.azure.net. As aplicações que utilizam o cofre através da respetiva API têm de utilizar este URI.

A sua conta do Azure pode agora realizar quaisquer operações neste cofre de chaves. Até o momento, ninguém mais está autorizado.

Adicionar uma chave, segredo ou certificado ao cofre de chaves

Se pretender que o Azure Key Vault crie uma chave protegida por software para si, utilize o az key create comando.

az keyvault key create --vault-name "ContosoKeyVault" --name "ContosoFirstKey" --protection software

Se você tiver uma chave existente em um arquivo .pem, poderá carregá-la no Cofre de Chaves do Azure. Você pode optar por proteger a chave com software ou HSM. Este exemplo importa a chave do arquivo .pem e a protege com software, usando a senha "hVFkk965BuUv":

az keyvault key import --vault-name "ContosoKeyVault" --name "ContosoFirstKey" --pem-file "./softkey.pem" --pem-password "hVFkk965BuUv" --protection software

Agora você pode fazer referência à chave que criou ou carregou no Cofre de Chaves do Azure usando seu URI. Use https://ContosoKeyVault.vault.azure.net/keys/ContosoFirstKey para obter sempre a versão atual. Use https://<keyvault-name>.vault.azure.net/keys/<keyname>/<key-unique-id> para obter esta versão específica. Por exemplo, https://ContosoKeyVault.vault.azure.net/keys/ContosoFirstKey/cgacf4f763ar42ffb0a1gca546aygd87.

Adicione um segredo ao cofre, que é uma senha chamada SQLPassword e que tem o valor de "hVFkk965BuUv" aos Cofres de Chaves do Azure.

az keyvault secret set --vault-name "ContosoKeyVault" --name "SQLPassword" --value "hVFkk965BuUv "

Faça referência a essa senha usando seu URI. Use https://ContosoVault.vault.azure.net/secrets/SQLPassword para obter sempre a versão atual e https://<keyvault-name>.vault.azure.net/secret/<secret-name>/<secret-unique-id> para obter esta versão específica. Por exemplo, https://ContosoVault.vault.azure.net/secrets/SQLPassword/90018dbb96a84117a0d2847ef8e7189d.

Importe um certificado para o cofre usando um .pem ou .pfx.

az keyvault certificate import --vault-name "ContosoKeyVault" --file "c:\cert\cert.pfx" --name "ContosoCert" --password "hVFkk965BuUv"

Vamos exibir a chave, o segredo ou o certificado que você criou:

  • Para ver as chaves, escreva:
az keyvault key list --vault-name "ContosoKeyVault"
  • Para ver seus segredos, digite:
az keyvault secret list --vault-name "ContosoKeyVault"
  • Para exibir certificados, digite:
az keyvault certificate list --vault-name "ContosoKeyVault"

Registrando um aplicativo com o Microsoft Entra ID

Geralmente, este passo deve ser realizado por um programador, num computador à parte. Ele não é específico do Azure Key Vault, mas está incluído aqui, para conhecimento. Para concluir o registro do aplicativo, sua conta, o cofre e o aplicativo precisam estar no mesmo diretório do Azure.

Os aplicativos que usam um cofre de chaves devem se autenticar usando um token do Microsoft Entra ID. O proprietário do aplicativo deve registrá-lo no Microsoft Entra primeiro. No final do registo, o proprietário da aplicação obtém os seguintes valores:

  • Uma ID de Aplicativo (também conhecida como ID do Cliente Microsoft Entra ou appID)
  • Chave de autenticação (também conhecida como segredo partilhado).

O aplicativo deve apresentar esses dois valores para o Microsoft Entra ID, para obter um token. Como um aplicativo é configurado para obter um token dependerá do aplicativo. Na aplicação de exemplo do Key Vault, o proprietário da aplicação define estes valores no ficheiro app.config.

Para obter etapas detalhadas sobre como registrar um aplicativo com o Microsoft Entra ID, você deve revisar os artigos intitulados Integrando aplicativos com o Microsoft Entra ID, Usar portal para criar um aplicativo e entidade de serviço do Microsoft Entra que possa acessar recursos e Criar uma entidade de serviço do Azure com a CLI do Azure.

Para registrar um aplicativo no Microsoft Entra ID:

az ad sp create-for-rbac -n "MyApp" --password "hVFkk965BuUv" --role Contributor --scopes /subscriptions/<subscription id>
# If you don't specify a password, one will be created for you.

Autorizando um aplicativo a usar uma chave ou segredo

Para autorizar o aplicativo a acessar a chave ou o segredo no cofre, use o az keyvault set-policy comando.

Por exemplo, se o nome do cofre for ContosoKeyVault e você quiser autorizar o aplicativo a descriptografar e assinar com chaves no cofre, use o seguinte comando com a ID do aplicativo:

az keyvault set-policy --name "ContosoKeyVault" --spn {application-id} --key-permissions decrypt sign

Para autorizar o mesmo aplicativo a ler segredos em seu cofre, digite o seguinte comando:

az keyvault set-policy --name "ContosoKeyVault" --spn {application-id} --secret-permissions get

Definindo políticas avançadas de acesso do cofre de chaves

Use az keyvault update para habilitar políticas avançadas para o cofre de chaves.

Habilitar o Cofre da Chave para implantação: permite que máquinas virtuais recuperem certificados armazenados como segredos do cofre.

az keyvault update --name "ContosoKeyVault" --resource-group "ContosoResourceGroup" --enabled-for-deployment "true"

Habilitar o Cofre da Chave para criptografia de disco: necessário ao usar o cofre para criptografia de disco do Azure.

az keyvault update --name "ContosoKeyVault" --resource-group "ContosoResourceGroup" --enabled-for-disk-encryption "true"

Habilitar o Cofre da Chave para implantação de modelo: Permite que o Gerenciador de Recursos recupere segredos do cofre.

az keyvault update --name "ContosoKeyVault" --resource-group "ContosoResourceGroup" --enabled-for-template-deployment "true"

Trabalhando com módulos de segurança de hardware (HSMs)

Para maior garantia, você pode importar ou gerar chaves de módulos de segurança de hardware (HSMs) que nunca saem do limite do HSM. Os HSMs são validados pelo FIPS 140. Se este requisito não se aplica a si, ignore esta secção e aceda a Eliminar o cofre de chaves e as chaves e segredos associados.

Para criar estas chaves protegidas pelo HSM, a sua subscrição ao cofre deverá suportar chaves protegidas pelo HSM.

Ao criar o keyvault, adicione o parâmetro 'sku':

az keyvault create --name "ContosoKeyVaultHSM" --resource-group "ContosoResourceGroup" --location "East Asia" --sku "Premium"

Neste cofre, pode adicionar chaves protegidas por software (conforme mostrado anteriormente) e chaves protegidas por HSM. Para criar uma chave protegida por HSM, defina o parâmetro Destination como 'HSM':

az keyvault key create --vault-name "ContosoKeyVaultHSM" --name "ContosoFirstHSMKey" --protection "hsm"

Você pode usar o seguinte comando para importar uma chave de um arquivo .pem no seu computador. Este comando importa a chave os HSMs no serviço Cofre de Chaves:

az keyvault key import --vault-name "ContosoKeyVaultHSM" --name "ContosoFirstHSMKey" --pem-file "/.softkey.pem" --protection "hsm" --pem-password "PaSSWORD"

O próximo comando importa um pacote "bring your own key" (BYOK). Isto permite-lhe gerar a chave no seu HSM local e transferi-la para HSMs no serviço Cofre de Chaves, sem que a chave saia do limite HSM:

az keyvault key import --vault-name "ContosoKeyVaultHSM" --name "ContosoFirstHSMKey" --byok-file "./ITByok.byok" --protection "hsm"

Para obter instruções mais detalhadas sobre como gerar este pacote BYOK, consulte Como usar chaves protegidas por HSM com o Azure Key Vault.

Eliminar o cofre de chaves e as chaves e segredos associados

Se você não precisar mais do cofre de chaves e suas chaves ou segredos, poderá excluí-lo usando o az keyvault delete comando:

az keyvault delete --name "ContosoKeyVault"

Em alternativa, pode eliminar um grupo de recursos completo do Azure, que inclui o Cofre de Chaves e quaisquer outros recursos que incluiu nesse grupo:

az group delete --name "ContosoResourceGroup"

Comandos diversos da interface de linha de comando entre plataformas do Azure

Outros comandos que você pode achar úteis para gerenciar o Cofre da Chave do Azure.

Este comando lista uma exibição tabular de todas as chaves e propriedades selecionadas:

az keyvault key list --vault-name "ContosoKeyVault"

Este comando exibe uma lista completa de propriedades para a chave especificada:

az keyvault key show --vault-name "ContosoKeyVault" --name "ContosoFirstKey"

Este comando lista uma exibição tabular de todos os nomes secretos e propriedades selecionadas:

az keyvault secret list --vault-name "ContosoKeyVault"

Eis um exemplo de como remover uma chave específica:

az keyvault key delete --vault-name "ContosoKeyVault" --name "ContosoFirstKey"

Eis um exemplo de como remover um segredo específico:

az keyvault secret delete --vault-name "ContosoKeyVault" --name "SQLPassword"

Próximos passos