Compartilhar via

Gerenciar Key Vault no Azure Stack Hub usando o PowerShell

  • Artigo

Este artigo descreve como criar e gerenciar um cofre de chaves no Azure Stack Hub usando o PowerShell. Você aprenderá a usar Key Vault cmdlets do PowerShell para:

  • Crie um cofre da chave.
  • Armazene e gerencie chaves criptográficas e segredos.
  • Autorize usuários ou aplicativos a invocar operações no cofre.

Observação

Os cmdlets do Key Vault PowerShell descritos neste artigo são fornecidos no SDK do Azure PowerShell.

Pré-requisitos

Habilitar sua assinatura de locatário para operações de Key Vault

Antes de emitir qualquer operação em um cofre de chaves, você deve garantir que sua assinatura de locatário esteja habilitada para operações de cofre. Para verificar se as operações do cofre de chaves estão habilitadas, execute o seguinte comando:

Get-AzResourceProvider -ProviderNamespace Microsoft.KeyVault | ft -Autosize

Se sua assinatura estiver habilitada para operações de cofre, a saída mostrará Que RegistrationState está Registrado para todos os tipos de recursos de um cofre de chaves.

Estado de registro do cofre de chaves no PowerShell

Se as operações do cofre não estiverem habilitadas, emita o seguinte comando para registrar o serviço Key Vault em sua assinatura:

Register-AzResourceProvider -ProviderNamespace Microsoft.KeyVault

Se o registro for bem-sucedido, a seguinte saída será retornada:

Registro do cofre de chaves no Powershell bem-sucedido

Ao invocar os comandos do cofre de chaves, você pode receber um erro, como "A assinatura não está registrada para usar o namespace 'Microsoft.KeyVault'." Se você receber um erro, confirme se habilitou o provedor de recursos Key Vault seguindo as instruções anteriores.

Criar um cofre de chaves

Antes de criar um cofre de chaves, crie um grupo de recursos para que todos os recursos relacionados ao cofre de chaves existam em um grupo de recursos. Use o seguinte comando para criar um novo grupo de recursos:

New-AzResourceGroup -Name "VaultRG" -Location local -verbose -Force

Novo grupo de recursos gerado no PowerShell

Agora, use o cmdlet a seguir para criar um cofre de chaves no grupo de recursos que você criou anteriormente. Esse comando lê três parâmetros obrigatórios: nome do grupo de recursos, nome do cofre de chaves e localização geográfica.

Execute o seguinte comando para criar um cofre de chaves:

New-AzKeyVault -VaultName "Vault01" -ResourceGroupName "VaultRG" -Location local -verbose

Novo cofre de chaves gerado no PowerShell

A saída desse comando mostra as propriedades do cofre de chaves que você criou. Quando um aplicativo acessa esse cofre, ele deve usar a propriedade URI do Cofre , que está https://vault01.vault.local.azurestack.external neste exemplo.

implantação do AD FS (Serviços de Federação do Active Directory (AD FS))

Em uma implantação do AD FS, você pode receber este aviso: "A política de acesso não está definida. Nenhum usuário ou aplicativo tem permissão de acesso para usar esse cofre." Para resolve esse problema, defina uma política de acesso para o cofre usando o comando Set-AzKeyVaultAccessPolicy:

# Obtain the security identifier(SID) of the active directory user
$adUser = Get-ADUser -Filter "Name -eq '{Active directory user name}'"
$objectSID = $adUser.SID.Value

# Set the key vault access policy
Set-AzKeyVaultAccessPolicy -VaultName "{key vault name}" -ResourceGroupName "{resource group name}" -ObjectId "{object SID}" -PermissionsToKeys {permissionsToKeys} -PermissionsToSecrets {permissionsToSecrets} -BypassObjectIdValidation

Gerenciar chaves e segredos

Depois de criar um cofre, use estas etapas para criar e gerenciar chaves e segredos no cofre.

Criar uma chave

Use o cmdlet Add-AzureKeyVaultKey para criar ou importar uma chave protegida por software em um cofre de chaves:

Add-AzureKeyVaultKey -VaultName "Vault01" -Name "Key01" -verbose -Destination Software

O -Destination parâmetro é usado para especificar que a chave é protegida por software. Quando a chave é criada com êxito, o comando gera os detalhes da chave criada.

Nova chave do cofre de chaves gerada no PowerShell

Agora você pode referenciar a chave criada usando seu URI. Se você criar ou importar uma chave que tenha o mesmo nome de uma chave existente, a chave original será atualizada com os valores especificados na nova chave. Você pode acessar a versão anterior usando o URI específico da versão da chave. Por exemplo:

  • Use https://vault10.vault.local.azurestack.external:443/keys/key01 para sempre obter a versão atual.
  • Use https://vault010.vault.local.azurestack.external:443/keys/key01/d0b36ee2e3d14e9f967b8b6b1d38938a para obter essa versão específica.

Obter uma chave

Use o cmdlet Get-AzureKeyVaultKey para ler uma chave e seus detalhes:

Get-AzureKeyVaultKey -VaultName "Vault01" -Name "Key01"

Criar um segredo

Use o cmdlet Set-AzureKeyVaultSecret para criar ou atualizar um segredo em um cofre. Um segredo será criado se ainda não existir um. Uma nova versão do segredo será criada se ele já existir:

$secretvalue = ConvertTo-SecureString "User@123" -AsPlainText -Force
Set-AzureKeyVaultSecret -VaultName "Vault01" -Name "Secret01" -SecretValue $secretvalue

Criar um segredo no PowerShell

Obter um segredo

Use o cmdlet Get-AzureKeyVaultSecret para ler um segredo em um cofre de chaves. Esse comando pode retornar todas ou versões específicas de um segredo:

Get-AzureKeyVaultSecret -VaultName "Vault01" -Name "Secret01"

Depois de criar as chaves e os segredos, você pode autorizar aplicativos externos a usá-los.

Autorizar um aplicativo a usar uma chave ou segredo

Use o cmdlet a seguir para autorizar um aplicativo a acessar uma chave ou segredo no cofre de chaves.

No exemplo a seguir, o nome do cofre é ContosoKeyVault e o aplicativo que você deseja autorizar tem uma ID de cliente de 8f8c4bbd-485b-45fd-98f7-ec6300b7b4ed. Para autorizar o aplicativo, execute o comando a seguir. Você também pode especificar o parâmetro PermissionsToKeys para definir permissões para um usuário, um aplicativo ou um grupo de segurança.

Ao usar o cmdlet em um ambiente do Azure Stack Hub configurado pelo AD FS, o parâmetro BypassObjectIdValidation deve ser fornecido

Set-AzKeyVaultAccessPolicy -VaultName 'ContosoKeyVault' -ServicePrincipalName 8f8c4bbd-485b-45fd-98f7-ec6300b7b4ed -PermissionsToKeys decrypt,sign -BypassObjectIdValidation

Se você quiser autorizar esse mesmo aplicativo a ler segredos em seu cofre, execute o seguinte cmdlet:

Set-AzKeyVaultAccessPolicy -VaultName 'ContosoKeyVault' -ServicePrincipalName 8f8c4bbd-485b-45fd-98f7-ec6300 -PermissionsToKeys Get -BypassObjectIdValidation

Próximas etapas