Azure Key Vault geheime Clientbibliothek für .NET– Version 4.5.0

  • Artikel

Azure Key Vault ist ein Clouddienst, der eine sichere Speicherung von Geheimnissen wie Kennwörtern und Datenbankverbindungszeichenfolgen ermöglicht.

Mit der Clientbibliothek für Azure Key Vault Geheimnisse können Sie den Zugriff auf Token, Kennwörter, API-Schlüssel und andere Geheimnisse sicher speichern und steuern. Diese Bibliothek bietet Vorgänge zum Erstellen, Abrufen, Aktualisieren, Löschen, Löschen, Sichern, Wiederherstellen und Auflisten der Geheimnisse und ihrer Versionen.

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

Erste Schritte

Installieren des Pakets

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

dotnet add package Azure.Security.KeyVault.Secrets

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 SecretClient-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

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

Wichtige Begriffe

KeyVaultSecret

Ein KeyVaultSecret ist die grundlegende Ressource in Azure Key Vault. Aus Entwicklersicht akzeptieren Azure Key Vault-APIs geheime Werte und geben sie als Zeichenfolgen zurück.

SecretClient

Ein SecretClient stellt sowohl synchrone als auch asynchrone Vorgänge im SDK bereit, die die Auswahl eines Clients basierend auf dem Anwendungsfall einer Anwendung ermöglichen. Nachdem Sie ein SecretClientinitialisiert haben, können Sie mit Geheimnissen in Azure Key Vault interagieren.

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 Azure.Security.KeyVault.Secrets-Paket unterstützt synchrone und asynchrone APIs.

Der folgende Abschnitt enthält mehrere Codeausschnitte, die das client oben erstellte verwenden, wobei einige der häufigsten Aufgaben im Zusammenhang mit Azure Key Vault Secret Service behandelt werden:

Synchronisierungsbeispiele

Asynchrone Beispiele

Erstellen eines Geheimnisses

SetSecreterstellt eine KeyVaultSecret , die im Azure-Key Vault gespeichert werden soll. Wenn bereits ein Geheimnis mit demselben Namen vorhanden ist, wird eine neue Version des Geheimnisses erstellt.

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

Abrufen eines Geheimnisses

GetSecretruft ein Geheimnis ab, das zuvor im Azure-Key Vault gespeichert wurde.

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

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

Aktualisieren eines vorhandenen Geheimnisses

UpdateSecretPropertiesaktualisiert ein Geheimnis, das zuvor im Azure-Key Vault gespeichert wurde. Nur die Attribute des Geheimnisses werden aktualisiert. Um den Wert zu aktualisieren, rufen Sie SecretClient.SetSecret für ein Geheimnis mit demselben Namen auf.

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

Löschen eines Geheimnisses

StartDeleteSecretstartet einen zeitintensiven Vorgang, um ein geheimnis zu löschen, das zuvor im Azure-Key Vault gespeichert wurde. Sie können das Geheimnis sofort abrufen, ohne auf den Abschluss des Vorgangs zu warten. Wenn vorläufiges Löschen für die Azure-Key Vault nicht aktiviert ist, wird das Geheimnis durch diesen Vorgang endgültig gelöscht.

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

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

Löschen und Bereinigen eines Geheimnisses

Sie müssen warten, bis der lang andauernde Vorgang abgeschlossen ist, bevor Sie versuchen, das Geheimnis zu bereinigen oder wiederherzustellen. Dazu können Sie wie unten gezeigt in einer Schleife aufrufen UpdateStatus :

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

Auflisten geheimer Schlüssel

In diesem Beispiel werden alle Geheimnisse im angegebenen Azure-Key Vault aufgelistet. Der Wert wird beim Auflisten aller Geheimnisse nicht zurückgegeben. Sie müssen aufrufen SecretClient.GetSecret , um den Wert abzurufen.

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

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

Asynchrones Erstellen eines Geheimnisses

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 Geheimnis im Azure-Key Vault mit den angegebenen optionalen Argumenten erstellt.

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

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

Asynchrones Auflisten von Geheimnissen

Das Auflisten von Geheimnissen basiert nicht auf dem Warten auf die GetPropertiesOfSecretsAsync -Methode, sondern gibt eine zurück AsyncPageable<SecretProperties> , die Sie mit der await foreach -Anweisung verwenden können:

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

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

Asynchrones Löschen eines Geheimnisses

Wenn Sie ein Geheimnis 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.

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

Problembehandlung

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

Allgemein

Wenn Sie mit der Geheimclientbibliothek von Azure Key Vault 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, ein Geheimnis abzurufen, das in Ihrem Azure Key Vault nicht vorhanden ist, wird ein 404 Fehler zurückgegeben, der angibtNot Found.

try
{
    KeyVaultSecret secret = client.GetSecret("some_secret");
}
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":"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

Nächste Schritte

In diesem GitHub-Repository stehen Ihnen mehrere Beispiele für die Clientbibliothek für Azure Key Vault Geheimnisse 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, einschließlich:

    • Erstellen eines Geheimnisses
    • Abrufen eines vorhandenen Geheimnisses
    • Aktualisieren eines vorhandenen Geheimnisses
    • Löschen von Geheimnissen

  • Sample2_BackupAndRestore.md: Enthält die Codeausschnitte, die mit Azure Key Vault Geheimnissen arbeiten, einschließlich:

    • Sichern und Wiederherstellen eines Geheimnisses

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

    • Erstellen von Geheimnissen
    • Auflisten aller Geheimnisse im Key Vault
    • Aktualisieren von Geheimnissen im Key Vault
    • Auflisten von Versionen eines angegebenen Geheimnisses
    • Löschen von Geheimnissen aus dem Key Vault
    • Auflisten gelöschter Geheimnisse 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