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ı |
---|---|---|
Tonoz |
|
https://{vault-name}.vault.azure.net |
Yönetilen HSM |
|
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.
- Kasalar için:
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ı.
Not
İ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.