Klientská knihovna tajných kódů Azure Key Vault pro .NET – verze 4.5.0

  • Článek

Azure Key Vault je cloudová služba, která poskytuje zabezpečené úložiště tajných kódů, jako jsou hesla a připojovací řetězce databáze.

Klientská knihovna Tajných kódů Azure Key Vault umožňuje bezpečně ukládat tokeny, hesla, klíče rozhraní API a další tajné kódy a řídit přístup k nim. Tato knihovna nabízí operace pro vytvoření, načtení, aktualizaci, odstranění, vymazání, zálohování, obnovení a výpis tajných kódů a jejich verzí.

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 tajných kódů Azure Key Vault pro .NET pomocí NuGetu:

dotnet add package Azure.Security.KeyVault.Secrets

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

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

V níže uvedených příkladech se používá DefaultAzureCredential, který je vhodný pro většinu scénářů, včetně místního vývojového a produkčního prostředí. Kromě toho doporučujeme pro ověřování v produkčních prostředích používat spravovanou identitu. 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 ke službě Azure Identity .

Pokud chcete použít DefaultAzureCredential níže uvedeného zprostředkovatele 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ř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 budou ověřovat pomocí stejné identity.

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

Klíčové koncepty

KeyVaultSecret

A KeyVaultSecret je základní prostředek v rámci Azure Key Vault. Z pohledu vývojáře rozhraní API Azure Key Vault přijímají a vracejí hodnoty tajných kódů jako řetězce.

SecretClient

Poskytuje SecretClient synchronní i asynchronní operace v sadě SDK, které umožňují výběr klienta na základě případu použití aplikace. Jakmile inicializujete SecretClient, můžete s tajnými kódy pracovat v Azure Key Vault.

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ě používat instance klienta je 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.Secrets podporuje synchronní a asynchronní rozhraní API.

Následující část obsahuje několik fragmentů kódu pomocí client výše vytvořeného kódu, které pokrývají některé z nejběžnějších úloh souvisejících s Azure Key Vault tajnými službami:

Příklady synchronizace

Příklady asynchronních funkcí

Vytvoření tajného klíče

SetSecretvytvoří soubor, který KeyVaultSecret se uloží do Key Vault Azure. Pokud tajný kód se stejným názvem již existuje, vytvoří se nová verze tajného kódu.

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

Načtení tajného kódu

GetSecretnačte tajný kód dříve uložený v azure Key Vault.

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

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

Aktualizace existujícího tajného kódu

UpdateSecretPropertiesaktualizuje tajný klíč uložený dříve v Azure Key Vault. Aktualizují se jenom atributy tajného kódu. Pokud chcete hodnotu aktualizovat, zavolejte SecretClient.SetSecret na tajný kód se stejným názvem.

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

Odstranění tajného klíče

StartDeleteSecretspustí dlouhotrvající operaci, která odstraní tajný klíč uložený dříve v Azure Key Vault. Tajný kód můžete načíst okamžitě, aniž byste museli čekat na dokončení operace. Pokud pro azure Key Vault není povolené obnovitelné odstranění, tato operace tajný klíč trvale odstraní.

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

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

Odstranění a vymazání tajného kódu

Než se pokusíte tajný klíč vyprázdnit nebo obnovit, budete muset počkat na dokončení dlouhotrvající operace. Můžete to provést voláním UpdateStatus smyčky, jak je znázorněno níže:

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

Výpis tajných kódů

Tento příklad vypíše všechny tajné kódy v zadaném Key Vault Azure. Hodnota se při výpisu všech tajných kódů nevrátí. K načtení hodnoty budete muset volat SecretClient.GetSecret .

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

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

Asynchronní vytvoření tajného kódu

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ří tajný kód v azure Key Vault se zadanými volitelnými argumenty.

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

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

Asynchronní výpis tajných kódů

Výpis tajných kódů nespoléhá na čekání na metodu GetPropertiesOfSecretsAsync , ale vrátí hodnotu AsyncPageable<SecretProperties> , kterou můžete použít s příkazem await foreach :

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

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

Asynchronní odstranění tajného kódu

Při asynchronním odstranění tajného kódu před jeho vymazáním můžete počkat na metodu WaitForCompletionAsync operace. Ve výchozím nastavení se tato smyčka smyje po neomezenou dobu, ale můžete ji zrušit předáním 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);

Ř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 Azure Key Vault tajných kódů 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 tajný kód, který v Azure Key Vault neexistuje, 404 vrátí se chyba s informací Not Found.

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

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

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

Další kroky

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

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

    • Vytvoření tajného klíče
    • Získání existujícího tajného kódu
    • Aktualizace existujícího tajného kódu
    • Odstranit tajný kód

  • Sample2_BackupAndRestore.md – obsahuje fragmenty kódu, které pracují s tajnými kódy Azure Key Vault, včetně následujících:

    • Zálohování a obnovení tajného kódu

  • Sample3_GetSecrets.md – ukázkový kód pro práci s tajnými kódy Azure Key Vault, včetně:

    • Vytváření tajných kódů
    • Výpis všech tajných kódů v Key Vault
    • Aktualizace tajných kódů v Key Vault
    • Výpis verzí zadaného tajného kódu
    • Odstranění tajných kódů z Key Vault
    • Výpis odstraněných tajných kódů 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