Gerenciar Key Vault no Hub de Azure Stack usando o PowerShellManage Key Vault in Azure Stack Hub using PowerShell

Este artigo descreve como criar e gerenciar um cofre de chaves no Hub de Azure Stack usando o PowerShell.This article describes how to create and manage a key vault in Azure Stack Hub using PowerShell. Você aprenderá a usar Key Vault cmdlets do PowerShell para:You'll learn how to use Key Vault PowerShell cmdlets to:

  • Crie um cofre da chave.Create a key vault.
  • Armazene e gerencie segredos e chaves de criptografia.Store and manage cryptographic keys and secrets.
  • Autorizar usuários ou aplicativos a invocar operações no cofre.Authorize users or apps to invoke operations in the vault.

Observação

Os cmdlets Key Vault PowerShell descritos neste artigo são fornecidos no SDK do Azure PowerShell.The Key Vault PowerShell cmdlets described in this article are provided in the Azure PowerShell SDK.

Pré-requisitosPrerequisites

Habilitar sua assinatura de locatário para operações de Key VaultEnable your tenant subscription for Key Vault operations

Antes de poder 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.Before you can issue any operations against a key vault, you must ensure that your tenant subscription is enabled for vault operations. Para verificar se as operações do Key Vault estão habilitadas, execute o seguinte comando:To verify that key vault operations are enabled, run the following command:

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

Se a sua assinatura estiver habilitada para operações de cofre, a saída mostrará o registrostate é registrado para todos os tipos de recurso de um cofre de chaves.If your subscription is enabled for vault operations, the output shows RegistrationState is Registered for all resource types of a key vault.

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 de Key Vault em sua assinatura:If vault operations are not enabled, issue the following command to register the Key Vault service in your subscription:

Register-AzResourceProvider -ProviderNamespace Microsoft.KeyVault

Se o registro for bem-sucedido, a seguinte saída será retornada:If the registration is successful, the following output is returned:

Registro do Key Vault 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 que habilitou o provedor de recursos Key Vault seguindo as instruções anteriores.When you invoke the key vault commands, you might receive an error, such as "The subscription is not registered to use namespace 'Microsoft.KeyVault'." If you get an error, confirm you've enabled the Key Vault resource provider by following the previous instructions.

Criar um cofre de chavesCreate a key vault

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.Before you create a key vault, create a resource group so that all of the resources related to the key vault exist in a resource group. Use o seguinte comando para criar um novo grupo de recursos:Use the following command to create a new resource group:

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.Now, use the following cmdlet to create a key vault in the resource group that you created earlier. Este comando lê três parâmetros obrigatórios: nome do grupo de recursos, nome do cofre de chaves e localização geográfica.This command reads three mandatory parameters: resource group name, key vault name, and geographic location.

Execute o seguinte comando para criar um cofre de chaves:Run the following command to create a key vault:

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.The output of this command shows the properties of the key vault that you created. Quando um aplicativo acessa esse cofre, ele deve usar a propriedade URI do cofre , que está https://vault01.vault.local.azurestack.external neste exemplo.When an app accesses this vault, it must use the Vault URI property, which is https://vault01.vault.local.azurestack.external in this example.

Implantação de Serviços de Federação do Active Directory (AD FS) (AD FS)Active Directory Federation Services (AD FS) deployment

Em uma implantação AD FS, você pode receber este aviso: "a política de acesso não está definida.In an AD FS deployment, you might get this warning: "Access policy is not set. Nenhum usuário ou aplicativo tem permissão de acesso para usar este cofre. "No user or application has access permission to use this vault." Para resolver esse problema, defina uma política de acesso para o cofre usando o comando set-AzKeyVaultAccessPolicy :To resolve this issue, set an access policy for the vault by using the Set-AzKeyVaultAccessPolicy command:

# 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 segredosManage keys and secrets

Depois de criar um cofre, use estas etapas para criar e gerenciar chaves e segredos no cofre.After you create a vault, use these steps to create and manage keys and secrets in the vault.

Criar uma chaveCreate a key

Use o cmdlet Add-AzureKeyVaultKey para criar ou importar uma chave protegida por software em um cofre de chaves:Use the Add-AzureKeyVaultKey cmdlet to create or import a software-protected key in a key vault:

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

O -Destination parâmetro é usado para especificar que a chave é protegida por software.The -Destination parameter is used to specify that the key is software protected. Quando a chave é criada com êxito, o comando gera os detalhes da chave criada.When the key is successfully created, the command outputs the details of the created key.

Nova chave do Key Vault gerada no PowerShell

Agora você pode referenciar a chave criada usando seu URI.You can now reference the created key by using its URI. Se você criar ou importar uma chave com o mesmo nome de uma chave existente, a chave original será atualizada com os valores especificados na nova chave.If you create or import a key that has same name as an existing key, the original key is updated with the values specified in the new key. Você pode acessar a versão anterior usando o URI específico da versão da chave.You can access the previous version by using the version-specific URI of the key. Por exemplo: For example:

  • Use https://vault10.vault.local.azurestack.external:443/keys/key01 para sempre obter a versão atual.Use https://vault10.vault.local.azurestack.external:443/keys/key01 to always get the current version.
  • Use https://vault010.vault.local.azurestack.external:443/keys/key01/d0b36ee2e3d14e9f967b8b6b1d38938a para obter essa versão específica.Use https://vault010.vault.local.azurestack.external:443/keys/key01/d0b36ee2e3d14e9f967b8b6b1d38938a to get this specific version.

Obter uma chaveGet a key

Use o cmdlet Get-AzureKeyVaultKey para ler uma chave e seus detalhes:Use the Get-AzureKeyVaultKey cmdlet to read a key and its details:

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

Criar um segredoCreate a secret

Use o cmdlet set-AzureKeyVaultSecret para criar ou atualizar um segredo em um cofre.Use the Set-AzureKeyVaultSecret cmdlet to create or update a secret in a vault. Um segredo será criado se ainda não existir um.A secret is created if one does not already exist. Uma nova versão do segredo será criada se ela já existir:A new version of the secret is created if it already exists:

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

Criar um segredo no PowerShell

Obter um segredoGet a secret

Use o cmdlet Get-AzureKeyVaultSecret para ler um segredo em um cofre de chaves.Use the Get-AzureKeyVaultSecret cmdlet to read a secret in a key vault. Este comando pode retornar todas ou versões específicas de um segredo:This command can return all or specific versions of a secret:

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

Depois de criar as chaves e os segredos, você pode autorizar os aplicativos externos a usá-los.After you create the keys and secrets, you can authorize external apps to use them.

Autorizar um aplicativo a usar uma chave ou segredoAuthorize an app to use a key or secret

Use o cmdlet a seguir para autorizar um aplicativo a acessar uma chave ou segredo no cofre de chaves.Use the following cmdlet to authorize an app to access a key or secret in the key vault.

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.In the following example, the vault name is ContosoKeyVault, and the app you want to authorize has a client ID of 8f8c4bbd-485b-45fd-98f7-ec6300b7b4ed. Para autorizar o aplicativo, execute o comando a seguir.To authorize the app, run the following command. 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.You can also specify the PermissionsToKeys parameter to set permissions for a user, an app, or a security group.

Ao usar o cmdlet em um ambiente de Hub de Azure Stack AD FS configurado, o parâmetro BypassObjectIdValidation deve ser fornecidoWhen using the cmdlet against an AD FS configured Azure Stack Hub environment, the parameter BypassObjectIdValidation should be provided

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

Se você quiser autorizar o mesmo aplicativo para ler segredos em seu cofre, execute o seguinte cmdlet:If you want to authorize that same app to read secrets in your vault, run the following cmdlet:

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

Próximas etapasNext steps