Gerir o cofre da chave no Azure Stack Hub usando o PowerShellManage Key Vault in Azure Stack Hub using PowerShell

Este artigo descreve como criar e gerir um cofre chave em Azure Stack Hub usando PowerShell.This article describes how to create and manage a key vault in Azure Stack Hub using PowerShell. Você vai aprender a usar cmdlets Key Vault PowerShell para:You'll learn how to use Key Vault PowerShell cmdlets to:

  • Criar um cofre de chaves.Create a key vault.
  • Armazenar e gerir chaves criptográficas e segredos.Store and manage cryptographic keys and secrets.
  • Autorizar utilizadores ou aplicativos a invocar operações no cofre.Authorize users or apps to invoke operations in the vault.

Nota

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

Pré-requisitosPrerequisites

Ativar a subscrição do seu inquilino para operações do Key VaultEnable your tenant subscription for Key Vault operations

Antes de poder emitir quaisquer operações contra um cofre chave, deve certificar-se de que a subscrição do seu inquilino está ativada para operações de abóbada.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 cofre de chaves estão ativadas, executar 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 subscrição estiver ativada para operações de cofre, a saída mostra que o RegistrationState está registado para todos os tipos de recursos de um cofre chave.If your subscription is enabled for vault operations, the output shows RegistrationState is Registered for all resource types of a key vault.

Estado de registo do cofre chave em Powershell

Se as operações do cofre não estiverem ativadas, emita o seguinte comando para registar o serviço Key Vault na sua subscrição: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 registo for bem sucedido, a seguinte saída é devolvida:If the registration is successful, the following output is returned:

Registo de cofre chave em Powershell bem sucedido

Quando invoca os comandos do cofre de chaves, poderá receber um erro, tal como "A subscrição não está registada para utilizar o espaço de nome 'Microsoft.KeyVault'". Se tiver um erro, confirme que ativou o fornecedor de recursos do Cofre de Chaves 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 chave, crie um grupo de recursos para que todos os recursos relacionados com o cofre-chave existam num 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. Utilize 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 em Powershell

Agora, use o cmdlet seguinte para criar um cofre chave no grupo de recursos que criou anteriormente.Now, use the following cmdlet to create a key vault in the resource group that you created earlier. Este comando diz três parâmetros obrigatórios: nome do grupo de recursos, nome do cofre chave e localização geográfica.This command reads three mandatory parameters: resource group name, key vault name, and geographic location.

Executar o seguinte comando para criar um cofre chave:Run the following command to create a key vault:

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

Novo cofre-chave gerado em Powershell

A saída deste comando mostra as propriedades do cofre chave que criou.The output of this command shows the properties of the key vault that you created. Quando uma aplicação acede a este cofre, deve usar a propriedade Vault URI, 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 da Federação de Diretórios Ativos (AD FS)Active Directory Federation Services (AD FS) deployment

Numa implementação de FS AD, 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 utilizador ou aplicação tem permissão de acesso para usar este cofre."No user or application has access permission to use this vault." Para resolver este problema, desafete uma política de acesso para o cofre utilizando 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

Gerir chaves e segredosManage keys and secrets

Depois de criar um cofre, use estes passos para criar e gerir 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

Utilize o cmdlet Add-AzureKeyVaultKey para criar ou importar uma chave protegida por software num cofre chave: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 é utilizado para especificar que a chave está protegida por software.The -Destination parameter is used to specify that the key is software protected. Quando a chave é criada com sucesso, o comando produz os detalhes da chave criada.When the key is successfully created, the command outputs the details of the created key.

Nova chave do cofre gerada em Powershell

Agora pode referenciar a tecla criada utilizando o seu URI.You can now reference the created key by using its URI. Se criar ou importar uma chave com o mesmo nome que uma chave existente, a chave original é 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. Pode aceder à versão anterior utilizando 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 obter sempre 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 esta 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

Utilize o cmdlet Get-AzureKeyVaultKey para ler uma chave e os 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

Utilize o cmdlet Set-AzureKeyVaultSecret para criar ou atualizar um segredo num cofre.Use the Set-AzureKeyVaultSecret cmdlet to create or update a secret in a vault. Um segredo é criado se não existirmos já.A secret is created if one does not already exist. Uma nova versão do segredo é criada se já existe: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 em Powershell

Obter um segredoGet a secret

Use o cmdlet Get-AzureKeyVaultSecret para ler um segredo num cofre de chaves.Use the Get-AzureKeyVaultSecret cmdlet to read a secret in a key vault. Este comando pode devolver 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 segredos, pode autorizar aplicações externas a usá-las.After you create the keys and secrets, you can authorize external apps to use them.

Autorizar uma aplicação a usar uma chave ou segredoAuthorize an app to use a key or secret

Utilize o cmdlet seguinte para autorizar uma aplicação a aceder a uma chave ou segredo no cofre da chave.Use the following cmdlet to authorize an app to access a key or secret in the key vault.

No exemplo seguinte, o nome do cofre é ContosoKeyVault, e a app que pretende autorizar tem um 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 a aplicação, executar o seguinte comando.To authorize the app, run the following command. Também pode especificar o parâmetro PermissõesToKeys para definir permissões para um utilizador, uma aplicação 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 utilizar o cmdlet contra um ambiente AD FS configurado Azure Stack Hub, 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 quiser autorizar a mesma aplicação a ler segredos no 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

Passos seguintesNext steps