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

  • Makale

Azure Key Vault, parolalar ve veritabanı bağlantı dizeleri gibi gizli dizilerin güvenli bir şekilde depolanmasını sağlayan bir bulut hizmetidir.

Azure Key Vault gizli dizileri istemci kitaplığı belirteçlere, parolalara, API anahtarlarına ve diğer gizli dizilere erişimi güvenli bir şekilde depolamanıza ve denetlemenize olanak tanır. Bu kitaplık, gizli dizileri ve sürümlerini oluşturma, alma, güncelleştirme, silme, temizleme, yedekleme, geri yükleme ve listeleme işlemleri sunar.

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 gizli dizileri istemci kitaplığını yükleyin:

dotnet add package Azure.Security.KeyVault.Secrets

Önkoş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 SecretClient 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

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

Önemli kavramlar

KeyVaultSecret

AKeyVaultSecret, Azure Key Vault içindeki temel kaynaktır. Geliştirici açısından bakıldığında Azure Key Vault API'leri gizli dizi değerlerini dize olarak kabul eder ve döndürür.

SecretClient

A, SecretClient SDK'da hem zaman uyumlu hem de zaman uyumsuz işlemler sağlayarak bir uygulamanın kullanım örneğine göre bir istemcinin seçilmesini sağlar. bir SecretClient'i başlatdıktan sonra Azure Key Vault'da gizli dizilerle etkileşim kurabilirsiniz.

İş 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.Secrets paketi zaman uyumlu ve zaman uyumsuz API'leri destekler.

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

Eşitleme örnekleri

Zaman uyumsuz örnekler

Gizli anahtar oluşturma

SetSecretAzure Key Vault depolanacak bir KeyVaultSecret oluşturur. Aynı ada sahip bir gizli dizi zaten varsa, gizli dizinin yeni bir sürümü oluşturulur.

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

Gizli dizi alma

GetSecretdaha önce Azure Key Vault depolanan bir gizli diziyi alır.

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

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

Mevcut gizli diziyi güncelleştirme

UpdateSecretPropertiesdaha önce Azure Key Vault depolanan bir gizli diziyi güncelleştirir. Yalnızca gizli dizinin öznitelikleri güncelleştirilir. Değeri güncelleştirmek için aynı ada sahip bir gizli diziyi çağırın SecretClient.SetSecret .

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

Gizli anahtarı silme

StartDeleteSecretdaha önce Azure Key Vault depolanan bir gizli diziyi silmek için uzun süre çalışan bir işlem başlatır. İşlemin tamamlanmasını beklemeden gizli diziyi hemen alabilirsiniz. Azure Key Vault için geçici silme etkinleştirilmediğinde, bu işlem gizli diziyi kalıcı olarak siler.

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

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

Gizli diziyi silme ve temizleme

Gizli diziyi temizlemeye veya kurtarmaya çalışmadan önce uzun süre çalışan işlemin tamamlanmasını beklemeniz gerekir. Bunu, aşağıda gösterildiği gibi döngü içinde çağırarak UpdateStatus yapabilirsiniz:

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

Gizli dizileri listeleme

Bu örnekte, belirtilen Azure Key Vault içindeki tüm gizli diziler listelenir. Tüm gizli diziler listelenirken değer döndürülmüyor. Değeri almak için çağrısı SecretClient.GetSecret yapmanız gerekir.

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

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

Zaman uyumsuz olarak gizli dizi 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 gizli dizi oluşturur.

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

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

Gizli dizileri zaman uyumsuz olarak listeleme

Gizli dizilerin listelenmesi yöntemin beklenmesine GetPropertiesOfSecretsAsync dayanmaz, ancak deyimiyle await foreach kullanabileceğiniz bir AsyncPageable<SecretProperties> döndürür:

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

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

Gizli diziyi zaman uyumsuz olarak silme

Temizlemeden önce bir gizli diziyi 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.

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

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 gizli istemci kitaplığıyla etkileşimde bulunursanız, 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 gizli diziyi almaya çalışırsanız değerini belirten Not Foundbir 404 hata döndürülür.

try
{
    KeyVaultSecret secret = client.GetSecret("some_secret");
}
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":"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

Sonraki adımlar

Bu GitHub deposunda çeşitli Azure Key Vault gizli dizileri 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 ile çalışmak için:

    • Gizli anahtar oluşturma
    • Mevcut bir gizli diziyi alma
    • Mevcut gizli diziyi güncelleştirme
    • Gizli diziyi silme

  • Sample2_BackupAndRestore.md - Azure Key Vault gizli dizileriyle çalışan kod parçacıklarını içerir; örneğin:

    • Gizli diziyi yedekleme ve kurtarma

  • Sample3_GetSecrets.md - Azure Key Vault gizli dizileriyle çalışmaya yönelik örnek kod:

    • Gizli dizi oluşturma
    • Key Vault içindeki tüm gizli dizileri listeleme
    • Key Vault gizli dizileri güncelleştirme
    • Belirtilen gizli dizinin sürümlerini listeleme
    • gizli dizileri Key Vault silme
    • Key Vault silinen gizli dizileri listeleme

Diğer Belgeler

Katkıda bulunma

Bu kitaplıkları oluşturma, test etme ve bunlara 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 veya yorumlarla iletişime geçin opencode@microsoft.com .

İzlenimler