Gerenciar o Cofre da Chave 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. Vai aprender a utilizar os cmdlets do Key Vault PowerShell para:
- Criar um cofre de chaves.
- Armazene e gerencie chaves criptográficas e segredos.
- Autorize usuários ou aplicativos a invocar operações no cofre.
Nota
Os cmdlets do Azure Key Vault PowerShell descritos neste artigo são fornecidos no SDK do Azure PowerShell.
Pré-requisitos
- Tem de subscrever uma oferta que inclua o serviço Azure Key Vault.
- Instale o PowerShell para Azure Stack Hub.
- Configurar o ambiente do PowerShell do Azure Stack Hub.
Ative a subscrição do seu inquilino para operações do Cofre de Chaves
Antes de emitir quaisquer operações num cofre de chaves, deve assegurar-se de que a sua subscrição de inquilino está ativada para operações do 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 a sua subscrição estiver ativada para operações do cofre, a saída mostrará que RegistrationState está registado para todos os tipos de recursos de um cofre de chaves.
Caso as operações de Key Vault não estejam ativadas, emita o seguinte comando para registar o serviço Key Vault na tua subscrição:
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 que ativou o provedor de recursos do Cofre da Chave 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
Agora, use o cmdlet a seguir para criar um cofre de chaves no grupo de recursos criado anteriormente. Este 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 deste comando mostra as propriedades do cofre de chaves que você criou. Quando uma aplicação acede a este cofre, 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
Gerir 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 emite 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 obter sempre a versão atual. - Use
https://vault010.vault.local.azurestack.external:443/keys/key01/d0b36ee2e3d14e9f967b8b6b1d38938apara obter esta versão específica.
Obter uma chave
Utilize o cmdlet Get-AzureKeyVaultKey para ler uma chave e os 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 caso ainda não exista. Uma nova versão do segredo é criada se já existir:
$secretvalue = ConvertTo-SecureString "User@123" -AsPlainText -Force
Set-AzureKeyVaultSecret -VaultName "Vault01" -Name "Secret01" -SecretValue $secretvalue
Obtenha um segredo
Use o cmdlet Get-AzureKeyVaultSecret para ler um segredo em um cofre de chaves. Este 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 00001111-aaaa-2222-bbbb-3333cccc4444. Para autorizar o aplicativo, execute o seguinte comando. 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 quiser autorizar essa mesma aplicação a ler informações confidenciais no seu cofre, execute o seguinte cmdlet.
Set-AzKeyVaultAccessPolicy -VaultName 'ContosoKeyVault' -ServicePrincipalName 8f8c4bbd-485b-45fd-98f7-ec6300 -PermissionsToKeys Get -BypassObjectIdValidation