Libreria client di Amministrazione di Azure KeyVault per .NET - versione 4.3.0

Azure Key Vault Managed HSM è un servizio cloud conforme a standard, completamente gestito e completamente gestito, a disponibilità elevata e a disponibilità elevata, che consente di proteggere le chiavi crittografiche per le applicazioni cloud con FIPS 140-2 Livello 3 convalidato.

I client della libreria di amministrazione di Azure Key Vault supportano attività amministrative, ad esempio backup completo/ripristino e controllo degli accessi in base al ruolo a livello di chiave.

Codice | sorgente Pacchetto (NuGet) | Documentazione | del prodotto Campioni

Introduzione

Installare il pacchetto

Installare la libreria client di amministrazione di Azure Key Vault per .NET con NuGet:

dotnet add package Azure.Security.KeyVault.Administration

Prerequisiti

• Una sottoscrizione di Azure.
• Un Key Vault di Azure esistente. Se è necessario creare un Key Vault di Azure, è possibile usare l'interfaccia della riga di comando di Azure.
• Autorizzazione a un Key Vault di Azure esistente usando il controllo degli accessi in base al ruolo (consigliato) o il controllo di accesso.

Per creare una risorsa HSM gestita, eseguire il comando dell'interfaccia della riga di comando seguente:

az keyvault create --hsm-name <your-key-vault-name> --resource-group <your-resource-group-name> --administrators <your-user-object-id> --location <your-azure-location>

Per ottenere l'esecuzione <your-user-object-id> del comando dell'interfaccia della riga di comando seguente:

az ad user show --id <your-user-principal> --query id

Autenticare il client

Per interagire con il servizio azure Key Vault, è necessario creare un'istanza delle classi client seguenti. È necessario un URL dell'insieme di credenziali, che può essere visualizzato come "Nome DNS" nel portale e le credenziali per creare un'istanza di un oggetto client.

Gli esempi illustrati di seguito usano un DefaultAzureCredentialoggetto , appropriato per la maggior parte degli scenari, tra cui lo sviluppo locale e gli ambienti di produzione. È inoltre consigliabile usare un'identità gestita per l'autenticazione negli ambienti di produzione. È possibile trovare altre informazioni su diversi modi di autenticazione e sui relativi tipi di credenziali corrispondenti nella documentazione di Identità di Azure .

Per usare il DefaultAzureCredential provider illustrato di seguito o altri provider di credenziali forniti con Azure SDK, è prima necessario installare il pacchetto Azure.Identity:

dotnet add package Azure.Identity

Attivare il modulo di protezione hardware gestito

Tutti i comandi del piano dati vengono disabilitati finché non viene attivato il modulo di protezione hardware. Non sarà possibile creare chiavi o assegnare ruoli. Solo gli amministratori designati assegnati durante il comando di creazione possono attivare il modulo di protezione hardware. Per attivare il modulo di protezione hardware, è necessario scaricare il dominio di sicurezza.

Per attivare il modulo di protezione hardware occorre:

• Minimo 3 coppie chiave RSA (massimo 10)
• Specificare il numero minimo di chiavi necessarie per decrittografare il dominio di sicurezza (quorum)

Per attivare il modulo di protezione hardware è necessario inviare almeno 3 (al massimo 10) chiavi pubbliche RSA al modulo stesso. Il modulo di protezione hardware crittografa il dominio di sicurezza con queste chiavi e lo restituisce. Dopo aver scaricato correttamente questo dominio di sicurezza, il modulo di protezione hardware è pronto per l'uso. Occorre anche specificare il quorum, ossia il numero minimo di chiavi private necessarie per decrittografare il dominio di sicurezza.

Nell'esempio seguente viene illustrato come usare openssl per generare 3 certificati autofirmato.

openssl req -newkey rsa:2048 -nodes -keyout cert_0.key -x509 -days 365 -out cert_0.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_1.key -x509 -days 365 -out cert_1.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_2.key -x509 -days 365 -out cert_2.cer

Usare il comando az keyvault security-domain download per scaricare il dominio di sicurezza e attivare il modulo di protezione hardware gestito. L'esempio seguente usa 3 coppie di chiavi RSA (per questo comando sono necessarie solo chiavi pubbliche) e imposta il quorum su 2.

az keyvault security-domain download --hsm-name <your-managed-hsm-name> --sd-wrapping-keys ./certs/cert_0.cer ./certs/cert_1.cer ./certs/cert_2.cer --sd-quorum 2 --security-domain-file ContosoMHSM-SD.json

Controllo dell'accesso al modulo di protezione hardware gestito

Gli amministratori designati assegnati durante la creazione vengono aggiunti automaticamente al ruolo predefinito "Amministratori HSM gestiti", che possono scaricare un dominio di sicurezza e gestire i ruoli per l'accesso al piano dati, tra le altre autorizzazioni limitate.

Per eseguire altre azioni sulle chiavi, è necessario assegnare entità ad altri ruoli, ad esempio "Managed HSM Crypto User", che può eseguire operazioni chiave non distruttive:

az keyvault role assignment create --hsm-name <your-managed-hsm-name> --role "Managed HSM Crypto User" --scope / --assignee-object-id <principal-or-user-object-ID> --assignee-principal-type <principal-type>

Leggere le procedure consigliate per proteggere correttamente il modulo di protezione hardware gestito.

Creare KeyVaultAccessControlClient

Creare un'istanza DefaultAzureCredential di per passare all'oggetto KeyVaultAccessControlClient. La stessa istanza di una credenziale token può essere usata con più client se eseguirà l'autenticazione con la stessa identità.

KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Creare KeyVaultBackupClient

Creare un'istanza DefaultAzureCredential di per passare all'oggetto KeyVaultBackupClient. La stessa istanza di una credenziale token può essere usata con più client se eseguirà l'autenticazione con la stessa identità.

KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Creare KeyVaultSettingClient

Creare un'istanza DefaultAzureCredential di per passare all'oggetto KeyVaultSettingsClient. La stessa istanza di una credenziale token può essere usata con più client se eseguirà l'autenticazione con la stessa identità.

KeyVaultSettingsClient client = new KeyVaultSettingsClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Concetti chiave

KeyVaultRoleDefinition

Un KeyVaultRoleDefinition è una raccolta di autorizzazioni. Una definizione di ruolo definisce le operazioni che possono essere eseguite, ad esempio lettura, scrittura ed eliminazione. Può anche definire le operazioni escluse dalle operazioni consentite.

KeyVaultRoleDefinitions può essere elencato e specificato come parte di un KeyVaultRoleAssignmentoggetto .

KeyVaultRoleAssignment

Un KeyVaultRoleAssignment è l'associazione di keyVaultRoleDefinition a un'entità servizio. Possono essere create, elencate, recuperate singolarmente ed eliminate.

KeyVaultAccessControlClient

Un KeyVaultAccessControlClient oggetto fornisce sia operazioni sincrone che asincrone che consentono la gestione di KeyVaultRoleDefinition e KeyVaultRoleAssignment oggetti.

KeyVaultBackupClient

Un KeyVaultBackupClient offre sia operazioni sincrone che asincrone per l'esecuzione di backup completi delle chiavi, ripristini completi delle chiavi e ripristini di chiavi selettive.

BackupOperation

Un BackupOperation rappresenta un'operazione a esecuzione prolungata per un backup completo della chiave.

RestoreOperation

Un RestoreOperation oggetto rappresenta un'operazione a esecuzione prolungata per un ripristino completo della chiave e della chiave selettiva.

Thread safety

Si garantisce che tutti i metodi di istanza client siano thread-safe e indipendenti tra loro (linee guida). Ciò garantisce che la raccomandazione di riutilizzare le istanze client sia sempre sicura, anche tra thread.

Concetti aggiuntivi

Opzioni | client Accesso alla risposta | Operazioni | a esecuzione prolungataGestione degli errori | Diagnostica | Beffardo | Durata client

Esempio

Il pacchetto Azure.Security.KeyVault.Administration supporta API sincrone e asincrone.

La sezione seguente fornisce diversi frammenti di codice usando il codice creato in precedenza per i client client di controllo di accesso o di backup, che copre alcune delle attività correlate al controllo di accesso di Azure Key Vault più comuni:

Esempi di sincronizzazione

• Controllo di accesso
  • Elenco di tutte le definizioni di ruolo
  • Elencare tutte le assegnazioni di ruolo
  • Creazione di un'assegnazione di ruolo
  • Recupero di un'assegnazione di ruolo
  • Eliminazione di assegnazioni di ruolo
• Backup e ripristino
  • Esecuzione di un backup completo della chiave
  • Esecuzione di un ripristino completo della chiave

Esempi asincroni

• Controllo di accesso
  • Elenco di tutte le definizioni di ruolo
  • Elencare tutte le assegnazioni di ruolo
  • Creazione di un'assegnazione di ruolo
  • Recupero di un'assegnazione di ruolo
  • Eliminazione di assegnazioni di ruolo
• Backup e ripristino
  • Esecuzione di un backup completo della chiave
  • Esecuzione di un ripristino completo della chiave

Risoluzione dei problemi

Per informazioni dettagliate su come diagnosticare vari scenari di errore, vedere la guida alla risoluzione dei problemi .

Generale

Quando si interagisce con la libreria di amministrazione di Azure Key Vault usando .NET SDK, gli errori restituiti dal servizio corrispondono agli stessi codici di stato HTTP restituiti per le richieste api REST.

Ad esempio, se si tenta di recuperare un'assegnazione di ruolo che non esiste nel Key Vault di Azure, viene restituito un 404 errore che indica "Non trovato".

try
{
    KeyVaultRoleAssignment roleAssignment = client.GetRoleAssignment(KeyVaultRoleScope.Global, "example-name");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Azure.RequestFailedException: Service request failed.
Status: 404 (Not Found)

Content:
{"error":{"code":"RoleAssignmentNotFound","message":"Requested role assignment not found (Activity ID: a67f09f4-b68e-11ea-bd6d-0242ac120006)"}}

Headers:
X-Content-Type-Options: REDACTED
x-ms-request-id: a67f09f4-b68e-11ea-bd6d-0242ac120006
Content-Length: 143
Content-Type: application/json

Configurazione della registrazione della console

Il modo più semplice per visualizzare i log consiste nell'abilitare la registrazione della console. Per creare un listener di log di Azure SDK che restituisce messaggi nella console, usare il AzureEventSourceListener.CreateConsoleLogger metodo .

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Per altre informazioni sugli altri meccanismi di registrazione, vedere qui.

Passaggi successivi

Introduzione agli esempi.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.