Gestire Key Vault nell'hub Azure Stack con PowerShellManage Key Vault in Azure Stack Hub using PowerShell

Questo articolo descrive come creare e gestire un insieme di credenziali delle chiavi nell'hub Azure Stack usando PowerShell.This article describes how to create and manage a key vault in Azure Stack Hub using PowerShell. Si apprenderà come usare Key Vault cmdlet di PowerShell per:You'll learn how to use Key Vault PowerShell cmdlets to:

  • Creare un insieme di credenziali delle chiavi.Create a key vault.
  • Archiviare e gestire le chiavi crittografiche e i segreti.Store and manage cryptographic keys and secrets.
  • Autorizzare gli utenti o le app a richiamare le operazioni nell'insieme di credenziali.Authorize users or apps to invoke operations in the vault.

Nota

I cmdlet di Key Vault PowerShell descritti in questo articolo sono forniti in Azure PowerShell SDK.The Key Vault PowerShell cmdlets described in this article are provided in the Azure PowerShell SDK.

PrerequisitiPrerequisites

Abilitare la sottoscrizione tenant per le operazioni di Key VaultEnable your tenant subscription for Key Vault operations

Prima di poter eseguire qualsiasi operazione su un insieme di credenziali delle chiavi, è necessario assicurarsi che la sottoscrizione tenant sia abilitata per le operazioni dell'insieme di credenziali.Before you can issue any operations against a key vault, you must ensure that your tenant subscription is enabled for vault operations. Per verificare che le operazioni di Key Vault siano abilitate, eseguire il comando seguente:To verify that key vault operations are enabled, run the following command:

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

Se la sottoscrizione è abilitata per le operazioni dell'insieme di credenziali, l'output mostra che RegistrationState è registrato per tutti i tipi di risorsa di un insieme di credenziali delle chiavi.If your subscription is enabled for vault operations, the output shows RegistrationState is Registered for all resource types of a key vault.

Stato di registrazione di Key Vault in PowerShell

Se le operazioni dell'insieme di credenziali non sono abilitate, eseguire il comando seguente per registrare il servizio Key Vault nella sottoscrizione: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 la registrazione ha esito positivo, viene restituito l'output seguente:If the registration is successful, the following output is returned:

Registrazione di Key Vault in PowerShell riuscita

Quando si richiamano i comandi dell'insieme di credenziali delle chiavi, è possibile che venga visualizzato un errore, ad esempio "la sottoscrizione non è registrata per l'uso dello spazio dei nomi ' Microsoft. Key Vault '". Se viene ricevuto un errore, verificare di aver abilitato il provider di risorse Key Vault seguendo le istruzioni precedenti.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.

Creare un insieme di credenziali delle chiaviCreate a key vault

Prima di creare un insieme di credenziali delle chiavi, creare un gruppo di risorse in modo che tutte le risorse correlate all'insieme di credenziali delle chiavi esistano in un gruppo di risorse.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. Usare il comando seguente per creare un nuovo gruppo di risorse:Use the following command to create a new resource group:

New-AzResourceGroup -Name "VaultRG" -Location local -verbose -Force

Nuovo gruppo di risorse generato in PowerShell

A questo punto, usare il cmdlet seguente per creare un insieme di credenziali delle chiavi nel gruppo di risorse creato in precedenza.Now, use the following cmdlet to create a key vault in the resource group that you created earlier. Questo comando legge tre parametri obbligatori: il nome del gruppo di risorse, il nome del Key Vault e la posizione geografica.This command reads three mandatory parameters: resource group name, key vault name, and geographic location.

Eseguire il comando seguente per creare un insieme di credenziali delle chiavi:Run the following command to create a key vault:

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

Nuovo Key Vault generato in PowerShell

L'output di questo comando Mostra le proprietà dell'insieme di credenziali delle chiavi creato.The output of this command shows the properties of the key vault that you created. Quando un'app accede a questo insieme di credenziali, deve usare la proprietà URI dell'insieme di credenziali, che https://vault01.vault.local.azurestack.external in questo esempio è.When an app accesses this vault, it must use the Vault URI property, which is https://vault01.vault.local.azurestack.external in this example.

Distribuzione di Active Directory Federation Services (AD FS)Active Directory Federation Services (AD FS) deployment

In una distribuzione di AD FS, è possibile che venga visualizzato questo avviso: "criteri di accesso non impostati.In an AD FS deployment, you might get this warning: "Access policy is not set. Nessun utente o applicazione ha l'autorizzazione di accesso per l'uso di questo insieme di credenziali. "No user or application has access permission to use this vault." Per risolvere questo problema, impostare un criterio di accesso per l'insieme di credenziali usando il 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

Gestire chiavi e segretiManage keys and secrets

Dopo aver creato un insieme di credenziali, seguire questa procedura per creare e gestire chiavi e segreti nell'insieme di credenziali.After you create a vault, use these steps to create and manage keys and secrets in the vault.

Creare una chiaveCreate a key

Usare il cmdlet Add-AzureKeyVaultKey per creare o importare una chiave protetta tramite software in un insieme di credenziali delle chiavi: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

Il -Destination parametro viene usato per specificare che la chiave è protetta da software.The -Destination parameter is used to specify that the key is software protected. Quando la chiave viene creata correttamente, il comando restituisce i dettagli della chiave creata.When the key is successfully created, the command outputs the details of the created key.

Nuova chiave di Key Vault generata in PowerShell

È ora possibile fare riferimento alla chiave creata usando il relativo URI.You can now reference the created key by using its URI. Se si crea o si importa una chiave con lo stesso nome di una chiave esistente, la chiave originale viene aggiornata con i valori specificati nella nuova chiave.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. È possibile accedere alla versione precedente usando l'URI specifico della versione della chiave.You can access the previous version by using the version-specific URI of the key. Ad esempio:For example:

  • Usare https://vault10.vault.local.azurestack.external:443/keys/key01 per ottenere sempre la versione corrente.Use https://vault10.vault.local.azurestack.external:443/keys/key01 to always get the current version.
  • Usare https://vault010.vault.local.azurestack.external:443/keys/key01/d0b36ee2e3d14e9f967b8b6b1d38938a per ottenere questa versione specifica.Use https://vault010.vault.local.azurestack.external:443/keys/key01/d0b36ee2e3d14e9f967b8b6b1d38938a to get this specific version.

Ottenere una chiaveGet a key

Usare il cmdlet Get-AzureKeyVaultKey per leggere una chiave e i relativi dettagli:Use the Get-AzureKeyVaultKey cmdlet to read a key and its details:

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

Creare un segretoCreate a secret

Usare il cmdlet set-AzureKeyVaultSecret per creare o aggiornare un segreto in un insieme di credenziali.Use the Set-AzureKeyVaultSecret cmdlet to create or update a secret in a vault. Un segreto viene creato se non ne esiste già uno.A secret is created if one does not already exist. Se già esistente, viene creata una nuova versione del segreto: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

Creare un segreto in PowerShell

Ottenere un segretoGet a secret

Usare il cmdlet Get-AzureKeyVaultSecret per leggere un segreto in un insieme di credenziali delle chiavi.Use the Get-AzureKeyVaultSecret cmdlet to read a secret in a key vault. Questo comando può restituire tutte o versioni specifiche di un segreto:This command can return all or specific versions of a secret:

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

Dopo aver creato le chiavi e i segreti, è possibile autorizzare le app esterne a usarle.After you create the keys and secrets, you can authorize external apps to use them.

Autorizzare un'app a usare una chiave o un segretoAuthorize an app to use a key or secret

Usare il cmdlet seguente per autorizzare un'app ad accedere a una chiave o un segreto nell'insieme di credenziali delle chiavi.Use the following cmdlet to authorize an app to access a key or secret in the key vault.

Nell'esempio seguente il nome dell'insieme di credenziali è ContosoKeyVault e l'app che si vuole autorizzare ha un ID client di 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. Per autorizzare l'app, eseguire il comando seguente.To authorize the app, run the following command. È anche possibile specificare il parametro PermissionsToKeys per impostare le autorizzazioni per un utente, un'app o un gruppo di sicurezza.You can also specify the PermissionsToKeys parameter to set permissions for a user, an app, or a security group.

Quando si usa il cmdlet in un ambiente di Azure Stack Hub AD FS configurato, è necessario fornire il parametro BypassObjectIdValidationWhen 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 si vuole autorizzare la stessa app a leggere i segreti nell'insieme di credenziali, eseguire il cmdlet seguente: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

Passaggi successiviNext steps