Udostępnij przez

Biblioteka klienta certyfikatu usługi Azure Key Vault dla platformy .NET — wersja 4.5.1

  • Artykuł

Azure Key Vault to usługa w chmurze, która zapewnia bezpieczny magazyn i zautomatyzowane zarządzanie certyfikatami używanymi w całej aplikacji w chmurze. Wiele certyfikatów i wiele wersji tego samego certyfikatu można przechowywać w usłudze Azure Key Vault. Każdy certyfikat w magazynie ma skojarzone z nim zasady, które kontrolują wystawianie i okres istnienia certyfikatu, wraz z akcjami, które mają być podejmowane jako certyfikaty zbliżające się do wygaśnięcia.

Biblioteka klienta certyfikatów usługi Azure Key Vault umożliwia programowe zarządzanie certyfikatami, oferowanie metod tworzenia, aktualizowania, wyświetlania listy i usuwania certyfikatów, zasad, wystawców i kontaktów. Biblioteka obsługuje również zarządzanie oczekującymi operacjami certyfikatów i zarządzanie usuniętymi certyfikatami.

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

Wprowadzenie

Instalowanie pakietu

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

dotnet add package Azure.Security.KeyVault.Certificates

Wymagania wstępne

Jeśli używasz interfejsu wiersza polecenia platformy Azure, zastąp <your-resource-group-name> element 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 móc korzystać z usługi Azure Key Vault, należy utworzyć wystąpienie klasy CertificateClient. 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 elementu DefaultAzureCredential, który jest odpowiedni dla większości scenariuszy, w tym lokalnych środowisk programistycznych i produkcyjnych. Ponadto zalecamy użycie 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 usługi Azure Identity .

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

dotnet add package Azure.Identity

Tworzenie elementu CertificateClient

DefaultAzureCredential Utwórz wystąpienie elementu , aby przekazać go 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 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());

Kluczowe pojęcia

KeyVaultCertificate

Element to KeyVaultCertificate podstawowy zasób w ramach usługi Azure Key Vault. Certyfikaty będą używane do szyfrowania i weryfikowania zaszyfrowanych lub podpisanych danych.

CertificateClient

Za pomocą programu CertificateClient można pobrać certyfikaty z magazynu, utworzyć nowe certyfikaty i nowe wersje istniejących certyfikatów, zaktualizować metadane certyfikatów i usunąć certyfikaty. Można również zarządzać wystawcami certyfikatów, kontaktami i zasadami zarządzania certyfikatami. Przedstawiono to w poniższych przykładach.

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 instalowania 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.Certificates obsługuje synchroniczne i asynchroniczne interfejsy API.

W poniższej client sekcji przedstawiono kilka fragmentów kodu utworzonych powyżej, które obejmują niektóre z najbardziej typowych zadań związanych z usługą certyfikatów platformy Azure Key Vault:

Przykłady synchronizacji

Przykłady asynchroniczne

Tworzenie certyfikatu

StartCreateCertificateTworzy certyfikat do przechowywania w usłudze Azure Key Vault. Jeśli certyfikat o tej samej nazwie już istnieje, zostanie utworzona nowa wersja certyfikatu. Podczas tworzenia certyfikatu użytkownik może określić zasady kontrolujące okres istnienia certyfikatu. Jeśli nie określono żadnych zasad, zostaną użyte zasady domyślne. Operacja StartCreateCertificate zwraca wartość CertificateOperation. Poniższy przykład tworzy certyfikat z podpisem własnym z domyślnymi zasadami.

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

UWAGA: W zależności od metod wystawcy certyfikatu i weryfikacji tworzenie certyfikatu i podpisywanie może zająć nieokreślony czas. Użytkownicy powinni czekać tylko na operacje certyfikatów, gdy operacja może być rozsądnie ukończona w zakresie aplikacji, na przykład z certyfikatami z podpisem własnym lub wystawcami z dobrze znanymi czasami odpowiedzi.

Pobieranie certyfikatu

GetCertificatepobiera najnowszą wersję certyfikatu przechowywanego w usłudze Azure Key Vault wraz z jego wersją CertificatePolicy.

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

GetCertificateVersion pobiera określoną wersję certyfikatu w magazynie.

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

Aktualizowanie istniejącego certyfikatu

UpdateCertificateaktualizuje certyfikat przechowywany w usłudze Azure Key Vault.

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

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

Wyświetlanie listy certyfikatów

GetCertificates Wylicza certyfikaty w magazynie, zwracając wybrane właściwości certyfikatu. Poufne pola certyfikatu nie zostaną zwrócone. Ta operacja wymaga uprawnień certyfikatów/listy.

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

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

Usuwanie certyfikatu

DeleteCertificateUsuwa wszystkie wersje certyfikatu przechowywane w usłudze Azure Key Vault. Gdy usuwanie nietrwałe nie jest włączone dla usługi Azure Key Vault, ta operacja trwale usuwa certyfikat. Jeśli usuwanie nietrwałe jest włączone, certyfikat jest oznaczony do usunięcia i można opcjonalnie przeczyścić lub odzyskać do daty zaplanowanego przeczyszczenia.

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

Tworzenie certyfikatu asynchronicznie

Interfejsy API asynchroniczne są identyczne z ich synchronicznymi odpowiednikami, ale zwracają typowe sufiksy "asynchroniczne" dla metod asynchronicznych i zwracają Taskwartość .

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

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

Wyświetlanie listy certyfikatów asynchronicznie

Wyświetlanie certyfikatu nie polega na oczekiwaniu na metodę GetPropertiesOfCertificatesAsync , ale zwraca wartość AsyncPageable<CertificateProperties> , której można użyć z instrukcją await foreach :

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

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

Usuwanie certyfikatu asynchronicznie

Podczas usuwania certyfikatu asynchronicznie przed jego przeczyszczeniem można oczekiwać WaitForCompletionAsync na metodę operacji. Domyślnie ta pętla jest w nieskończoność, ale można ją anulować, przekazując CancellationTokenelement .

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

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 certyfikatów usługi Azure Key Vault przy użyciu zestawu SDK platformy .NET błędy zwrócone przez usługę odpowiadają tym samym kodom stanu HTTP zwróconym dla żądań interfejsu API REST.

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

try
{
    KeyVaultCertificateWithPolicy certificateWithPolicy = client.GetCertificate("SomeCertificate");
}
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":"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

Następne kroki

Kilka przykładów biblioteki klienta certyfikatów platformy Azure Key Vault jest dostępnych w tym repozytorium GitHub. Te przykłady zawierają przykładowy kod dla dodatkowych scenariuszy często napotykanych podczas pracy z usługą Azure Key Vault:

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

    • Tworzenie certyfikatu
    • Pobieranie istniejącego certyfikatu
    • Aktualizowanie istniejącego certyfikatu
    • Usuwanie certyfikatu

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

    • Tworzenie certyfikatów
    • Wyświetlanie listy wszystkich certyfikatów w Key Vault
    • Wyświetlanie listy wersji określonego certyfikatu
    • Usuwanie certyfikatów z Key Vault
    • Wyświetlanie listy usuniętych certyfikatów 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