Aracılığıyla paylaş

Kimlik doğrulaması, istekler ve yanıtlar

Azure Key Vault, bulut uygulamalarınız için gizli dizileri depolamak ve yönetmek için iki tür kapsayıcı sağlar:

Konteyner türü Desteklenen nesne türleri Veri düzlemi uç noktası
Kasalar
  • Yazılım korumalı anahtarlar
  • HSM korumalı anahtarlar (Premium SKU ile)
  • Sertifikalar
  • Depolama hesabı anahtarları
 https://{vault-name}.vault.azure.net
Yönetilen HSM
  • HSM ile korunan anahtarlar
 https://{hsm-name}.managedhsm.azure.net

Her nesne türüne erişmek için kullanılan URL'lerin son ekleri aşağıdadır

Nesne türü URL uzantısı
Yazılım korumalı anahtarlar /Anahtarlar
HSM ile korunan anahtarlar /Anahtarlar
Sırlar /sirlar
Sertifikalar /Sertifika
Depolama hesabı anahtarları /storageaccounts

Azure Key Vault, JSON biçimli istekleri ve yanıtları destekler. Azure Key Vault istekleri, bazı URL parametreleri ve JSON kodlanmış istek ve yanıt gövdeleriyle HTTPS kullanılarak geçerli bir Azure Key Vault URL'sine yönlendirilir.

Bu makale, Azure Key Vault hizmetine ilişkin ayrıntıları kapsar. Kimlik doğrulaması/yetkilendirme ve erişim belirteci alma gibi Azure REST arabirimlerini kullanma hakkında genel bilgi için bkz. Azure REST API Başvurusu.

İstek URL'si yapısı

Anahtar yönetimi işlemleri DELETE, GET, PATCH ve PUT gibi HTTP fiillerini kullanır. Mevcut anahtar nesnelerinde şifreleme işlemleri HTTP POST kullanır.

Azure Key Vault, belirli HTTP fiillerini destekleyemeyen istemciler için, hedeflenen fiili belirtmek için üst bilgiyle HTTP X-HTTP-REQUEST POST'un kullanılmasına izin verir. POST yerine kullanılırken (örneğin, DELETE yerine), normalde gerekli olmayan istekler için boş bir gövde ekleyin.

Azure Key Vault'taki nesnelerle çalışmak için örnek URL'ler şunlardır:

  • Key Vault'ta TESTKEY adlı bir anahtar oluşturmak için - PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

  • IMPORTEDKEY adlı bir anahtarı Key Vault'a aktarmak için - POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

  • Key Vault'ta MYSECRET adlı bir gizliye erişmek için - GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

  • Key Vault'ta TESTKEY adlı bir anahtar kullanarak özet imzalamak için - POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

  • Key Vault'a yapılan bir isteğin yetkilendirilmesi her zaman aşağıdaki gibidir:

    • Kasalar için: https://{keyvault-name}.vault.azure.net/
    • Yönetilen HSM'ler için: https://{HSM-name}.managedhsm.azure.net/ Anahtarlar her zaman /keys yolu altında, Gizli Diziler ise her zaman /secrets yolu altında depolanır.

Desteklenen API sürümleri

Azure Key Vault Hizmeti, alt düzey istemcilerle uyumluluk sağlamak için protokol sürümü oluşturmayı destekler, ancak tüm özellikler bu istemciler tarafından kullanılamaz. İstemciler, varsayılan olmadığı için destekledikleri protokolün sürümünü belirtmek için sorgu dizesi parametresini kullanmalıdır api-version .

Azure Key Vault protokol sürümleri, {YYYY}.{MM}.{DD} biçimini kullanan bir tarih numaralandırma düzenini takip eder.

Talep gövdesi gereksinimleri

HTTP belirtimine göre GET işlemlerinin bir istek gövdesi OLMAMALI, POST ve PUT işlemlerinin ise bir istek gövdesi OLMALIDIR. DELETE işlemlerindeki gövde HTTP'de isteğe bağlıdır.

İşlem açıklamasında aksi belirtilmedikçe, istek gövdesi içerik türü application/json olmalı ve içerik türüne uygun serileştirilmiş bir JSON nesnesi içermelidir.

İşlem açıklamasında aksi belirtilmedikçe Accept isteği üst bilgisi application/json medya türünü içermelidir.

Yanıt gövdesi biçimi

İşlem açıklamasında aksi belirtilmedikçe, hem başarılı hem de başarısız işlemlerin yanıt gövdesi içerik türü application/json'dır ve ayrıntılı hata bilgileri içerir.

Alternatif olarak HTTP POST kullanma

Bazı istemciler PATCH veya DELETE gibi belirli HTTP fiillerini kullanamayabilir. Azure Key Vault, istemci özgün HTTP fiiline yönelik "X-HTTP-METHOD" üst bilgisini de içeriyorsa, bu istemciler için alternatif olarak HTTP POST'yi destekler. Bu belgede tanımlanan api'lerden her biri için HTTP POST desteğine dikkat edilir.

Hata yanıtlarını işleme

Hata işleme HTTP durum kodlarını kullanır. Tipik sonuçlar şunlardır:

  • 2xx – Başarı: Normal işlem için kullanılır. Yanıt gövdesi beklenen sonucu içerir

  • 3xx – Yeniden Yönlendirme: Koşullu bir GET isteğini karşılamak için 304 "Değiştirilmedi" döndürülebilir. Gelecekte DNS ve yol değişikliklerini göstermek için diğer 3xx kodları kullanılabilir.

  • 4xx – İstemci Hatası: Hatalı istekler, eksik anahtarlar, söz dizimi hataları, geçersiz parametreler, kimlik doğrulama hataları vb. için kullanılır. Yanıt gövdesi ayrıntılı hata açıklaması içeriyor.

  • 5xx – Sunucu Hatası: İç sunucu hataları için kullanılır. Yanıt gövdesi özetlenmiş hata bilgilerini içerir.

    Sistem, bir ara sunucu veya güvenlik duvarının arkasında çalışacak şekilde tasarlanmıştır. Bu nedenle, bir istemci başka hata kodları alabilir.

    Azure Key Vault, bir sorun oluştuğunda yanıt gövdesinde hata bilgilerini de döndürür. Yanıt gövdesi JSON biçimindedir ve şu biçimi alır:


{  
  "error":  
  {  
    "code": "BadArgument",  
    "message":  

      "’Foo’ is not a valid argument for ‘type’."  
    }  
  }  
}

Kimlik doğrulama gereksinimleri

Azure Key Vault'a yönelik tüm isteklerin kimliği doğrulanmalıdır. Azure Key Vault, OAuth2 [RFC6749] kullanılarak edinilebilen Microsoft Entra erişim belirteçlerini destekler.

Uygulamanızı kaydetme ve Azure Key Vault'u kullanmak için kimlik doğrulaması yapma hakkında daha fazla bilgi için bkz. İstemci uygulamanızı Microsoft Entra Id ile kaydetme.

Erişim belirteçleri HTTP Yetkilendirme üst bilgisi kullanılarak hizmete gönderilmelidir:

PUT /keys/MYKEY?api-version=<api_version>  HTTP/1.1  
Authorization: Bearer <access_token>

Erişim belirteci sağlanmadığında veya hizmet bir belirteci kabul etmediğinde, istemciye bir HTTP 401 hatası döndürülür ve WWW-Authenticate üst bilgisini içerir, örneğin:

401 Not Authorized  
WWW-Authenticate: Bearer authorization="…", resource="…"

WWW-Authenticate üst bilgisindeki parametreler şunlardır:

  • yetkilendirme: İstek için erişim belirteci almak için kullanılabilecek OAuth2 yetkilendirme hizmetinin adresi.

  • resource: Yetkilendirme isteğinde kullanılacak kaynağın adı (https://vault.azure.net).

Uyarı

Key Vault'a yapılan ilk çağrıda gizli diziler, sertifikalar ve anahtarlar için Key Vault SDK istemcileri, kiracı bilgilerini elde etmek üzere bir erişim belirteci sağlamaz. Key Vault SDK istemcisi kullanıldığında HTTP 401 yanıtının alınması bekleniyor ve Key Vault, uygulamaya belirtecin alınması gereken kaynağı ve kiracıyı içeren WWW-Authenticate üst bilgisini sağlar. Her şey doğru yapılandırıldıysa uygulamadan gelen ikinci Key Vault çağrısı geçerli bir belirteç içerir ve başarılı olur.

  • Last updated on