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. Você aprenderá a usar cmdlets do PowerShell do Key Vault 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 PowerShell do Cofre da Chave 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.
- Configure o ambiente do PowerShell do Azure Stack Hub.
Habilite sua assinatura de locatário para operações do Cofre da Chave
Antes de poder emitir quaisquer operações em um cofre de chaves, você deve garantir que sua assinatura de locatário esteja habilitada 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 sua assinatura estiver habilitada para operações do cofre, a saída mostrará que RegistrationState está 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 Cofre da Chave 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 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 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 Ative 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
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 é 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 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