Libreria client del certificato di Azure Key Vault per .NET - versione 4.5.1

  • Articolo

Azure Key Vault è un servizio cloud che offre archiviazione sicura e gestione automatizzata dei certificati usati in un'applicazione cloud. È possibile conservare più certificati e più versioni dello stesso certificato nel Key Vault di Azure. A ogni certificato nell'insieme di credenziali è associato un criterio che controlla il rilascio e la durata del certificato, insieme alle azioni da eseguire come certificati prossimi alla scadenza.

La libreria client dei certificati di Azure Key Vault consente di gestire i certificati a livello di codice, offrendo metodi per creare, aggiornare, elencare ed eliminare certificati, criteri, autorità emittenti e contatti a livello di codice. La libreria supporta anche la gestione delle operazioni dei certificati in sospeso e la gestione dei certificati eliminati.

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

Introduzione

Installare il pacchetto

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

dotnet add package Azure.Security.KeyVault.Certificates

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 CertificateClient. È 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 CertificateClient

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 certificate 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 CertificateClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

Concetti chiave

KeyVaultCertificate

Un KeyVaultCertificate è la risorsa fondamentale all'interno di Azure Key Vault. Si useranno i certificati per crittografare e verificare i dati crittografati o firmati.

CertificateClient

Con è CertificateClient possibile ottenere certificati dall'insieme di credenziali, creare nuovi certificati e nuove versioni dei certificati esistenti, aggiornare i metadati dei certificati ed eliminare i certificati. È anche possibile gestire autorità di certificazione, contatti e criteri di gestione dei certificati. Questo è illustrato negli esempi seguenti.

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.Certificates supporta API sincrone e asincrone.

La sezione seguente fornisce diversi frammenti di codice che usano la clientprocedura creata in precedenza, che illustra alcune delle attività più comuni correlate al servizio certificati di Azure Key Vault:

Esempi di sincronizzazione

Esempi asincroni

Creare un certificato

StartCreateCertificatecrea un certificato da archiviare nel Key Vault di Azure. Se esiste già un certificato con lo stesso nome, viene creata una nuova versione del certificato. Quando si crea il certificato, l'utente può specificare il criterio che controlla la durata del certificato. Se non viene specificato alcun criterio, verranno usati i criteri predefiniti. L'operazione StartCreateCertificate restituisce un oggetto CertificateOperation. Nell'esempio seguente viene creato un certificato autofirmato con i criteri predefiniti.

// Create a certificate. This starts a long running operation to create and sign the certificate.
CertificateOperation operation = client.StartCreateCertificate("MyCertificate", CertificatePolicy.Default);

// You can await the completion of the create certificate operation.
// You should run UpdateStatus in another thread or do other work like pumping messages between calls.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

KeyVaultCertificateWithPolicy certificate = operation.Value;

NOTA: a seconda dell'autorità di certificazione e dei metodi di convalida, la creazione e la firma del certificato possono richiedere un periodo di tempo indeterminato. Gli utenti devono attendere solo le operazioni sui certificati quando l'operazione può essere ragionevolmente completata nell'ambito dell'applicazione, ad esempio con certificati autofirmato o autorità emittenti con tempi di risposta noti.

Recuperare un certificato

GetCertificaterecupera la versione più recente di un certificato archiviato in Azure Key Vault insieme al relativo CertificatePolicy.

KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("MyCertificate");

GetCertificateVersion recupera una versione specifica di un certificato nell'insieme di credenziali.

KeyVaultCertificate certificate = client.GetCertificateVersion(certificateWithPolicy.Name, certificateWithPolicy.Properties.Version);

Aggiornare un certificato esistente

UpdateCertificateaggiorna un certificato archiviato nel Key Vault di Azure.

CertificateProperties certificateProperties = new CertificateProperties(certificate.Id);
certificateProperties.Tags["key1"] = "value1";

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

List certificates

GetCertificates enumera i certificati nell'insieme di credenziali, restituendo proprietà selezionate del certificato. I campi sensibili del certificato non verranno restituiti. Questa operazione richiede l'autorizzazione certificati/elenco.

Pageable<CertificateProperties> allCertificates = client.GetPropertiesOfCertificates();

foreach (CertificateProperties certificateProperties in allCertificates)
{
    Console.WriteLine(certificateProperties.Name);
}

Eliminare un certificato

DeleteCertificateelimina tutte le versioni di un certificato archiviato nel Key Vault di Azure. Quando l'eliminazione temporanea non è abilitata per l'Key Vault di Azure, questa operazione elimina definitivamente il certificato. Se l'eliminazione temporanea è abilitata, il certificato viene contrassegnato per l'eliminazione e può essere facoltativamente eliminato o ripristinato fino alla data di eliminazione pianificata.

DeleteCertificateOperation operation = client.StartDeleteCertificate("MyCertificate");

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

    operation.UpdateStatus();
}

DeletedCertificate certificate = operation.Value;
client.PurgeDeletedCertificate(certificate.Name);

Creare un certificato 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 certificato nel Key Vault di Azure con gli argomenti facoltativi specificati.

// Create a certificate. This starts a long running operation to create and sign the certificate.
CertificateOperation operation = await client.StartCreateCertificateAsync("MyCertificate", CertificatePolicy.Default);

// You can await the completion of the create certificate operation.
KeyVaultCertificateWithPolicy certificate = await operation.WaitForCompletionAsync();

Elencare i certificati in modo asincrono

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

AsyncPageable<CertificateProperties> allCertificates = client.GetPropertiesOfCertificatesAsync();

await foreach (CertificateProperties certificateProperties in allCertificates)
{
    Console.WriteLine(certificateProperties.Name);
}

Eliminare un certificato in modo asincrono

Quando si elimina un certificato 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.

DeleteCertificateOperation operation = await client.StartDeleteCertificateAsync("MyCertificate");

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

DeletedCertificate certificate = operation.Value;
await client.PurgeDeletedCertificateAsync(certificate.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 dei certificati di Azure Key Vault tramite .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 una chiave che non esiste nell'Key Vault di Azure, viene restituito un 404 errore, che indica Not Found.

try
{
    KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("SomeCertificate");
}
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":"CertificateNotFound","message":"Certificate not found: MyCertificate"}}

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 certificati 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 dei certificati di Azure Key Vault, tra cui:

    • Creare un certificato
    • Ottenere un certificato esistente
    • Aggiornare un certificato esistente
    • Eliminare un certificato

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

    • Creare i certificati
    • Elencare tutti i certificati nel Key Vault
    • Elencare le versioni di un certificato specificato
    • Eliminare i certificati dalla Key Vault
    • Elencare i certificati eliminati nella Key Vault

Documentazione aggiuntiva

Contributo

Per informazioni dettagliate su compilazione, test e 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