Azure Key Vault Tanúsítvány ügyfélkódtár a .NET-hez – 4.5.1-es verzió

  • Cikk

Az Azure Key Vault egy felhőalapú szolgáltatás, amely biztonságos tárolást és a felhőalkalmazásokban használt tanúsítványok automatizált kezelését biztosítja. Az Azure Key Vault több tanúsítvány és ugyanazon tanúsítvány több verziója is megőrizhető. A tároló minden tanúsítványához tartozik egy szabályzat, amely szabályozza a tanúsítvány kiállítását és élettartamát, valamint a lejárat előtt végrehajtandó tanúsítványként végrehajtandó műveleteket.

Az Azure Key Vault-tanúsítványok ügyfélkódtára lehetővé teszi a tanúsítványok programozott kezelését, és metódusokat kínál a tanúsítványok, szabályzatok, kiállítók és névjegyek létrehozásához, frissítéséhez, listázásához és törléséhez. A kódtár támogatja a függőben lévő tanúsítványműveletek és a törölt tanúsítványok kezelését is.

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 az Azure Key Vault certificates ügyfélkódtárat a .NET-hez a NuGet használatával:

dotnet add package Azure.Security.KeyVault.Certificates

Előfeltételek

Ha az Azure CLI-t használja, cserélje le <your-resource-group-name> a és <your-key-vault-name> a nevet 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 CertificateClient osztály egy példányát. Szüksége van egy tároló URL-címére, amelyet "DNS-név" néven láthat a portálon, valamint hitelesítő adatokra egy ügyfélobjektum példányosításához.

Az alábbi példákban egy DefaultAzureCredential, a legtöbb forgatókönyvnek megfelelő , beleértve a helyi fejlesztési és éles környezeteket is. Emellett azt is 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 DefaultAzureCredential Azure SDK-hoz biztosított egyéb hitelesítőadat-szolgáltatók használatához először telepítenie kell az Azure.Identity csomagot:

dotnet add package Azure.Identity

CertificateClient létrehozása

Példányosítsa az a-t 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 hitelesíti őket.

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

Fő fogalmak

KeyVaultCertificate

Az A KeyVaultCertificate az Azure Key Vault alapvető erőforrása. A tanúsítványok használatával titkosíthatja és ellenőrizheti a titkosított vagy aláírt adatokat.

CertificateClient

CertificateClient A tárolóból tanúsítványokat szerezhet be, új tanúsítványokat és meglévő tanúsítványok új verzióit hozhat létre, frissítheti a tanúsítvány metaadatait, és törölheti a tanúsítványokat. A tanúsítványok tanúsítványkibocsátóit, névjegyeit és felügyeleti szabályzatait is kezelheti. Ezt az alábbi példák szemléltetik.

Menetbiztonság

Garantáljuk, hogy minden ügyfélpéldány-metódus szálbiztos és független egymástól (iránymutatás). 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.Certificates csomag támogatja a szinkron és aszinkron API-kat.

A következő szakasz a fent létrehozott kódrészleteket tartalmazzaclient, amelyek az Azure Key Vault tanúsítványszolgáltatással kapcsolatos leggyakoribb feladatokat ismertetik:

Példák szinkronizálása

Példák aszinkronizálásra

Tanúsítvány létrehozása

StartCreateCertificatelétrehoz egy tanúsítványt, amely az Azure Key Vault tárolandó. Ha már létezik azonos nevű tanúsítvány, akkor létrejön a tanúsítvány új verziója. A tanúsítvány létrehozásakor a felhasználó megadhatja a tanúsítvány élettartamát szabályozó szabályzatot. Ha nincs megadva szabályzat, a rendszer az alapértelmezett szabályzatot használja. A StartCreateCertificate művelet egy értéket CertificateOperationad vissza. Az alábbi példa létrehoz egy önaláírt tanúsítványt az alapértelmezett szabályzattal.

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

MEGJEGYZÉS: A tanúsítványkibocsátótól és az érvényesítési módszerektől függően a tanúsítvány létrehozása és aláírása határozatlan ideig tarthat. A felhasználók csak akkor várnak a tanúsítványműveletekre, ha a művelet ésszerűen elvégezhető az alkalmazás hatókörében, például önaláírt tanúsítványokkal vagy jól ismert válaszidővel rendelkező kiállítókkal.

Tanúsítvány lekérése

GetCertificateLekéri az Azure Key Vault tárolt tanúsítvány legújabb verzióját a hozzá CertificatePolicytartozóval együtt.

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

GetCertificateVersion lekéri a tanúsítvány egy adott verzióját a tárolóban.

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

Meglévő tanúsítvány frissítése

UpdateCertificatefrissíti az Azure Key Vault tárolt tanúsítványt.

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

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

Tanúsítványok listázása

GetCertificates számba adja a tárolóban lévő tanúsítványokat, és visszaadja a tanúsítvány kiválasztott tulajdonságait. A rendszer nem adja vissza a tanúsítvány bizalmas mezőit. Ehhez a művelethez a tanúsítványok/listák engedélyére van szükség.

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

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

Tanúsítvány törlése

DeleteCertificatetörli az Azure Key Vault tárolt tanúsítvány összes verziójá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 tanúsítványt. Ha a helyreállítható törlés engedélyezve van, a tanúsítvány törlésre van megjelölve, és igény szerint törölhető vagy helyreállítható az ütemezett végleges törlési dátumig.

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

Tanúsítvány létrehozása aszinkron módon

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

Ez a példa létrehoz egy tanúsítványt az Azure Key Vault a megadott választható argumentumokkal.

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

Tanúsítványok aszinkron listázása

A listatanúsítvány nem a metódusra GetPropertiesOfCertificatesAsync vár, hanem az utasítással await foreach használható értéket AsyncPageable<CertificateProperties> ad vissza:

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

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

Tanúsítvány aszinkron törlése

Ha aszinkron módon töröl egy tanúsítványt, mielőtt véglegesítené, megvárhatja a metódust WaitForCompletionAsync a műveletben. Alapértelmezés szerint ez a hurok határozatlan ideig működik, de egy parancs átadásával CancellationTokenmegszakíthatja azt.

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

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 tanúsítványok ügyfélkódtárával a .NET SDK-t használja, a szolgáltatás által visszaadott hibák megegyeznek a REST API-kérésekhez visszaadott HTTP-állapotkódokkal.

Ha például olyan kulcsot próbál lekérni, amely nem létezik az Azure Key Vault, a 404 rendszer hibát ad vissza, amely Not Foundazt jelzi, hogy .

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

Megfigyelheti, hogy a rendszer további információkat naplóz, például a művelet ügyfélkérési azonosítóját.

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

Következő lépések

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

  • Sample1_HelloWorld.md – Az Azure Key Vault-tanúsítványokkal való munkához, beleértve a következőket:

    • Tanúsítvány létrehozása
    • Meglévő tanúsítvány lekérése
    • Meglévő tanúsítvány frissítése
    • Tanúsítvány törlése

  • Sample2_GetCertificates.md – Példakód az Azure-Key Vault-tanúsítványok használatára, beleértve a következőket:

    • Tanúsítványok létrehozása
    • Az Key Vault összes tanúsítványának listázása
    • Adott tanúsítvány verzióinak listázása
    • Tanúsítványok törlése a Key Vault
    • Törölt tanúsítványok 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