Klientská knihovna certifikátů Azure Key Vault pro .NET – verze 4.5.1

  • Článek

Azure Key Vault je cloudová služba, která poskytuje zabezpečené úložiště a automatizovanou správu certifikátů používaných v rámci cloudové aplikace. V Azure Key Vault je možné uchovávat více certifikátů a více verzí stejného certifikátu. Ke každému certifikátu v trezoru jsou přidružené zásady, které řídí vystavování a životnost certifikátu, spolu s akcemi, které se mají provést jako certifikáty blízko vypršení platnosti.

Klientská knihovna certifikátů Azure Key Vault umožňuje programovou správu certifikátů a nabízí metody pro vytváření, aktualizaci, výpis a odstraňování certifikátů, zásad, vystavitelů a kontaktů. Knihovna také podporuje správu čekajících operací certifikátů a správu odstraněných certifikátů.

Zdrojový kód | Balíček (NuGet) | Referenční dokumentace k | rozhraní API Dokumentace k | produktu Vzorky | Průvodce migrací

Začínáme

Instalace balíčku

Nainstalujte klientskou knihovnu certifikátů Azure Key Vault pro .NET pomocí NuGetu:

dotnet add package Azure.Security.KeyVault.Certificates

Požadavky

Pokud používáte Azure CLI, nahraďte <your-resource-group-name> a <your-key-vault-name> vlastními jedinečnými názvy:

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

Ověření klienta

Abyste mohli pracovat se službou Azure Key Vault, budete muset vytvořit instanci třídy CertificateClient. K vytvoření instance objektu klienta potřebujete adresu URL trezoru, která se na portálu může zobrazit jako Název DNS, a přihlašovací údaje.

Níže uvedené příklady používají DefaultAzureCredentialobjekt , který je vhodný pro většinu scénářů, včetně místních vývojových a produkčních prostředí. Kromě toho doporučujeme použít spravovanou identitu pro ověřování v produkčních prostředích. Další informace o různých způsobech ověřování a jejich odpovídajících typech přihlašovacích údajů najdete v dokumentaci k Identitě Azure .

Pokud chcete použít DefaultAzureCredential zprostředkovatele uvedeného níže nebo jiné zprostředkovatele přihlašovacích údajů poskytované se sadou Azure SDK, musíte nejprve nainstalovat balíček Azure.Identity:

dotnet add package Azure.Identity

Vytvořit CertificateClient

Vytvořte instanci, která DefaultAzureCredential se má předat klientovi. Stejnou instanci přihlašovacích údajů tokenu je možné použít s více klienty, pokud se budou ověřovat se stejnou identitou.

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

Klíčové koncepty

KeyVaultCertificate

A KeyVaultCertificate je základní prostředek v rámci Azure Key Vault. Certifikáty budete používat k šifrování a ověřování šifrovaných nebo podepsaných dat.

CertificateClient

CertificateClient Pomocí nástroje můžete získat certifikáty z trezoru, vytvářet nové certifikáty a nové verze existujících certifikátů, aktualizovat metadata certifikátů a odstraňovat certifikáty. Můžete také spravovat vystavitele certifikátů, kontakty a zásady správy certifikátů. To je znázorněno v následujících příkladech.

Bezpečnost vlákna

Zaručujeme, že všechny metody instance klienta jsou bezpečné pro přístup z více vláken a nezávislé na sobě (pokyny). Tím se zajistí, že doporučení opakovaného použití instancí klienta bude vždy bezpečné, a to i napříč vlákny.

Další koncepty

Možnosti | klienta Přístup k odpovědi | Dlouhotrvající operace | Zpracování selhání | Diagnostika | Zesměšňovat | Životnost klienta

Příklady

Balíček Azure.Security.KeyVault.Certificates podporuje synchronní a asynchronní rozhraní API.

Následující část obsahuje několik fragmentů kódu pomocí výše vytvořenéhoclient kódu, které pokrývají některé z nejběžnějších úloh souvisejících se službou Azure Key Vault certificate service:

Příklady synchronizace

Asynchronní příklady

Vytvoření certifikátu

StartCreateCertificatevytvoří certifikát, který se uloží do azure Key Vault. Pokud již existuje certifikát se stejným názvem, vytvoří se nová verze certifikátu. Při vytváření certifikátu může uživatel zadat zásadu, která řídí životnost certifikátu. Pokud nezadáte žádnou zásadu, použijí se výchozí zásady. Operace StartCreateCertificate vrátí .CertificateOperation Následující příklad vytvoří certifikát podepsaný svým držitelem s výchozí zásadou.

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

POZNÁMKA: V závislosti na vystaviteli certifikátu a metodách ověření může vytvoření a podepisování certifikátu trvat neurčitou dobu. Uživatelé by měli čekat pouze na operace s certifikáty, pokud je možné operaci přiměřeně dokončit v rozsahu aplikace, například u certifikátů podepsaných svým držitelem nebo vystavitelů s dobře známou dobou odezvy.

Načtení certifikátu

GetCertificateNačte nejnovější verzi certifikátu uloženého v Azure Key Vault spolu s .CertificatePolicy

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

GetCertificateVersion načte konkrétní verzi certifikátu v trezoru.

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

Aktualizace existujícího certifikátu

UpdateCertificateaktualizuje certifikát uložený v Azure Key Vault.

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

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

Výpis certifikátů

GetCertificates vytvoří výčet certifikátů v trezoru a vrátí vybrané vlastnosti certifikátu. Citlivá pole certifikátu se nevrátí. Tato operace vyžaduje oprávnění certifikátů nebo seznamů.

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

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

Odstranění certifikátu

DeleteCertificateodstraní všechny verze certifikátu uloženého v Azure Key Vault. Pokud pro Azure Key Vault není povolené obnovitelné odstranění, tato operace trvale odstraní certifikát. Pokud je povolené obnovitelné odstranění, certifikát se označí k odstranění a dá se volitelně vymazat nebo obnovit až do plánovaného data vymazání.

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

Asynchronní vytvoření certifikátu

Asynchronní rozhraní API jsou shodná se svými synchronními protějšky, ale vrací se s typickou příponou Async pro asynchronní metody a vrací Taskhodnotu .

Tento příklad vytvoří certifikát v azure Key Vault se zadanými volitelnými argumenty.

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

Asynchronní výpis certifikátů

Výpis certifikátu nespoléhá na čekání na metodu GetPropertiesOfCertificatesAsync , ale vrátí AsyncPageable<CertificateProperties> hodnotu, kterou můžete použít s příkazem await foreach :

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

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

Asynchronní odstranění certifikátu

Při asynchronním odstraňování certifikátu před vyprázdněním můžete počkat na metodu WaitForCompletionAsync operace. Ve výchozím nastavení se tato smyčka trvale smyče, ale můžete ji zrušit předáním CancellationTokenpříkazu .

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

Řešení potíží

Podrobnosti o tom, jak diagnostikovat různé scénáře selhání, najdete v našem průvodci odstraňováním potíží.

Obecné

Při interakci s klientskou knihovnou certifikátů Azure Key Vault pomocí sady .NET SDK odpovídají chyby vrácené službou stejným stavovým kódům HTTP vráceným pro požadavky rozhraní REST API.

Pokud se například pokusíte načíst klíč, který v Azure Key Vault neexistuje, 404 vrátí se chyba s informací Not Found.

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

Všimněte si, že se protokolují další informace, například ID žádosti klienta operace.

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

Další kroky

V tomto úložišti GitHub máte k dispozici několik ukázek klientské knihovny certifikátů Azure Key Vault. Tyto ukázky poskytují příklad kódu pro další scénáře, se kterými se při práci s Azure Key Vault běžně setkáváme:

  • Sample1_HelloWorld.md – pro práci s certifikáty Azure Key Vault, včetně:

    • Vytvoření certifikátu
    • Získání existujícího certifikátu
    • Aktualizace existujícího certifikátu
    • Odstranění certifikátu

  • Sample2_GetCertificates.md – příklad kódu pro práci s certifikáty Azure Key Vault, včetně následujících:

    • Vytvoření certifikátů
    • Výpis všech certifikátů v Key Vault
    • Výpis verzí zadaného certifikátu
    • Odstranění certifikátů z Key Vault
    • Výpis odstraněných certifikátů v Key Vault

Další dokumentace

Přispívání

Podrobnosti o sestavování, testování a přispívání do těchto knihoven najdete v CONTRIBUTING.md .

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo se obraťte na opencode@microsoft.com případné další dotazy nebo komentáře.

Imprese