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

Azure Key Vault JSON biçimli istekleri ve yanıtları destekler. Azure Key Vault yönelik istekler, 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.

Belirli HTTP fiillerini destekleyemeyen istemciler için, Azure Key Vault hedeflenen fiili belirtmek için X-HTTP-REQUEST üst bilgisi ile HTTP 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 nesnelerle çalışmak için örnek URL'ler şunlardır:

  • Key Vault içinde TESTKEY adlı bir anahtar OLUŞTURMAK için - PUT /keys/TESTKEY?api-version=<api-version> HTTP/1.1

  • IMPORTEDKEY adlı bir anahtarı Anahtar Kasası'na içeri aktarmak için - POST /keys/IMPORTEDKEY/import?api-version=<api-version> HTTP/1.1

  • Bir Key Vault'tan MYSECRET adlı bir gizli veriyi almak için - GET /secrets/MYSECRET?api-version=<api-version> HTTP/1.1

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

  • Bir Key Vault isteği için yetkilendirme her zaman aşağıdaki gibidir.

    • Kasalar için: https://<vault-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 kullanarak 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 fiilini belirtmek için "X-HTTP-METHOD" üst bilgisini de içeriyorsa, bu istemciler için HTTP POST yöntemini alternatif olarak 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 alınabilecek Microsoft Entra erişim belirteçlerini destekler.

Uygulamanızı kaydetme ve Azure Key Vault kullanmak için kimlik doğrulama 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 SDK istemcileri, ilk çağrıda gizli bilgiler, sertifikalar ve anahtarlar için kiracı bilgilerini almak üzere bir erişim belirteci sağlamaz. Key Vault SDK istemcisi kullanılarak bir HTTP 401 almanın beklenmesi normaldir. Bu durumda, Key Vault, uygulamaya, kaynağı ve belirteci talep etmesi gereken kiracıyı içeren WWW-Authenticate başlığını gösterir. Her şey doğru yapılandırılırsa, uygulamadan Key Vault ikinci çağrı geçerli bir belirteç içerir ve başarılı olur.

  • Last updated on