Kimlik doğrulaması, istekler ve yanıtlar

  • Makale

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ı
Tonoz
  • 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 son ekleri aşağıdadır

Object type URL son eki
Yazılım korumalı anahtarlar /Anahtar
HSM ile korunan anahtarlar /Anahtar
Gizli Diziler /Sır -larını
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 konu, 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

Anahtar yönetimi işlemleri HTTP DELETE, GET, PATCH, PUT ve HTTP POST kullanır ve mevcut anahtar nesnelerine karşı şifreleme işlemleri HTTP POST kullanır. Belirli HTTP fiillerini destekleyemeyen istemciler, hedeflenen fiili belirtmek için X-HTTP-REQUEST üst bilgisini kullanarak HTTP POST da kullanabilir; Normalde gövde gerektirmeyen istekler, ÖRNEĞIN DELETE yerine POST kullanırken HTTP POST kullanırken boş bir gövde içermelidir.

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ı gizli diziyi almak 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 istek için yetkili 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 her zaman /secrets yolu altında depolanır.

API Sürümü

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 istemcilerin kullanımına sunulmaz. İ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} kullanarak tarih numaralandırma düzenini izler. {MM}. {DD} biçimi.

İstek Gövdesi

HTTP belirtimine göre GET işlemlerinin bir istek gövdesi, POST ve PUT işlemlerinin de bir istek gövdesi olmalıdır. 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

İş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 olur ve ayrıntılı hata bilgileri içerir.

HTTP POST kullanma

Bazı istemciler PATCH veya DELETE gibi belirli HTTP fiillerini kullanamayabilir. Azure Key Vault, istemcinin özgün HTTP fiiline yönelik "X-HTTP-METHOD" üst bilgisini de içermesi koşuluyla, 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ı

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

  • 3xx – Yeniden Yönlendirme: Koşullu GET'yi yerine getirmek 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çerir.

  • 5xx – Sunucu Hatası: İç sunucu hataları için kullanılır. Yanıt gövdesi özetlenmiş hata bilgileri 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ğrulaması

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 tarafından bir belirteç kabul edilmediğinde, istemciye bir HTTP 401 hatası döndürülür ve WWW-Authenticate üst bilgisi eklenir, ö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 (https://vault.azure.net) adı.

Dekont

İlk Key Vault çağrısında gizli dizi, sertifika ve anahtar talebinde bulunan Key Vault SDK’sı istemcileri, kiracı bilgilerini almak için bir erişim belirteci sağlamaz. Key Vault SDK istemcisi kullanıldığında HTTP 401 hatasının alınması beklenir ve Key Vault, uygulamaya belirtecin alınması gereken kaynağı ve kiracıyı içeren WWW-Authenticate üst bilgisini gösterir. 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.