Gerenciar o Key Vault no Azure Stack Hub usando o PowerShell
Este artigo descreve como criar e gerenciar um cofre de chaves no Azure Stack Hub usando o PowerShell. Você aprenderá a usar cmdlets do PowerShell do Key Vault para:
- Crie um cofre de chaves.
- Armazene e gerencie chaves criptográficas e segredos.
- Autorize usuários ou aplicativos a invocar operações no cofre.
Observação
Os cmdlets do PowerShell do Key Vault descritos neste artigo são fornecidos no SDK do Azure PowerShell.
Pré-requisitos
- Você deve assinar uma oferta que inclua o serviço Azure Key Vault.
- Instalar o PowerShell para o Azure Stack Hub.
- Configure o ambiente do PowerShell do Azure Stack Hub.
Habilitar sua assinatura de locatário para operações do 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 é Registrado para todos os tipos de recursos de um cofre de chaves.
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:
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 do Key Vault seguindo as instruções anteriores.
Criar um cofre de chave
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
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
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 Vault, que está https://vault01.vault.local.azurestack.external neste exemplo.
Implantação dos 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 este cofre." Para resolver 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 está protegida por software. Quando a chave é criada com êxito, o comando gera os detalhes da chave criada.
Agora você pode fazer referência à 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/key01para sempre obter a versão atual. - Use
https://vault010.vault.local.azurestack.external:443/keys/key01/d0b36ee2e3d14e9f967b8b6b1d38938apara 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 é criado se ainda não existir. Uma nova versão do segredo será criada se já existir:
$secretvalue = ConvertTo-SecureString "User@123" -AsPlainText -Force
Set-AzureKeyVaultSecret -VaultName "Vault01" -Name "Secret01" -SecretValue $secretvalue
Obter um segredo
Use o cmdlet Get-AzureKeyVaultSecret para ler um segredo em um cofre de chaves. Esse comando pode retornar todas as versões 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 00001111-aaaa-2222-bbbb-3333cccc4444. 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 00001111-aaaa-2222-bbbb-3333cccc4444 -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