Azure Key Vault-Zertifikatclientbibliothek für .NET– Version 4.5.1

  • Artikel

Azure Key Vault ist ein Clouddienst, der eine sichere Speicherung und automatisierte Verwaltung von Zertifikaten ermöglicht, die in einer Cloudanwendung verwendet werden. Mehrere Zertifikate und mehrere Versionen desselben Zertifikats können im Azure-Key Vault beibehalten werden. Jedem Zertifikat im Tresor ist eine Richtlinie zugeordnet, die die Ausstellung und Lebensdauer des Zertifikats sowie Aktionen steuert, die als Zertifikate kurz vor Ablauf ausgeführt werden sollen.

Die Clientbibliothek für Azure Key Vault Zertifikate ermöglicht die programmgesteuerte Verwaltung von Zertifikaten und bietet Methoden zum Erstellen, Aktualisieren, Auflisten und Löschen von Zertifikaten, Richtlinien, Ausstellern und Kontakten. Die Bibliothek unterstützt auch die Verwaltung ausstehender Zertifikatvorgänge und die Verwaltung gelöschter Zertifikate.

Quellcode | Paket (NuGet) | API-Referenzdokumentation | Produktdokumentation | Proben | Migrationshandbuch

Erste Schritte

Installieren des Pakets

Installieren Sie die Clientbibliothek für Azure Key Vault-Zertifikate für .NET mit NuGet:

dotnet add package Azure.Security.KeyVault.Certificates

Voraussetzungen

  • Ein Azure-Abonnement.
  • Eine vorhandene Azure Key Vault. Wenn Sie eine Azure Key Vault erstellen müssen, können Sie das Azure-Portal oder die Azure CLI verwenden.
  • Autorisierung für eine vorhandene Azure-Key Vault entweder mithilfe der RBAC (empfohlen) oder der Zugriffssteuerung.

Wenn Sie die Azure CLI verwenden, ersetzen <your-resource-group-name> Sie und <your-key-vault-name> durch Ihre eigenen, eindeutigen Namen:

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

Authentifizieren des Clients

Um mit dem Azure Key Vault-Dienst zu interagieren, müssen Sie eine instance der CertificateClient-Klasse erstellen. Sie benötigen eine Tresor-URL, die im Portal möglicherweise als "DNS-Name" angezeigt wird, und Anmeldeinformationen, um ein Clientobjekt zu instanziieren.

In den unten gezeigten Beispielen wird ein DefaultAzureCredentialverwendet, das für die meisten Szenarien geeignet ist, einschließlich lokaler Entwicklungs- und Produktionsumgebungen. Darüber hinaus wird empfohlen, eine verwaltete Identität für die Authentifizierung in Produktionsumgebungen zu verwenden. Weitere Informationen zu verschiedenen Authentifizierungsmethoden und den entsprechenden Anmeldeinformationstypen finden Sie in der Dokumentation zu Azure Identity .

Um den DefaultAzureCredential unten gezeigten Anbieter oder andere Anmeldeinformationsanbieter zu verwenden, die mit dem Azure SDK bereitgestellt werden, müssen Sie zuerst das Azure.Identity-Paket installieren:

dotnet add package Azure.Identity

Erstellen von CertificateClient

Instanziieren Sie eine DefaultAzureCredential , um sie an den Client zu übergeben. Die gleiche instance einer Tokenanmeldeinformation kann mit mehreren Clients verwendet werden, wenn sie sich mit derselben Identität authentifizieren.

// 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());

Wichtige Begriffe

KeyVaultCertificate

Ein KeyVaultCertificate ist die grundlegende Ressource in Azure Key Vault. Sie verwenden Zertifikate, um verschlüsselte oder signierte Daten zu verschlüsseln und zu überprüfen.

CertificateClient

Mit einem CertificateClient können Sie Zertifikate aus dem Tresor abrufen, neue Zertifikate und neue Versionen vorhandener Zertifikate erstellen, Zertifikatmetadaten aktualisieren und Zertifikate löschen. Sie können auch Zertifikataussteller, Kontakte und Verwaltungsrichtlinien von Zertifikaten verwalten. Dies wird in den folgenden Beispielen veranschaulicht.

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und voneinander unabhängig sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch über Threads hinweg.

Zusätzliche Konzepte

Clientoptionen | Zugreifen auf die Antwort | Vorgänge | mit langer AusführungsdauerBehandeln von Fehlern | Diagnose | Spott | Clientlebensdauer

Beispiele

Das Paket Azure.Security.KeyVault.Certificates unterstützt synchrone und asynchrone APIs.

Der folgende Abschnitt enthält mehrere Codeausschnitte, die das clientoben erstellte verwenden, wobei einige der häufigsten Azure Key Vault-Zertifikatdienstaufgaben behandelt werden:

Synchronisierungsbeispiele

Asynchrone Beispiele

Erstellen eines Zertifikats

StartCreateCertificateerstellt ein Zertifikat, das im Azure-Key Vault gespeichert werden soll. Wenn bereits ein Zertifikat mit demselben Namen vorhanden ist, wird eine neue Version des Zertifikats erstellt. Beim Erstellen des Zertifikats kann der Benutzer die Richtlinie angeben, die die Zertifikatlebensdauer steuert. Wenn keine Richtlinie angegeben ist, wird die Standardrichtlinie verwendet. Der StartCreateCertificate Vorgang gibt einen CertificateOperationzurück. Im folgenden Beispiel wird ein selbstsigniertes Zertifikat mit der Standardrichtlinie erstellt.

// 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;

HINWEIS: Abhängig vom Zertifikataussteller und den Validierungsmethoden kann die Erstellung und Signatur von Zertifikaten unbestimmte Zeit in Anspruch nehmen. Benutzer sollten nur auf Zertifikatvorgänge warten, wenn der Vorgang vernünftigerweise im Bereich der Anwendung abgeschlossen werden kann, z. B. mit selbstsignierten Zertifikaten oder Ausstellern mit bekannten Antwortzeiten.

Abrufen eines Zertifikats

GetCertificateruft die neueste Version eines Zertifikats ab, das im Azure-Key Vault gespeichert ist, zusammen mit CertificatePolicyseiner .

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

GetCertificateVersion ruft eine bestimmte Version eines Zertifikats im Tresor ab.

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

Aktualisieren eines vorhandenen Zertifikats

UpdateCertificateaktualisiert ein im Azure-Key Vault gespeichertes Zertifikat.

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

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

Auflisten von Zertifikaten

GetCertificates Listet die Zertifikate im Tresor auf und gibt ausgewählte Eigenschaften des Zertifikats zurück. Vertrauliche Felder des Zertifikats werden nicht zurückgegeben. Für diesen Vorgang ist die Berechtigung zertifikate/listen erforderlich.

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

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

Löschen eines Zertifikats

DeleteCertificatelöscht alle Versionen eines Zertifikats, das im Azure-Key Vault gespeichert ist. Wenn vorläufiges Löschen für die Azure-Key Vault nicht aktiviert ist, wird das Zertifikat durch diesen Vorgang endgültig gelöscht. Wenn vorläufiges Löschen aktiviert ist, wird das Zertifikat zum Löschen markiert und kann optional bis zum geplanten Löschdatum gelöscht oder wiederhergestellt werden.

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);

Asynchrones Erstellen eines Zertifikats

Die asynchronen APIs sind mit ihren synchronen Entsprechungen identisch, geben jedoch mit dem typischen Suffix "Async" für asynchrone Methoden zurück und geben ein Taskzurück.

In diesem Beispiel wird ein Zertifikat im Azure-Key Vault mit den angegebenen optionalen Argumenten erstellt.

// 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();

Asynchrones Auflisten von Zertifikaten

Das Auflisten des Zertifikats basiert nicht auf dem Warten auf die GetPropertiesOfCertificatesAsync -Methode, sondern gibt eine zurück AsyncPageable<CertificateProperties> , die Sie mit der await foreach -Anweisung verwenden können:

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

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

Asynchrones Löschen eines Zertifikats

Wenn Sie ein Zertifikat asynchron löschen, bevor Sie es löschen, können Sie die WaitForCompletionAsync -Methode für den Vorgang abwarten. Standardmäßig wird diese Schleife auf unbestimmte Zeit ausgeführt, aber Sie können sie abbrechen, indem Sie einen CancellationTokenübergeben.

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);

Problembehandlung

Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie in unserem Leitfaden zur Problembehandlung .

Allgemein

Wenn Sie mit der Clientbibliothek für Azure Key Vault-Zertifikate mithilfe des .NET SDK interagieren, entsprechen vom Dienst zurückgegebene Fehler denselben HTTP-status Codes, die für REST-API-Anforderungen zurückgegeben werden.

Wenn Sie beispielsweise versuchen, einen Schlüssel abzurufen, der in Ihrer Azure-Key Vault nicht vorhanden ist, wird ein 404 Fehler zurückgegeben, der angibtNot Found.

try
{
    KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("SomeCertificate");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Sie werden feststellen, dass zusätzliche Informationen protokolliert werden, z. B. die Clientanforderungs-ID des Vorgangs.

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

Nächste Schritte

In diesem GitHub-Repository stehen Ihnen mehrere Beispiele für die Clientbibliothek von Azure Key Vault-Zertifikaten zur Verfügung. Diese Beispiele enthalten Beispielcode für zusätzliche Szenarien, die häufig bei der Arbeit mit Azure Key Vault auftreten:

  • Sample1_HelloWorld.md– für die Arbeit mit Azure Key Vault-Zertifikaten, einschließlich:

    • Erstellen eines Zertifikats
    • Abrufen eines vorhandenen Zertifikats
    • Aktualisieren eines vorhandenen Zertifikats
    • Löschen eines Zertifikats

  • Sample2_GetCertificates.md: Beispielcode für die Arbeit mit Azure Key Vault-Zertifikaten, einschließlich:

    • Erstellen von Zertifikaten
    • Auflisten aller Zertifikate im Key Vault
    • Auflisten von Versionen eines angegebenen Zertifikats
    • Löschen von Zertifikaten aus dem Key Vault
    • Auflisten gelöschter Zertifikate im Key Vault

Zusätzliche Dokumentation

Mitwirken

Weitere Informationen zum Erstellen, Testen und Mitwirken zu diesen Bibliotheken finden Sie im CONTRIBUTING.md .

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe