Udostępnij za pośrednictwem

Biblioteka klienta wpisu tajnego usługi Azure Key Vault dla platformy .NET — wersja 4.5.0

  • Artykuł

Azure Key Vault to usługa w chmurze, która zapewnia bezpieczny magazyn wpisów tajnych, takich jak hasła i parametry połączenia bazy danych.

Biblioteka klienta wpisów tajnych usługi Azure Key Vault umożliwia bezpieczne przechowywanie i kontrolowanie dostępu do tokenów, haseł, kluczy interfejsu API i innych wpisów tajnych. Ta biblioteka oferuje operacje tworzenia, pobierania, aktualizowania, usuwania, przeczyszczania, tworzenia kopii zapasowej, przywracania i wyświetlania listy wpisów tajnych i jego wersji.

Kod | źródłowy Pakiet (NuGet) | Dokumentacja referencyjna interfejsu | API Dokumentacja | produktu Próbki | Przewodnik migracji

Wprowadzenie

Instalowanie pakietu

Zainstaluj bibliotekę klienta wpisu tajnego usługi Azure Key Vault dla platformy .NET przy użyciu narzędzia NuGet:

dotnet add package Azure.Security.KeyVault.Secrets

Wymagania wstępne

Jeśli używasz interfejsu wiersza polecenia platformy Azure, zastąp <your-resource-group-name> wartości i <your-key-vault-name> własnymi, unikatowymi nazwami:

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

Uwierzytelnianie klienta

Aby wchodzić w interakcje z usługą Azure Key Vault, należy utworzyć wystąpienie klasy SecretClient. Potrzebny jest adres URL magazynu, który może być widoczny jako "Nazwa DNS" w portalu i poświadczenia do utworzenia wystąpienia obiektu klienta.

W poniższych przykładach użyto DefaultAzureCredentialelementu , który jest odpowiedni dla większości scenariuszy, w tym lokalnych środowisk deweloperskich i produkcyjnych. Ponadto zalecamy używanie tożsamości zarządzanej do uwierzytelniania w środowiskach produkcyjnych. Więcej informacji na temat różnych sposobów uwierzytelniania i odpowiadających im typów poświadczeń można znaleźć w dokumentacji tożsamości platformy Azure .

Aby użyć podanego DefaultAzureCredential poniżej dostawcy lub innych dostawców poświadczeń dostarczanych z zestawem Azure SDK, należy najpierw zainstalować pakiet Azure.Identity:

dotnet add package Azure.Identity

Utwórz wystąpienie elementu DefaultAzureCredential , aby przekazać do klienta. To samo wystąpienie poświadczeń tokenu może być używane z wieloma klientami, jeśli będą uwierzytelniać się przy użyciu tej samej tożsamości.

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

Kluczowe pojęcia

KeyVaultSecret

A KeyVaultSecret to podstawowy zasób w usłudze Azure Key Vault. Z perspektywy dewelopera interfejsy API usługi Azure Key Vault akceptują i zwracają wartości wpisów tajnych jako ciągi.

SecretClient

Element udostępnia SecretClient zarówno operacje synchroniczne, jak i asynchroniczne w zestawie SDK, umożliwiając wybór klienta na podstawie przypadku użycia aplikacji. Po zainicjowaniu elementu SecretClientmożna wchodzić w interakcje z wpisami tajnymi w usłudze Azure Key Vault.

Bezpieczeństwo wątkowe

Gwarantujemy, że wszystkie metody wystąpienia klienta są bezpieczne wątkowo i niezależne od siebie (wytyczne). Dzięki temu zalecenie ponownego obsługi wystąpień klienta jest zawsze bezpieczne, nawet w wątkach.

Dodatkowe pojęcia

Opcje | klienta Uzyskiwanie dostępu do odpowiedzi | Długotrwałe operacje | Obsługa błędów | Diagnostyka | Szyderczy | Okres istnienia klienta

Przykłady

Pakiet Azure.Security.KeyVault.Secrets obsługuje interfejsy API synchroniczne i asynchroniczne.

Poniższa sekcja zawiera kilka fragmentów kodu, które zostały client utworzone powyżej, obejmujące niektóre z najbardziej typowych zadań związanych z usługą wpisów tajnych platformy Azure Key Vault:

Przykłady synchronizacji

Przykłady asynchroniczne

Utwórz klucz tajny

SetSecrettworzy obiekt KeyVaultSecret do przechowywania w usłudze Azure Key Vault. Jeśli wpis tajny o tej samej nazwie już istnieje, zostanie utworzona nowa wersja wpisu tajnego.

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

Pobieranie wpisu tajnego

GetSecretpobiera wpis tajny wcześniej przechowywany w usłudze Azure Key Vault.

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

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

Aktualizowanie istniejącego wpisu tajnego

UpdateSecretPropertiesaktualizuje wpis tajny przechowywany wcześniej w usłudze Azure Key Vault. Tylko atrybuty wpisu tajnego są aktualizowane. Aby zaktualizować wartość, wywołaj wpis SecretClient.SetSecret tajny o tej samej nazwie.

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

Usuń klucz tajny

StartDeleteSecretUruchamia długotrwałą operację usuwania wpisu tajnego wcześniej przechowywanego w usłudze Azure Key Vault. Wpis tajny można pobrać natychmiast bez oczekiwania na ukończenie operacji. Jeśli usuwanie nietrwałe nie jest włączone dla usługi Azure Key Vault, ta operacja trwale usuwa wpis tajny.

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

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

Usuwanie i przeczyszczanie wpisu tajnego

Przed próbą przeczyszczenia lub odzyskania wpisu tajnego należy poczekać na ukończenie długotrwałej operacji. Możesz to zrobić, wywołując UpdateStatus w pętli, jak pokazano poniżej:

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

Wyświetlanie listy wpisów tajnych

W tym przykładzie wymieniono wszystkie wpisy tajne w określonej Key Vault platformy Azure. Wartość nie jest zwracana podczas wyświetlania listy wszystkich wpisów tajnych. Aby pobrać wartość, należy wywołać SecretClient.GetSecret metodę .

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

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

Tworzenie wpisu tajnego asynchronicznie

Asynchroniczne interfejsy API są identyczne z ich synchronicznymi odpowiednikami, ale zwracają z typowym sufiksem "Asynchronicznym" dla metod asynchronicznych i zwracają wartość Task.

W tym przykładzie tworzony jest wpis tajny w usłudze Azure Key Vault z określonymi opcjonalnymi argumentami.

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

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

Asynchroniczna lista wpisów tajnych

Wyświetlanie wpisów tajnych nie polega na oczekiwaniu na metodę GetPropertiesOfSecretsAsync , ale zwraca wartość AsyncPageable<SecretProperties> , której można użyć z instrukcją await foreach :

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

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

Asynchroniczne usuwanie wpisu tajnego

Podczas asynchronicznego usuwania wpisu tajnego przed przeczyszczeniem można oczekiwać WaitForCompletionAsync na metodę operacji. Domyślnie ta pętla jest w nieskończoność, ale można ją anulować, przekazując element 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);

Rozwiązywanie problemów

Zobacz nasz przewodnik rozwiązywania problemów , aby uzyskać szczegółowe informacje na temat diagnozowania różnych scenariuszy awarii.

Ogólne

W przypadku interakcji z biblioteką klienta wpisu tajnego usługi Azure Key Vault przy użyciu zestawu SDK platformy .NET błędy zwracane przez usługę odpowiadają tym samym kodom stanu HTTP zwracanym dla żądań interfejsu API REST.

Jeśli na przykład spróbujesz pobrać wpis tajny, który nie istnieje w usłudze Azure Key Vault, 404 zostanie zwrócony błąd wskazujący Not Foundwartość .

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

Zauważysz, że dodatkowe informacje są rejestrowane, takie jak identyfikator żądania klienta operacji.

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

Następne kroki

Kilka przykładów biblioteki klienta wpisów tajnych usługi Azure Key Vault jest dostępnych w tym repozytorium GitHub. Te przykłady zawierają przykładowy kod dla dodatkowych scenariuszy, które często występują podczas pracy z usługą Azure Key Vault:

  • Sample1_HelloWorld.md — do pracy z usługą Azure Key Vault, w tym:

    • Utwórz klucz tajny
    • Uzyskiwanie istniejącego wpisu tajnego
    • Aktualizowanie istniejącego wpisu tajnego
    • Usuwanie wpisu tajnego

  • Sample2_BackupAndRestore.md — zawiera fragmenty kodu współpracujące z wpisami tajnymi usługi Azure Key Vault, w tym:

    • Tworzenie kopii zapasowej i odzyskiwanie wpisu tajnego

  • Sample3_GetSecrets.md — przykładowy kod do pracy z wpisami tajnymi usługi Azure Key Vault, w tym:

    • Tworzenie wpisów tajnych
    • Wyświetlanie listy wszystkich wpisów tajnych w Key Vault
    • Aktualizowanie wpisów tajnych w Key Vault
    • Wyświetlanie listy wersji określonego wpisu tajnego
    • Usuwanie wpisów tajnych z Key Vault
    • Wyświetlanie listy usuniętych wpisów tajnych w Key Vault

Dodatkowa dokumentacja

Współtworzenie

Zobacz CONTRIBUTING.md , aby uzyskać szczegółowe informacje na temat kompilowania, testowania i współtworzenia tych bibliotek.

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.

Wrażenia