Gestire Key Vault nell'hub di Azure Stack con PowerShell

  • Articolo

Questo articolo descrive come creare e gestire un insieme di credenziali delle chiavi nell'hub di Azure Stack usando PowerShell. Si apprenderà come usare Key Vault cmdlet di PowerShell per:

  • Creare un insieme di credenziali delle chiavi.
  • Archiviare e gestire chiavi crittografiche e segreti.
  • Autorizzare utenti o app a richiamare le operazioni nell'insieme di credenziali.

Nota

I cmdlet di PowerShell Key Vault descritti in questo articolo sono disponibili in Azure PowerShell SDK.

Prerequisiti

Abilitare la sottoscrizione del tenant per le operazioni di Key Vault

Prima di poter eseguire qualsiasi operazione su un insieme di credenziali delle chiavi, è necessario assicurarsi che la sottoscrizione del tenant sia abilitata per le operazioni dell'insieme di credenziali. Per verificare che le operazioni dell'insieme di credenziali delle chiavi siano abilitate, eseguire il comando seguente:

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

Se la sottoscrizione è abilitata per le operazioni dell'insieme di credenziali, l'output indica che RegistrationState è Registrato per tutti i tipi di risorse di un insieme di credenziali delle chiavi.

Stato di registrazione dell'insieme di credenziali delle chiavi in PowerShell

Se le operazioni dell'insieme di credenziali non sono abilitate, eseguire il comando seguente per registrare il servizio Key Vault nella sottoscrizione:

Register-AzResourceProvider -ProviderNamespace Microsoft.KeyVault

Se la registrazione ha esito positivo, viene restituito l'output seguente:

Registrazione dell'insieme di credenziali delle chiavi in PowerShell completata

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.KeyVault". Se viene visualizzato un errore, verificare di aver abilitato il provider di risorse Key Vault seguendo le istruzioni precedenti.

Creare un insieme di credenziali delle chiavi

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. Usare il comando seguente per creare un nuovo gruppo di risorse:

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

Nuovo gruppo di risorse generato in PowerShell

Usare ora il cmdlet seguente per creare un insieme di credenziali delle chiavi nel gruppo di risorse creato in precedenza. Questo comando legge tre parametri obbligatori: nome del gruppo di risorse, nome dell'insieme di credenziali delle chiavi e posizione geografica.

Eseguire il comando seguente per creare un insieme di credenziali delle chiavi:

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

Nuovo insieme di credenziali delle chiavi generato in PowerShell

L'output di questo comando mostra le proprietà dell'insieme di credenziali delle chiavi creato. Quando un'app accede a questo insieme di credenziali, deve usare la proprietà URI dell'insieme di credenziali , disponibile https://vault01.vault.local.azurestack.external in questo esempio.

distribuzione di Active Directory Federation Services (AD FS)

In una distribuzione di AD FS è possibile che venga visualizzato questo avviso: "I criteri di accesso non sono impostati. Nessun utente o applicazione dispone dell'autorizzazione di accesso per l'uso di questo insieme di credenziali." Per risolvere questo problema, impostare un criterio di accesso per l'insieme di credenziali usando il 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

Gestire chiavi e segreti

Dopo aver creato un insieme di credenziali, seguire questa procedura per creare e gestire chiavi e segreti nell'insieme di credenziali.

Creare una chiave

Usare il cmdlet Add-AzureKeyVaultKey per creare o importare una chiave protetta da software in un insieme di credenziali delle chiavi:

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

Il -Destination parametro viene usato per specificare che la chiave è protetta dal software. Quando la chiave viene creata correttamente, il comando restituisce i dettagli della chiave creata.

Nuova chiave dell'insieme di credenziali delle chiavi generata in PowerShell

È ora possibile fare riferimento alla chiave creata usando il relativo URI. Se si crea o importa una chiave con lo stesso nome di una chiave esistente, la chiave originale viene aggiornata con i valori specificati nella nuova chiave. È possibile accedere alla versione precedente usando l'URI specifico della versione della chiave. Ad esempio:

  • Usare https://vault10.vault.local.azurestack.external:443/keys/key01 per ottenere sempre la versione corrente.
  • Usare https://vault010.vault.local.azurestack.external:443/keys/key01/d0b36ee2e3d14e9f967b8b6b1d38938a per ottenere questa versione specifica.

Ottenere una chiave

Usare il cmdlet Get-AzureKeyVaultKey per leggere una chiave e i relativi dettagli:

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

Creare un segreto

Usare il cmdlet Set-AzureKeyVaultSecret per creare o aggiornare un segreto in un insieme di credenziali. Se non esiste già un segreto, viene creato un segreto. Se esiste già, viene creata una nuova versione del segreto:

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

Creare un segreto in PowerShell

Ottenere un segreto

Usare il cmdlet Get-AzureKeyVaultSecret per leggere un segreto in un insieme di credenziali delle chiavi. Questo comando può restituire tutte o versioni specifiche di un segreto:

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

Dopo aver creato le chiavi e i segreti, è possibile autorizzare le app esterne a usarle.

Autorizzare un'app a usare una chiave o un segreto

Usare il cmdlet seguente per autorizzare un'app ad accedere a una chiave o a un segreto nell'insieme di credenziali delle chiavi.

Nell'esempio seguente il nome dell'insieme di credenziali è ContosoKeyVault e l'app da autorizzare ha un ID client pari a 8f8c4bbd-485b-45fd-98f7-ec6300b7b4ed. Per autorizzare l'app, eseguire il comando seguente. È anche possibile specificare il parametro PermissionsToKeys per impostare le autorizzazioni per un utente, un'app o un gruppo di sicurezza.

Quando si usa il cmdlet in un ambiente dell'hub di Azure Stack configurato da AD FS, è necessario specificare il parametro BypassObjectIdValidation

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:

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

Passaggi successivi