Azure Key Vault-certifikatklientbibliotek för .NET – version 4.5.1

  • Artikel

Azure Key Vault är en molntjänst som tillhandahåller säker lagring och automatiserad hantering av certifikat som används i ett molnprogram. Flera certifikat och flera versioner av samma certifikat kan lagras i Azure Key Vault. Varje certifikat i valvet har en associerad princip som styr certifikatets utfärdande och livslängd, tillsammans med åtgärder som ska vidtas när certifikat snart upphör att gälla.

Klientbiblioteket för Azure Key Vault-certifikat gör det möjligt att programmatiskt hantera certifikat, erbjuda metoder för att skapa, uppdatera, lista och ta bort certifikat, principer, utfärdare och kontakter. Biblioteket stöder även hantering av väntande certifikatåtgärder och hantering av borttagna certifikat.

Källkod | Paket (NuGet) | API-referensdokumentation | Produktdokumentation | Prover | Migreringsguide

Komma igång

Installera paketet

Installera Klientbiblioteket för Azure Key Vault-certifikat för .NET med NuGet:

dotnet add package Azure.Security.KeyVault.Certificates

Krav

  • En Azure-prenumeration.
  • En befintlig Azure-Key Vault. Om du behöver skapa en Azure-Key Vault kan du använda Azure Portal eller Azure CLI.
  • Auktorisering till en befintlig Azure-Key Vault med antingen RBAC (rekommenderas) eller åtkomstkontroll.

Om du använder Azure CLI ersätter <your-resource-group-name> du och <your-key-vault-name> med dina egna unika namn:

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

Autentisera klienten

För att kunna interagera med Azure Key Vault-tjänsten måste du skapa en instans av klassen CertificateClient. Du behöver en valv-URL som du kan se som "DNS-namn" i portalen och autentiseringsuppgifter för att instansiera ett klientobjekt.

Exemplen som visas nedan använder en DefaultAzureCredential, som är lämplig för de flesta scenarier, inklusive lokala utvecklings- och produktionsmiljöer. Dessutom rekommenderar vi att du använder en hanterad identitet för autentisering i produktionsmiljöer. Du hittar mer information om olika sätt att autentisera och deras motsvarande typer av autentiseringsuppgifter i Azure Identity-dokumentationen .

Om du vill använda providern DefaultAzureCredential som visas nedan eller andra leverantörer av autentiseringsuppgifter som tillhandahålls med Azure SDK måste du först installera Azure.Identity-paketet:

dotnet add package Azure.Identity

Skapa CertificateClient

Instansiera en DefaultAzureCredential för att skicka till klienten. Samma instans av en tokenautentiseringsuppgift kan användas med flera klienter om de ska autentiseras med samma identitet.

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

Viktiga begrepp

KeyVaultCertificate

A KeyVaultCertificate är den grundläggande resursen i Azure Key Vault. Du använder certifikat för att kryptera och verifiera krypterade eller signerade data.

CertificateClient

Med en CertificateClient kan du hämta certifikat från valvet, skapa nya certifikat och nya versioner av befintliga certifikat, uppdatera certifikatmetadata och ta bort certifikat. Du kan också hantera certifikatutfärdare, kontakter och hanteringsprinciper för certifikat. Detta illustreras i exemplen nedan.

Trådsäkerhet

Vi garanterar att alla klientinstansmetoder är trådsäkra och oberoende av varandra (riktlinje). Detta säkerställer att rekommendationen att återanvända klientinstanser alltid är säker, även över trådar.

Ytterligare begrepp

Klientalternativ | Åtkomst till svaret | Långvariga åtgärder | Hantera fel | Diagnostik | Gäckande | Klientlivslängd

Exempel

Paketet Azure.Security.KeyVault.Certificates stöder synkrona och asynkrona API:er.

I följande avsnitt finns flera kodfragment med hjälp av ovanståendeclient, som omfattar några av de vanligaste azure-Key Vault certifikattjänstrelaterade uppgifterna:

Synkroniseringsexempel

Asynkrona exempel

Skapa ett certifikat

StartCreateCertificateskapar ett certifikat som ska lagras i Azure Key Vault. Om det redan finns ett certifikat med samma namn skapas en ny version av certifikatet. När du skapar certifikatet kan användaren ange den princip som styr certifikatets livslängd. Om ingen princip anges används standardprincipen. Åtgärden StartCreateCertificate returnerar en CertificateOperation. I följande exempel skapas ett självsignerat certifikat med standardprincipen.

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

Obs! Beroende på certifikatutfärdaren och valideringsmetoderna kan det ta en obestämd tid att skapa och signera certifikat. Användare bör bara vänta på certifikatåtgärder när åtgärden rimligen kan slutföras inom programmets omfång, till exempel med självsignerade certifikat eller utfärdare med välkända svarstider.

Hämta ett certifikat

GetCertificatehämtar den senaste versionen av ett certifikat som lagras i Azure Key Vault tillsammans med dess CertificatePolicy.

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

GetCertificateVersion hämtar en specifik version av ett certifikat i valvet.

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

Uppdatera ett befintligt certifikat

UpdateCertificateuppdaterar ett certifikat som lagras i Azure Key Vault.

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

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

Lista certifikat

GetCertificates räknar upp certifikaten i valvet och returnerar välj egenskaper för certifikatet. Känsliga fält i certifikatet returneras inte. Den här åtgärden kräver behörigheten certifikat/lista.

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

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

Ta bort ett certifikat

DeleteCertificatetar bort alla versioner av ett certifikat som lagras i Azure Key Vault. När mjuk borttagning inte är aktiverat för Azure Key Vault tar den här åtgärden bort certifikatet permanent. Om mjuk borttagning är aktiverat markeras certifikatet för borttagning och kan eventuellt rensas eller återställas fram till dess schemalagda rensningsdatum.

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

Skapa ett certifikat asynkront

De asynkrona API:erna är identiska med deras synkrona motsvarigheter, men returnerar med det typiska Suffixet "Async" för asynkrona metoder och returnerar ett Task.

Det här exemplet skapar ett certifikat i Azure Key Vault med de angivna valfria argumenten.

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

Lista certifikat asynkront

Listningscertifikatet förlitar sig inte på att vänta på GetPropertiesOfCertificatesAsync metoden, men returnerar ett AsyncPageable<CertificateProperties> som du kan använda med -instruktionen await foreach :

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

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

Ta bort ett certifikat asynkront

När du tar bort ett certifikat asynkront innan du rensar det kan du vänta på WaitForCompletionAsync -metoden för åtgärden. Som standard loopar den här loopen på obestämd tid, men du kan avbryta den genom att skicka en CancellationToken.

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

Felsökning

Mer information om hur du diagnostiserar olika felscenarier finns i vår felsökningsguide .

Allmänt

När du interagerar med Klientbiblioteket för Azure Key Vault-certifikat med hjälp av .NET SDK motsvarar fel som returneras av tjänsten samma HTTP-statuskoder som returneras för REST API-begäranden.

Om du till exempel försöker hämta en nyckel som inte finns i azure-Key Vault returneras ett 404 fel som anger Not Found.

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

Du kommer att märka att ytterligare information loggas, till exempel ID för klientbegäran för åtgärden.

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

Nästa steg

Det finns flera klientbiblioteksexempel för Azure Key Vault certifikat på den här GitHub-lagringsplatsen. De här exemplen innehåller exempelkod för ytterligare scenarier som ofta påträffas när du arbetar med Azure Key Vault:

  • Sample1_HelloWorld.md – för att arbeta med Azure Key Vault-certifikat, inklusive:

    • Skapa ett certifikat
    • Hämta ett befintligt certifikat
    • Uppdatera ett befintligt certifikat
    • Ta bort ett certifikat

  • Sample2_GetCertificates.md – Exempelkod för att arbeta med Azure Key Vault-certifikat, inklusive:

    • Skapa certifikat
    • Visa en lista över alla certifikat i Key Vault
    • Lista versioner av ett angivet certifikat
    • Ta bort certifikat från Key Vault
    • Lista borttagna certifikat i Key Vault

Ytterligare dokumentation

Bidra

Mer information om hur du skapar, testar och bidrar till dessa bibliotek finns i CONTRIBUTING.md .

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekod eller kontakt opencode@microsoft.com med ytterligare frågor eller kommentarer.

Visningar