.NET için Azure Key Vault Sertifikası istemci kitaplığı - sürüm 4.5.1

  • Makale

Azure Key Vault, bir bulut uygulaması genelinde kullanılan sertifikaların güvenli bir şekilde depolanmasını ve otomatik olarak yönetilmesini sağlayan bir bulut hizmetidir. Birden çok sertifika ve aynı sertifikanın birden çok sürümü Azure Key Vault tutulabilir. Kasadaki her sertifika, sertifikanın verilmesini ve kullanım ömrünü denetleyen ve süresi dolmak üzere olan sertifikalar olarak gerçekleştirilecek eylemlerle ilişkili bir ilkeye sahiptir.

Azure Key Vault sertifikaları istemci kitaplığı sertifikaları program aracılığıyla yönetmeye olanak tanır ve sertifikaları, ilkeleri, verenleri ve kişileri oluşturma, güncelleştirme, listeleme ve silme yöntemleri sunar. Kitaplık ayrıca bekleyen sertifika işlemlerini yönetmeyi ve silinen sertifikaların yönetimini de destekler.

Kaynak kodu | Paket (NuGet) | API başvuru belgeleri | Ürün belgeleri | Örnekleri | Geçiş kılavuzu

Başlarken

Paketi yükleme

NuGet ile .NET için Azure Key Vault sertifikaları istemci kitaplığını yükleyin:

dotnet add package Azure.Security.KeyVault.Certificates

Ön koşullar

Azure CLI kullanıyorsanız ve <your-key-vault-name> yerine kendi benzersiz adlarınızı yazın<your-resource-group-name>:

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

İstemcinin kimliğini doğrulama

Azure Key Vault hizmetiyle etkileşim kurmak için CertificateClient sınıfının bir örneğini oluşturmanız gerekir. Portalda "DNS Adı" olarak görebileceğiniz bir kasa url'sine ve istemci nesnesinin örneğini oluşturmak için kimlik bilgilerine ihtiyacınız vardır.

Aşağıda gösterilen örneklerde, yerel geliştirme ve üretim ortamları dahil olmak üzere çoğu senaryo için uygun olan bir DefaultAzureCredentialkullanılır. Ayrıca, üretim ortamlarında kimlik doğrulaması için yönetilen kimlik kullanmanızı öneririz. Kimlik doğrulamanın farklı yolları ve bunların ilgili kimlik bilgileri türleri hakkında daha fazla bilgiyi Azure Kimliği belgelerinde bulabilirsiniz.

Aşağıda gösterilen sağlayıcıyı DefaultAzureCredential veya Azure SDK ile sağlanan diğer kimlik bilgileri sağlayıcılarını kullanmak için önce Azure.Identity paketini yüklemeniz gerekir:

dotnet add package Azure.Identity

CertificateClient Oluşturma

İstemciye geçirmek için örneği DefaultAzureCredential oluşturun. Aynı kimlikle kimlik doğrulaması yapacaklarsa, belirteç kimlik bilgilerinin aynı örneği birden çok istemciyle kullanılabilir.

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

Önemli kavramlar

KeyVaultCertificate

AKeyVaultCertificate, Azure Key Vault içindeki temel kaynaktır. Şifrelenmiş veya imzalı verileri şifrelemek ve doğrulamak için sertifikaları kullanacaksınız.

CertificateClient

ile CertificateClient kasadan sertifika alabilir, yeni sertifikalar ve mevcut sertifikaların yeni sürümlerini oluşturabilir, sertifika meta verilerini güncelleştirebilir ve sertifikaları silebilirsiniz. Sertifikaların sertifika verenlerini, kişilerini ve yönetim ilkelerini de yönetebilirsiniz. Bu, aşağıdaki örneklerde gösterilmiştir.

İş parçacığı güvenliği

Tüm istemci örneği yöntemlerinin iş parçacığı açısından güvenli ve birbirinden bağımsız olduğunu garanti ediyoruz (kılavuz). Bu, istemci örneklerini yeniden kullanma önerisinin iş parçacıkları arasında bile her zaman güvenli olmasını sağlar.

Ek kavramlar

İstemci seçenekleri | Yanıta | erişme Uzun süre çalışan işlemler | Hataları | işleme Tanılama | Alaycı | İstemci ömrü

Örnekler

Azure.Security.KeyVault.Certificates paketi zaman uyumlu ve zaman uyumsuz API'leri destekler.

Aşağıdaki bölümde, yukarıda oluşturulan kullanılarak azure Key Vault sertifika hizmetiyle ilgili en yaygın görevlerden bazılarını kapsayan birkaç kod parçacığı client verilmiştir:

Eşitleme örnekleri

Zaman uyumsuz örnekler

Sertifika oluşturma

StartCreateCertificateAzure Key Vault depolanacak bir sertifika oluşturur. Aynı ada sahip bir sertifika zaten varsa, sertifikanın yeni bir sürümü oluşturulur. Sertifikayı oluştururken kullanıcı, sertifika ömrünü denetleyen ilkeyi belirtebilir. İlke belirtilmezse varsayılan ilke kullanılır. İşlem StartCreateCertificate bir CertificateOperationdöndürür. Aşağıdaki örnek, varsayılan ilkeyle otomatik olarak imzalanan bir sertifika oluşturur.

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

NOT: Sertifikayı verene ve doğrulama yöntemlerine bağlı olarak, sertifika oluşturma ve imzalama işlemi belirsiz bir süre alabilir. Kullanıcılar yalnızca otomatik olarak imzalanan sertifikalar veya iyi bilinen yanıt süreleri olan verenler gibi uygulama kapsamında işlem makul bir şekilde tamamlanabilirse sertifika işlemlerini beklemelidir.

Sertifika alma

GetCertificate, Azure Key Vault'nde depolanan bir sertifikanın en son sürümünü ile birlikte CertificatePolicyalır.

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

GetCertificateVersion kasadaki bir sertifikanın belirli bir sürümünü alır.

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

Var olan bir sertifikayı güncelleştirme

UpdateCertificateAzure Key Vault depolanan bir sertifikayı güncelleştirir.

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

KeyVaultCertificate updated = client.UpdateCertificateProperties(certificateProperties);

Sertifikaları listeleme

GetCertificates kasadaki sertifikaları numaralandırır ve sertifikanın seçme özelliklerini döndürür. Sertifikanın hassas alanları döndürülmeyecek. Bu işlem sertifikalar/liste izni gerektirir.

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

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

Sertifika silme

DeleteCertificateAzure Key Vault depolanan bir sertifikanın tüm sürümlerini siler. Azure Key Vault için geçici silme etkinleştirilmediğinde, bu işlem sertifikayı kalıcı olarak siler. Geçici silme etkinleştirildiyse sertifika silinmek üzere işaretlenir ve isteğe bağlı olarak temizlenebilir veya zamanlanan temizleme tarihine kadar kurtarılabilir.

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

Zaman uyumsuz olarak sertifika oluşturma

Zaman uyumsuz API'ler zaman uyumlu karşılıklarıyla aynıdır, ancak zaman uyumsuz yöntemler için tipik "Zaman Uyumsuz" soneki ile geri döner ve bir Taskdöndürür.

Bu örnek, Azure Key Vault belirtilen isteğe bağlı bağımsız değişkenlerle bir sertifika oluşturur.

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

Sertifikaları zaman uyumsuz olarak listeleme

Listeleme sertifikası yöntemini beklemeye GetPropertiesOfCertificatesAsync dayanmaz, ancak deyimiyle await foreach kullanabileceğiniz bir AsyncPageable<CertificateProperties> döndürür:

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

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

Sertifikayı zaman uyumsuz olarak silme

Bir sertifikayı temizlemeden önce zaman uyumsuz olarak silerken, işlemde WaitForCompletionAsync yöntemini bekleyebilirsiniz. Varsayılan olarak, bu döngü süresiz olarak döngüye geçer, ancak bir CancellationTokengeçirerek iptal edebilirsiniz.

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

Sorun giderme

Çeşitli hata senaryolarını tanılama hakkında ayrıntılı bilgi için sorun giderme kılavuzumuza bakın.

Genel

.NET SDK'sını kullanarak Azure Key Vault sertifikaları istemci kitaplığıyla etkileşime geçtiğinde, hizmet tarafından döndürülen hatalar REST API istekleri için döndürülen http durum kodlarıyla aynı olur.

Örneğin, Azure Key Vault'nizde mevcut olmayan bir Anahtarı almaya çalışırsanız, belirten Not Foundbir 404 hata döndürülür.

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

İşlemin İstemci İstek Kimliği gibi ek bilgilerin günlüğe kaydedildiğini fark edeceksiniz.

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

Sonraki adımlar

Bu GitHub deposunda çeşitli Azure Key Vault sertifikaları istemci kitaplığı örnekleri sağlanır. Bu örnekler, Azure Key Vault çalışırken yaygın olarak karşılaşılan ek senaryolar için örnek kod sağlar:

  • Sample1_HelloWorld.md - Azure Key Vault sertifikaları ile çalışmak için:

    • Sertifika oluşturma
    • Var olan bir sertifikayı alma
    • Var olan bir sertifikayı güncelleştirme
    • Sertifika silme

  • Sample2_GetCertificates.md - Azure Key Vault sertifikalarıyla çalışmaya yönelik örnek kod:

    • Sertifika oluşturma
    • Key Vault tüm sertifikaları listeleme
    • Belirtilen sertifikanın sürümlerini listeleme
    • sertifikaları Key Vault silme
    • Key Vault silinen sertifikaları listeleme

Diğer Belgeler

Katkıda bulunma

Bu kitaplıkları oluşturma, test etme ve bu kitaplıklara katkıda bulunma hakkında ayrıntılı bilgi için CONTRIBUTING.md bakın.

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorularınız veya yorumlarınızla iletişime geçin opencode@microsoft.com .

İzlenimler