Libreria client dei segreti di Azure Key Vault per .NET - versione 4.5.0

  • Articolo

Azure Key Vault è un servizio cloud che fornisce un'archiviazione sicura di segreti, ad esempio password e stringhe di connessione del database.

La libreria client dei segreti di Azure Key Vault consente di archiviare e controllare in modo sicuro l'accesso a token, password, chiavi API e altri segreti. Questa libreria offre operazioni per creare, recuperare, aggiornare, eliminare, ripulire, eseguire il backup, ripristinare ed elencare i segreti e le relative versioni.

Codice | sorgente Pacchetto (NuGet) | Documentazione | di riferimento sulle APIDocumentazione | del prodotto Campioni | Guida alla migrazione

Introduzione

Installare il pacchetto

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

dotnet add package Azure.Security.KeyVault.Secrets

Prerequisiti

Se si usa l'interfaccia della riga di comando di Azure, sostituire <your-resource-group-name> e <your-key-vault-name> con nomi univoci personalizzati:

az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

Autenticare il client

Per interagire con il servizio Azure Key Vault, è necessario creare un'istanza della classe SecretClient. È 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 ambienti di sviluppo e produzione locali. È inoltre consigliabile usare un'identità gestita per l'autenticazione negli ambienti di produzione. Per altre informazioni sulle diverse modalità di autenticazione e sui relativi tipi di credenziali corrispondenti, vedere la 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

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

// Create a new secret client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
var client = new SecretClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

// Create a new secret using the secret client.
KeyVaultSecret secret = client.SetSecret("secret-name", "secret-value");

// Retrieve a secret using the secret client.
secret = client.GetSecret("secret-name");

Concetti chiave

KeyVaultSecret

Un KeyVaultSecret è la risorsa fondamentale all'interno di Azure Key Vault. Dal punto di vista di uno sviluppatore, le API di Azure Key Vault accettano e restituiscono valori segreti come stringhe.

SecretClient

Un SecretClient oggetto fornisce sia operazioni sincrone che asincrone nell'SDK che consentono la selezione di un client in base al caso d'uso di un'applicazione. Dopo aver inizializzato un SecretClientoggetto , è possibile interagire con i segreti in Azure Key Vault.

Thread safety

Microsoft garantisce che tutti i metodi di istanza client siano thread-safe e indipendenti l'uno dall'altro (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 del client

Esempio

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

La sezione seguente fornisce diversi frammenti di codice usando il client codice creato sopra, che illustra alcune delle attività più comuni correlate al servizio segreto di Azure Key Vault:

Esempi di sincronizzazione

Esempi asincroni

Creare un segreto

SetSecretcrea un KeyVaultSecret oggetto da archiviare nel Key Vault di Azure. Se esiste già un segreto con lo stesso nome, viene creata una nuova versione del segreto.

KeyVaultSecret secret = client.SetSecret("secret-name", "secret-value");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);
Console.WriteLine(secret.Properties.Version);
Console.WriteLine(secret.Properties.Enabled);

Recuperare un segreto

GetSecretrecupera un segreto archiviato in precedenza nel Key Vault di Azure.

KeyVaultSecret secret = client.GetSecret("secret-name");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

Aggiornare un segreto esistente

UpdateSecretPropertiesaggiorna un segreto archiviato in precedenza nel Key Vault di Azure. Vengono aggiornati solo gli attributi del segreto. Per aggiornare il valore, chiamare SecretClient.SetSecret su un segreto con lo stesso nome.

KeyVaultSecret secret = client.GetSecret("secret-name");

// Clients may specify the content type of a secret to assist in interpreting the secret data when its retrieved.
secret.Properties.ContentType = "text/plain";

// You can specify additional application-specific metadata in the form of tags.
secret.Properties.Tags["foo"] = "updated tag";

SecretProperties updatedSecretProperties = client.UpdateSecretProperties(secret.Properties);

Console.WriteLine(updatedSecretProperties.Name);
Console.WriteLine(updatedSecretProperties.Version);
Console.WriteLine(updatedSecretProperties.ContentType);

consente di eliminare un segreto

StartDeleteSecretavvia un'operazione a esecuzione prolungata per eliminare un segreto archiviato in precedenza nel Key Vault di Azure. È possibile recuperare immediatamente il segreto senza attendere il completamento dell'operazione. Quando l'eliminazione temporanea non è abilitata per l'Key Vault di Azure, questa operazione elimina definitivamente il segreto.

DeleteSecretOperation operation = client.StartDeleteSecret("secret-name");

DeletedSecret secret = operation.Value;
Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

Eliminare ed eliminare un segreto

È necessario attendere il completamento dell'operazione a esecuzione prolungata prima di tentare di ripulire o recuperare il segreto. A tale scopo, chiamare UpdateStatus in un ciclo come illustrato di seguito:

DeleteSecretOperation operation = client.StartDeleteSecret("secret-name");

// You only need to wait for completion if you want to purge or recover the secret.
// You should call `UpdateStatus` in another thread or after doing additional work like pumping messages.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

DeletedSecret secret = operation.Value;
client.PurgeDeletedSecret(secret.Name);

List secrets

Questo esempio elenca tutti i segreti nell'Key Vault di Azure specificato. Il valore non viene restituito quando si elencano tutti i segreti. Sarà necessario chiamare SecretClient.GetSecret per recuperare il valore.

Pageable<SecretProperties> allSecrets = client.GetPropertiesOfSecrets();

foreach (SecretProperties secretProperties in allSecrets)
{
    Console.WriteLine(secretProperties.Name);
}

Creare un segreto in modo asincrono

Le API asincrone sono identiche alle rispettive controparti sincrone, ma restituiscono con il suffisso "Async" tipico per i metodi asincroni e restituiscono un oggetto Task.

Questo esempio crea un segreto nel Key Vault di Azure con gli argomenti facoltativi specificati.

KeyVaultSecret secret = await client.SetSecretAsync("secret-name", "secret-value");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

Elencare i segreti in modo asincrono

L'elenco dei segreti non si basa sull'attesa del GetPropertiesOfSecretsAsync metodo, ma restituisce un oggetto AsyncPageable<SecretProperties> che è possibile usare con l'istruzione await foreach :

AsyncPageable<SecretProperties> allSecrets = client.GetPropertiesOfSecretsAsync();

await foreach (SecretProperties secretProperties in allSecrets)
{
    Console.WriteLine(secretProperties.Name);
}

Eliminare un segreto in modo asincrono

Quando si elimina un segreto in modo asincrono prima di eliminarlo, è possibile attendere il WaitForCompletionAsync metodo sull'operazione. Per impostazione predefinita, questo ciclo viene eseguito per un periodo illimitato, ma è possibile annullarlo passando un oggetto CancellationToken.

DeleteSecretOperation operation = await client.StartDeleteSecretAsync("secret-name");

// You only need to wait for completion if you want to purge or recover the secret.
await operation.WaitForCompletionAsync();

DeletedSecret secret = operation.Value;
await client.PurgeDeletedSecretAsync(secret.Name);

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 client privata 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 segreto che non esiste nel Key Vault di Azure, viene restituito un 404 errore, che indica Not Found.

try
{
    KeyVaultSecret secret = client.GetSecret("some_secret");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Si noterà che vengono registrate informazioni aggiuntive, ad esempio l'ID richiesta client dell'operazione.

Message:
    Azure.RequestFailedException : Service request failed.
    Status: 404 (Not Found)
Content:
    {"error":{"code":"SecretNotFound","message":"Secret not found: some_secret"}}

Headers:
    Cache-Control: no-cache
    Pragma: no-cache
    Server: Microsoft-IIS/10.0
    x-ms-keyvault-region: westus
    x-ms-request-id: 625f870e-10ea-41e5-8380-282e5cf768f2
    x-ms-keyvault-service-version: 1.1.0.866
    x-ms-keyvault-network-info: addr=131.107.174.199;act_addr_fam=InterNetwork;
    X-AspNet-Version: 4.0.30319
    X-Powered-By: ASP.NET
    Strict-Transport-Security: max-age=31536000;includeSubDomains
    X-Content-Type-Options: nosniff
    Date: Tue, 18 Jun 2019 16:02:11 GMT
    Content-Length: 75
    Content-Type: application/json; charset=utf-8
    Expires: -1

Passaggi successivi

In questo repository GitHub sono disponibili diversi esempi di libreria client dei segreti di Azure Key Vault. Questi esempi forniscono codice di esempio per scenari aggiuntivi comunemente rilevati durante l'uso di Azure Key Vault:

  • Sample1_HelloWorld.md: per l'uso di Azure Key Vault, tra cui:

    • Creare un segreto
    • Ottenere un segreto esistente
    • Aggiornare un segreto esistente
    • Elimina segreto

  • Sample2_BackupAndRestore.md: contiene i frammenti di codice che collaborano con i segreti di Azure Key Vault, tra cui:

    • Eseguire il backup e il ripristino di un segreto

  • Sample3_GetSecrets.md: codice di esempio per l'uso dei segreti di Azure Key Vault, tra cui:

    • Creare segreti
    • Elencare tutti i segreti nel Key Vault
    • Aggiornare i segreti nel Key Vault
    • Elencare le versioni di un segreto specificato
    • Eliminare i segreti dal Key Vault
    • Elencare i segreti eliminati nel Key Vault

Documentazione aggiuntiva

Contributo

Per informazioni dettagliate sulla compilazione, il test e il contributo a queste librerie, vedere la CONTRIBUTING.md .

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.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

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.

Impression