Schnellstart: Azure Key Vault-Geheimnisclientbibliothek für .NET

  • Artikel

Hier finden Sie Informationen zu den ersten Schritten mit der Azure Key Vault-Geheimnisclientbibliothek für .NET. Azure Key Vault ist ein Clouddienst, der als sicherer Geheimnisspeicher fungiert. Dadurch können Schlüssel, Kennwörter, Zertifikate und andere Geheimnisse sicher gespeichert werden. Azure Key Vault-Instanzen können über das Azure-Portal erstellt und verwaltet werden. In dieser Schnellstartanleitung erfahren Sie, wie Sie mithilfe der .NET-Clientbibliothek Geheimnisse in einem Azure-Schlüsseltresor erstellen, daraus abrufen und löschen.

Ressourcen der Key Vault-Clientbibliothek:

API-Referenzdokumentation | Quellcode der Bibliothek | Paket (NuGet)

Weitere Informationen zu Key Vault und Geheimnissen finden Sie unter folgenden Links:

Voraussetzungen

Diese Schnellstartanleitung verwendet dotnet und Azure CLI oder Azure PowerShell.

Einrichten

In dieser Schnellstartanleitung wird die Azure Identity-Bibliothek mit der Azure CLI verwendet, um den Benutzer bei Azure-Diensten zu authentifizieren. Entwickler können auch Visual Studio oder Visual Studio Code verwenden, um ihre Aufrufe zu authentifizieren. Weitere Informationen finden Sie unter Authentifizieren des Clients mit der Azure Identity-Clientbibliothek.

Anmelden bei Azure

  1. Führen Sie den Befehl az login aus.

    az login

    Die CLI öffnet Ihren Standardbrowser, sofern sie dazu in der Lage ist, und lädt eine Azure-Anmeldeseite.

    Öffnen Sie andernfalls die Browserseite https://aka.ms/devicelogin, und geben Sie den in Ihrem Terminal angezeigten Autorisierungscode ein.

  2. Melden Sie sich im Browser mit Ihren Anmeldeinformationen an.

Gewähren des Zugriffs auf Ihren Schlüsseltresor

Um Ihrem Schlüsseltresor über die rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) Berechtigungen für Ihre Anwendung zu gewähren, weisen Sie mithilfe des Azure CLI-Befehls az role assignment create eine Rolle zu.

az role assignment create --role "Key Vault Secrets User" --assignee "<app-id>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Ersetzen Sie <app-id>, <subscription-id>, <resource-group-name> und <your-unique-keyvault-name> durch Ihre tatsächlichen Werte. <app-id> ist die Anwendungs-ID (Client-ID) Ihrer registrierten Anwendung in Azure AD.

Erstellen einer neuen .NET-Konsolen-App

  1. Führen Sie in einer Befehlsshell den folgenden Befehl aus, um ein Projekt namens key-vault-console-app zu erstellen:

    dotnet new console --name key-vault-console-app

  2. Wechseln Sie zum neu erstellten Verzeichnis key-vault-console-app, und führen Sie den folgenden Befehl aus, um das Projekt zu erstellen:

    dotnet build

    Die Buildausgabe sollte keine Warnungen oder Fehler enthalten.

    Build succeeded.
 0 Warning(s)
 0 Error(s)

Installieren der Pakete

Installieren Sie über die Befehlsshell die Azure Key Vault-Geheimnisclientbibliothek für .NET:

dotnet add package Azure.Security.KeyVault.Secrets

Für diese Schnellstartanleitung müssen Sie auch die Azure Identity-Clientbibliothek installieren:

dotnet add package Azure.Identity

Festlegen von Umgebungsvariablen

Diese Anwendung verwendet den Namen des Schlüsseltresors als Umgebungsvariable namens KEY_VAULT_NAME.

Windows

set KEY_VAULT_NAME=<your-key-vault-name>

Windows PowerShell

$Env:KEY_VAULT_NAME="<your-key-vault-name>"

macOS oder Linux

export KEY_VAULT_NAME=<your-key-vault-name>

Objektmodell

Mit der Azure Key Vault-Geheimnisclientbibliothek für .NET können Sie Geheimnisse verwalten. Im Abschnitt Codebeispiele wird gezeigt, wie ein Client erstellt und ein Geheimnis festgelegt, abgerufen und gelöscht wird.

Codebeispiele

Hinzufügen von Anweisungen

Fügen Sie am Anfang von Program.cs die folgenden Anweisungen hinzu:

using System;
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

Authentifizieren und Erstellen eines Clients

Anwendungsanforderungen an die meisten Azure-Dienste müssen autorisiert werden. Die Verwendung der von der Azure Identity-Clientbibliothek bereitgestellten Klasse DefaultAzureCredential ist der empfohlene Ansatz zum Implementieren von kennwortlosen Verbindungen mit Azure-Diensten in Ihrem Code. DefaultAzureCredential unterstützt mehrere Authentifizierungsmethoden und bestimmt, welche Methode zur Laufzeit verwendet werden soll. Bei diesem Ansatz kann Ihre App unterschiedliche Authentifizierungsmethoden in verschiedenen Umgebungen (lokal gegenüber Produktion) verwenden, ohne umgebungsspezifischen Code zu implementieren.

In dieser Schnellstartanleitung authentifiziert sich DefaultAzureCredential mit den Anmeldeinformationen des lokalen Entwicklungsbenutzers, der bei der Azure CLI angemeldet ist, beim Schlüsseltresor. Wenn die Anwendung in Azure bereitgestellt wird, kann derselbe DefaultAzureCredential-Code automatisch eine verwaltete Identität ermitteln und verwenden, die App Service, einem virtuellen Computer oder anderen Diensten zugewiesen ist. Weitere Informationen finden Sie in der Übersicht zu verwalteten Identitäten.

In diesem Beispiel wird der Name Ihres Schlüsseltresors in den Schlüsseltresor-URI mit dem Format https://<your-key-vault-name>.vault.azure.net erweitert. Weitere Informationen zur Authentifizierung beim Schlüsseltresor finden Sie im Entwicklerhandbuch.

string keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
var kvUri = "https://" + keyVaultName + ".vault.azure.net";

var client = new SecretClient(new Uri(kvUri), new DefaultAzureCredential());

Speichern eines Geheimnisses

Nachdem die Konsolen-App authentifiziert wurde, fügen Sie dem Schlüsseltresor ein Geheimnis hinzu. Verwenden Sie hierfür die SetSecretAsync-Methode.

Der erste Parameter der Methode akzeptiert einen Namen für das Geheimnis. In diesem Beispiel speichert die Variable secretName die Zeichenfolge „mySecret“.

Der zweite Parameter der Methode akzeptiert einen Wert für das Geheimnis. In diesem Beispiel wird das Geheimnis von Benutzer*innen über die Befehlszeile eingegeben und in der Variablen secretValue gespeichert.

await client.SetSecretAsync(secretName, secretValue);

Hinweis

Ist der Geheimnisname vorhanden, erstellt der Code eine neue Version dieses Geheimnisses.

Abrufen eines Geheimnisses

Nun können Sie den zuvor festgelegten Wert mithilfe der GetSecretAsync-Methode abrufen.

var secret = await client.GetSecretAsync(secretName);

Ihr Geheimnis ist jetzt als secret.Value gespeichert.

Löschen eines Geheimnisses

Verwenden Sie abschließend die Methoden StartDeleteSecretAsync und PurgeDeletedSecretAsync, um das Geheimnis aus Ihrem Schlüsseltresor zu löschen.

var operation = await client.StartDeleteSecretAsync(secretName);
// You only need to wait for completion if you want to purge or recover the key.
await operation.WaitForCompletionAsync();

await client.PurgeDeletedSecretAsync(secretName);

Beispielcode

Führen Sie die folgenden Schritte aus, um die .NET-Konsolen-App so zu ändern, dass Sie mit dem Schlüsseltresor interagiert:

  1. Ersetzen Sie den Code in Program.cs durch den folgenden Code:

    using System;
using System.Threading.Tasks;
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

namespace key_vault_console_app
{
    class Program
    {
        static async Task Main(string[] args)
        {
            const string secretName = "mySecret";
            var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
            var kvUri = $"https://{keyVaultName}.vault.azure.net";

            var client = new SecretClient(new Uri(kvUri), new DefaultAzureCredential());

            Console.Write("Input the value of your secret > ");
            var secretValue = Console.ReadLine();

            Console.Write($"Creating a secret in {keyVaultName} called '{secretName}' with the value '{secretValue}' ...");
            await client.SetSecretAsync(secretName, secretValue);
            Console.WriteLine(" done.");

            Console.WriteLine("Forgetting your secret.");
            secretValue = string.Empty;
            Console.WriteLine($"Your secret is '{secretValue}'.");

            Console.WriteLine($"Retrieving your secret from {keyVaultName}.");
            var secret = await client.GetSecretAsync(secretName);
            Console.WriteLine($"Your secret is '{secret.Value.Value}'.");

            Console.Write($"Deleting your secret from {keyVaultName} ...");
            DeleteSecretOperation operation = await client.StartDeleteSecretAsync(secretName);
            // You only need to wait for completion if you want to purge or recover the secret.
            await operation.WaitForCompletionAsync();
            Console.WriteLine(" done.");

            Console.Write($"Purging your secret from {keyVaultName} ...");
            await client.PurgeDeletedSecretAsync(secretName);
            Console.WriteLine(" done.");
        }
    }
}

Testen und Überprüfen

  1. Führen Sie die App mit dem folgenden Befehl aus.

    dotnet run

  2. Geben Sie bei entsprechender Aufforderung einen Geheimniswert ein, z. B. „mySecretPassword“.

Eine Variation der folgenden Ausgabe wird angezeigt:

Input the value of your secret > mySecretPassword
Creating a secret in <your-unique-keyvault-name> called 'mySecret' with the value 'mySecretPassword' ... done.
Forgetting your secret.
Your secret is ''.
Retrieving your secret from <your-unique-keyvault-name>.
Your secret is 'mySecretPassword'.
Deleting your secret from <your-unique-keyvault-name> ... done.    
Purging your secret from <your-unique-keyvault-name> ... done.

Nächste Schritte

Weitere Informationen zu Key Vault und zur Integration in Ihre Apps finden Sie in den folgenden Artikeln: