Azure Key Vault titkos ügyfélkódtár a .NET-hez – 4.5.0-s verzió

  • Cikk

Az Azure Key Vault egy felhőszolgáltatás, amely biztonságosan tárolja a titkos kódokat, például a jelszavakat és az adatbázis-kapcsolati sztringeket.

Az Azure Key Vault titkoskódtár lehetővé teszi a jogkivonatok, jelszavak, API-kulcsok és egyéb titkos kódok biztonságos tárolását és vezérlését. Ez a kódtár műveleteket kínál a titkos kódok és azok verzióinak létrehozásához, lekéréséhez, frissítéséhez, törléséhez, végleges törléséhez, biztonsági mentéséhez, visszaállításához és listázásához.

Forráskód | Csomag (NuGet) | API-referenciadokumentáció | Termékdokumentáció | Minták | Migrálási útmutató

Első lépések

A csomag telepítése

Telepítse a .NET-hez készült Azure Key Vault titkos ügyfélkódtárat a NuGet használatával:

dotnet add package Azure.Security.KeyVault.Secrets

Előfeltételek

Ha az Azure CLI-t használja, cserélje le <your-resource-group-name> a és <your-key-vault-name> a elemet a saját egyedi nevére:

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

Az ügyfél hitelesítése

Az Azure Key Vault szolgáltatás használatához létre kell hoznia a SecretClient osztály egy példányát. Szüksége van egy tároló URL-címére, amelyet a portálon "DNS-név" néven láthat, valamint hitelesítő adatokra egy ügyfélobjektum példányosításához.

Az alábbi példák a DefaultAzureCredentiallegtöbb forgatókönyvhöz , például a helyi fejlesztési és éles környezetekhez megfelelőt használnak. Emellett azt javasoljuk, hogy felügyelt identitást használjon a hitelesítéshez éles környezetben. A hitelesítés különböző módjairól és a hozzájuk tartozó hitelesítő adatok típusairól az Azure Identity dokumentációjában talál további információt.

Az alább látható szolgáltató vagy az Azure SDK-hoz biztosított egyéb hitelesítőadat-szolgáltatók használatához DefaultAzureCredential először telepítenie kell az Azure.Identity csomagot:

dotnet add package Azure.Identity

Példányosíthat egy példányt DefaultAzureCredential az ügyfélnek való továbbításhoz. A jogkivonat hitelesítő adatainak ugyanazon példánya több ügyféllel is használható, ha ugyanazzal az identitással fognak hitelesítést végezni.

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

Fő fogalmak

KeyVaultSecret

Az A KeyVaultSecret az Azure Key Vault alapvető erőforrása. A fejlesztők szempontjából az Azure Key Vault API-k sztringként fogadják el és adják vissza a titkos értékeket.

SecretClient

Az A SecretClient szinkron és aszinkron műveleteket is biztosít az SDK-ban, lehetővé téve az ügyfél kiválasztását az alkalmazás használati esete alapján. A inicializálása SecretClientután az Azure Key Vault titkos kódokkal kommunikálhat.

Menetbiztonság

Garantáljuk, hogy minden ügyfélpéldány-metódus szálbiztos és független egymástól (útmutató). Ez biztosítja, hogy az ügyfélpéldányok újrafelhasználására vonatkozó javaslat mindig biztonságos legyen, még a szálak között is.

További fogalmak

Ügyfélbeállítások | A válasz | elérése Hosszú ideig futó műveletek | Hibák | kezelése Diagnosztika | Gúnyos | Ügyfélélettartam

Példák

Az Azure.Security.KeyVault.Secrets csomag támogatja a szinkron és aszinkron API-kat.

A következő szakasz számos kódrészletet tartalmaz a client fent létrehozottak alapján, amelyek az Azure Key Vault titkos szolgáltatással kapcsolatos leggyakoribb feladatokat ismertetik:

Példák szinkronizálására

Példák aszinkronizálásra

Titkos kulcs létrehozása

SetSecretlétrehoz egyKeyVaultSecret, az Azure-Key Vault tárolandót. Ha már létezik ilyen nevű titkos kód, akkor létrejön a titkos kód egy új verziója.

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

Titkos kód lekérése

GetSecretlekéri az Azure Key Vault korábban tárolt titkos kódot.

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

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

Meglévő titkos kód frissítése

UpdateSecretPropertiesfrissíti a korábban az Azure Key Vault tárolt titkos kódot. Csak a titkos kód attribútumai frissülnek. Az érték frissítéséhez hívja SecretClient.SetSecret meg a titkos kódot ugyanazzal a névvel.

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

Titkos kulcs törlése

StartDeleteSecretelindít egy hosszú ideig futó műveletet az Azure Key Vault korábban tárolt titkos kód törléséhez. A titkos kódot azonnal lekérheti anélkül, hogy megvárja a művelet befejezését. Ha a helyreállítható törlés nincs engedélyezve az Azure Key Vault esetében, ez a művelet véglegesen törli a titkos kódot.

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

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

Titkos kód törlése és végleges törlése

Meg kell várnia, amíg a hosszú ideig futó művelet befejeződik, mielőtt megpróbálná véglegesíteni vagy helyreállítani a titkos kódot. Ezt úgy teheti meg, hogy egy hurokban hívja UpdateStatus meg az alábbiakat:

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

Titkos kulcsok listázása

Ez a példa felsorolja a megadott Azure-Key Vault összes titkos kódját. A függvény nem adja vissza az értéket az összes titkos kód listázásakor. Az érték lekéréséhez hívás SecretClient.GetSecret szükséges.

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

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

Titkos kód aszinkron létrehozása

Az aszinkron API-k megegyeznek a szinkron megfelelőikkel, de az aszinkron metódusok jellemző "Async" utótagjával térnek vissza, és egy Taskértéket adnak vissza.

Ez a példa létrehoz egy titkos kódot az Azure Key Vault a megadott választható argumentumokkal.

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

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

Titkos kódok aszinkron listázása

A titkos kódok listázása nem a metódusra GetPropertiesOfSecretsAsync vár, hanem az utasítással await foreach használható értéket AsyncPageable<SecretProperties> ad vissza:

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

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

Titkos kód aszinkron törlése

Ha aszinkron módon töröl egy titkos kódot, mielőtt véglegesítheti, megvárhatja a metódust WaitForCompletionAsync a művelet során. Alapértelmezés szerint ez a ciklus határozatlan ideig ismétlődik, de egy parancs átadásával CancellationTokenmegszakíthatja azt.

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

Hibaelhárítás

A különböző hibaforgatókönyvek diagnosztizálásával kapcsolatos részletekért tekintse meg a hibaelhárítási útmutatónkat .

Általános kérdések

Amikor az Azure Key Vault titkos ügyfélkódtárat használja a .NET SDK-val, a szolgáltatás által visszaadott hibák megegyeznek a REST API-kérésekhez visszaadott HTTP-állapotkódokkal.

Ha például olyan titkos kódot próbál lekérni, amely nem létezik az Azure-Key Vault, a rendszer hibát 404 ad vissza, amely azt jelziNot Found, hogy .

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

Megfigyelheti, hogy a rendszer további adatokat naplóz, például a művelet ügyfélkérés-azonosítóját.

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

Következő lépések

Ebben a GitHub-adattárban számos Azure Key Vault titkos ügyfélkódtár-minta érhető el. Ezek a minták példakódot biztosítanak az Azure Key Vault használata során gyakran előforduló további forgatókönyvekhez:

  • Sample1_HelloWorld.md – az Azure Key Vault való munkavégzéshez, beleértve a következőket:

    • Titkos kulcs létrehozása
    • Meglévő titkos kód lekérése
    • Meglévő titkos kód frissítése
    • Titkos kód törlése

  • Sample2_BackupAndRestore.md – az Azure Key Vault titkos kódrészleteit tartalmazza, beleértve a következőket:

    • Titkos kulcs biztonsági mentése és helyreállítása

  • Sample3_GetSecrets.md – példakód az Azure Key Vault titkos kódokkal való együttműködéshez, beleértve a következőket:

    • Titkos kulcsok létrehozása
    • Az összes titkos kód listázása a Key Vault
    • Titkos kulcsok frissítése a Key Vault
    • Megadott titkos kód verzióinak listázása
    • Titkos kódok törlése a Key Vault
    • Törölt titkos kódok listázása a Key Vault

További dokumentáció

Közreműködés

A kódtárak létrehozásával, tesztelésével és közreműködésével kapcsolatos részletekért tekintse meg a CONTRIBUTING.md.

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. További részletekért lásd: https://cla.microsoft.com.

A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes olyan tárházban, amely a CLA-t használja.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.

Megjelenések