.NET için Azure Key Vault gizli istemci kitaplığı - sürüm 4.5.0
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
- Bir Azure aboneliği.
- Mevcut bir Azure Key Vault. Azure Key Vault oluşturmanız gerekiyorsa Azure Portal'ı veya Azure CLI'yı kullanabilirsiniz.
- RBAC (önerilir) veya erişim denetimi kullanarak mevcut bir Azure Key Vault yetkilendirme.
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 DefaultAzureCredential
kullanı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
- Gizli anahtar oluşturma
- Gizli dizi alma
- Mevcut gizli diziyi güncelleştirme
- Gizli anahtarı silme
- Gizli diziyi silme ve temizleme
- Gizli Dizileri Listele
Zaman uyumsuz örnekler
- Zaman uyumsuz olarak gizli dizi oluşturma
- Gizli dizileri zaman uyumsuz olarak listeleme
- Gizli diziyi zaman uyumsuz olarak silme
Gizli anahtar oluşturma
SetSecret
Azure 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
GetSecret
daha ö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
UpdateSecretProperties
daha ö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
StartDeleteSecret
daha ö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 Task
dö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 CancellationToken
geç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 Found
bir 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
- Azure Key Vault hakkında daha kapsamlı belgeler için API başvuru belgelerine bakın.
- Anahtarlar istemci kitaplığı için bkz . Anahtarlar istemci kitaplığı.
- Sertifikalar istemci kitaplığı için bkz. Sertifikalar istemci kitaplığı.
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 .
Azure SDK for .NET