Delen via

Azure Key Vault Certificate-clientbibliotheek voor .NET - versie 4.5.1

  • Artikel

Azure Key Vault is een cloudservice die veilige opslag en geautomatiseerd beheer van certificaten biedt die in een cloudtoepassing worden gebruikt. Meerdere certificaten en meerdere versies van hetzelfde certificaat kunnen worden bewaard in de Azure Key Vault. Aan elk certificaat in de kluis is een beleid gekoppeld dat de uitgifte en levensduur van het certificaat bepaalt, samen met acties die moeten worden uitgevoerd als certificaten bijna zijn verlopen.

De clientbibliotheek voor Azure Key Vault certificaten maakt het programmatisch beheer van certificaten mogelijk en biedt methoden voor het maken, bijwerken, weergeven en verwijderen van certificaten, beleid, verleners en contactpersonen. De bibliotheek biedt ook ondersteuning voor het beheren van in behandeling zijnde certificaatbewerkingen en het beheer van verwijderde certificaten.

Broncode | Pakket (NuGet) | API-referentiedocumentatie | Productdocumentatie | Monsters | Migratiehandleiding

Aan de slag

Het pakket installeren

Installeer de clientbibliotheek voor Azure Key Vault certificaten voor .NET met NuGet:

dotnet add package Azure.Security.KeyVault.Certificates

Vereisten

  • Een Azure-abonnement.
  • Een bestaande Azure-Key Vault. Als u een Azure-Key Vault wilt maken, kunt u Azure Portal of Azure CLI gebruiken.
  • Autorisatie voor een bestaande Azure-Key Vault met behulp van RBAC (aanbevolen) of toegangsbeheer.

Als u de Azure CLI gebruikt, vervangt u en <your-key-vault-name> door <your-resource-group-name> uw eigen, unieke namen:

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

De client verifiëren

Als u wilt communiceren met de Azure Key Vault-service, moet u een exemplaar van de klasse CertificateClient maken. U hebt een kluis-URL nodig, die u mogelijk ziet als 'DNS-naam' in de portal, en referenties om een clientobject te instantiëren.

In de onderstaande voorbeelden wordt een DefaultAzureCredentialgebruikt, die geschikt is voor de meeste scenario's, waaronder lokale ontwikkel- en productieomgevingen. Daarnaast raden we u aan een beheerde identiteit te gebruiken voor verificatie in productieomgevingen. Meer informatie over verschillende manieren om te verifiëren en de bijbehorende referentietypen vindt u in de Documentatie voor Azure Identity .

Als u de DefaultAzureCredential onderstaande provider of andere referentieproviders wilt gebruiken die bij de Azure SDK worden geleverd, moet u eerst het pakket Azure.Identity installeren:

dotnet add package Azure.Identity

CertificateClient maken

Instantieer een DefaultAzureCredential om door te geven aan de client. Hetzelfde exemplaar van een tokenreferentie kan worden gebruikt met meerdere clients als ze verifiëren met dezelfde identiteit.

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

Belangrijkste concepten

KeyVaultCertificate

Een KeyVaultCertificate is de fundamentele resource binnen Azure Key Vault. U gebruikt certificaten om versleutelde of ondertekende gegevens te versleutelen en te verifiëren.

CertificateClient

Met een CertificateClient kunt u certificaten ophalen uit de kluis, nieuwe certificaten en nieuwe versies van bestaande certificaten maken, metagegevens van certificaten bijwerken en certificaten verwijderen. U kunt ook certificaatverleners, contactpersonen en het beheerbeleid van certificaten beheren. Dit wordt geïllustreerd in de onderstaande voorbeelden.

Veiligheid van schroefdraad

We garanderen dat alle clientexemplaren veilig zijn en onafhankelijk van elkaar zijn (richtlijn). Dit zorgt ervoor dat de aanbeveling om clientexemplaren opnieuw te gebruiken altijd veilig is, zelfs voor alle threads.

Aanvullende concepten

Clientopties | Toegang tot het antwoord | Langlopende bewerkingen | Fouten | afhandelen Diagnostics | Spottende | Clientlevensduur

Voorbeelden

Het pakket Azure.Security.KeyVault.Certificates ondersteunt synchrone en asynchrone API's.

De volgende sectie bevat verschillende codefragmenten met behulp van de clienthierboven gemaakte code voor enkele van de meest voorkomende taken met betrekking tot azure Key Vault certificate service:

Voorbeelden van synchronisatie

Asynchrone voorbeelden

Een certificaat maken

StartCreateCertificatemaakt een certificaat dat moet worden opgeslagen in de Azure Key Vault. Als er al een certificaat met dezelfde naam bestaat, wordt er een nieuwe versie van het certificaat gemaakt. Bij het maken van het certificaat kan de gebruiker het beleid opgeven dat de levensduur van het certificaat bepaalt. Als er geen beleid is opgegeven, wordt het standaardbeleid gebruikt. De StartCreateCertificate bewerking retourneert een CertificateOperation. In het volgende voorbeeld wordt een zelfondertekend certificaat gemaakt met het standaardbeleid.

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

OPMERKING: Afhankelijk van de certificaatverlener en validatiemethoden kan het maken en ondertekenen van certificaten een onbepaalde tijd duren. Gebruikers moeten alleen wachten op certificaatbewerkingen wanneer de bewerking redelijkerwijs kan worden voltooid binnen het bereik van de toepassing, zoals met zelfondertekende certificaten of verleners met bekende reactietijden.

Een certificaat ophalen

GetCertificatehaalt de nieuwste versie van een certificaat op dat is opgeslagen in de Azure Key Vault samen met de bijbehorende CertificatePolicy.

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

GetCertificateVersion haalt een specifieke versie van een certificaat in de kluis op.

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

Een bestaand certificaat bijwerken

UpdateCertificatewerkt een certificaat bij dat is opgeslagen in de Azure Key Vault.

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

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

Certificaten vermelden

GetCertificates inventariseert de certificaten in de kluis en retourneert geselecteerde eigenschappen van het certificaat. Gevoelige velden van het certificaat worden niet geretourneerd. Voor deze bewerking is de machtiging certificaten/lijst vereist.

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

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

Een certificaat verwijderen

DeleteCertificateverwijdert alle versies van een certificaat die zijn opgeslagen in de Azure Key Vault. Wanneer voorlopig verwijderen niet is ingeschakeld voor de Azure Key Vault, wordt het certificaat definitief verwijderd met deze bewerking. Als voorlopig verwijderen is ingeschakeld, wordt het certificaat gemarkeerd voor verwijdering en kan het desgewenst worden opgeschoond of hersteld tot de geplande opschoondatum.

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

Een certificaat asynchroon maken

De asynchrone API's zijn identiek aan hun synchrone tegenhangers, maar worden geretourneerd met het typische Asynchrone achtervoegsel voor asynchrone methoden en retourneren een Task.

In dit voorbeeld wordt een certificaat gemaakt in de Azure Key Vault met de opgegeven optionele 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();

Certificaten asynchroon weergeven

Het weergeven van het certificaat is niet afhankelijk van het wachten op de GetPropertiesOfCertificatesAsync methode, maar retourneert een AsyncPageable<CertificateProperties> die u kunt gebruiken met de await foreach -instructie:

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

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

Een certificaat asynchroon verwijderen

Wanneer u een certificaat asynchroon verwijdert voordat u het opschoont, kunt u wachten op de WaitForCompletionAsync methode voor de bewerking. Deze wordt standaard voor onbepaalde tijd herhaald, maar u kunt deze annuleren door een CancellationTokendoor te geven.

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

Problemen oplossen

Zie onze gids voor probleemoplossing voor meer informatie over het diagnosticeren van verschillende foutscenario's.

Algemeen

Wanneer u communiceert met de clientbibliotheek voor Azure Key Vault certificaten met behulp van de .NET SDK, komen fouten die door de service worden geretourneerd, overeen met dezelfde HTTP-statuscodes die zijn geretourneerd voor REST API-aanvragen.

Als u bijvoorbeeld een sleutel probeert op te halen die niet bestaat in uw Azure Key Vault, wordt er een 404 fout geretourneerd die aangeeftNot Found.

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

U ziet dat aanvullende informatie wordt geregistreerd, zoals de clientaanvraag-id van de bewerking.

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

Volgende stappen

In deze GitHub-opslagplaats zijn verschillende voorbeelden van clientbibliotheek voor Azure Key Vault certificaten voor u beschikbaar. Deze voorbeelden bevatten voorbeeldcode voor aanvullende scenario's die vaak voorkomen tijdens het werken met Azure Key Vault:

  • Sample1_HelloWorld.md : voor het werken met Azure Key Vault-certificaten, waaronder:

    • Een certificaat maken
    • Een bestaand certificaat ophalen
    • Een bestaand certificaat bijwerken
    • Een certificaat verwijderen

  • Sample2_GetCertificates.md - Voorbeeldcode voor het werken met Azure Key Vault-certificaten, waaronder:

    • Certificaten maken
    • Alle certificaten in de Key Vault weergeven
    • Versies van een opgegeven certificaat weergeven
    • Certificaten verwijderen uit de Key Vault
    • Verwijderde certificaten weergeven in de Key Vault

Aanvullende documentatie

Bijdragen

Zie de CONTRIBUTING.md voor meer informatie over het bouwen, testen en bijdragen aan deze bibliotheken.

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie de Veelgestelde vragen over de gedragscode voor meer informatie of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.

Weergaven