Autentikasi, permintaan, dan respons

  • Artikel

Azure Key Vault memberikan dua jenis kontainer untuk menyimpan dan mengelola rahasia untuk aplikasi cloud Anda:

Jenis kontainer Jenis objek yang didukung Titik akhir bidang data
Vault
  • Kunci yang dilindungi perangkat lunak
  • Kunci yang dilindungi HSM (dengan SKU Premium)
  • Sertifikat
  • Kunci akun penyimpanan
 https://{vault-name}.vault.azure.net
HSM Terkelola
  • Kunci yang dilindungi HSM
 https://{hsm-name}.managedhsm.azure.net

Berikut adalah akhiran URL yang digunakan untuk mengakses setiap jenis objek

Tipe objek Akhiran URL
Kunci yang dilindungi perangkat lunak /kunci
Kunci yang dilindungi HSM /kunci
Secret /secrets
Sertifikat /certificates
Kunci akun penyimpanan /storageaccounts

Azure Key Vault mendukung permintaan dan respons yang diformat JSON. Permintaan ke Azure Key Vault diarahkan ke URL Azure Key Vault yang valid menggunakan HTTPS dengan beberapa parameter URL serta isi permintaan dan respons yang dikodekan JSON.

Topik ini mencakup spesifik untuk layanan Azure Key Vault. Untuk mengetahui informasi umum tentang menggunakan antarmuka REST Azure, termasuk autentikasi/otorisasi dan cara memperoleh token akses, lihat Referensi REST API Azure.

Minta URL

Operasi manajemen kunci menggunakan HTTP DELETE, GET, PATCH, PUT dan HTTP POST dan operasi kriptografi terhadap objek kunci yang ada menggunakan HTTP POST. Klien yang tidak dapat mendukung kata kerja HTTP tertentu juga dapat menggunakan HTTP POST menggunakan header X-HTTP-REQUEST untuk menentukan kata kerja yang dimaksudkan; permintaan yang biasanya tidak memerlukan isi harus menyertakan isi kosong saat menggunakan HTTP POST, misalnya saat menggunakan POST, bukan DELETE.

Untuk bekerja dengan objek di Azure Key Vault, berikut ini adalah contoh URL:

  • Untuk MEMBUAT kunci yang disebut TESTKEY di penggunaan Key Vault - PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

  • Untuk MENGIMPOR kunci yang disebut IMPORTEDKEY di penggunaan Key Vault - POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

  • Untuk MENDAPATKAN rahasia yang disebut MYSECRET di penggunaan Key Vault - GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

  • Untuk SIGN hash menggunakan kunci yang disebut TESTKEY di penggunaan Key Vault - POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

  • Otoritas untuk permintaan ke Key Vault selalu sebagai berikut,

    • Untuk vault: https://{keyvault-name}.vault.azure.net/
    • Untuk HSM Terkelola: https://{HSM-name}.managedhsm.azure.net/

    Kunci selalu disimpan di bagian/jalur kunci, Rahasia selalu disimpan di bagian/jalur rahasia.

Versi API

Layanan Azure Key Vault mendukung pembuatan versi protokol untuk memberikan kompatibilitas dengan klien tingkat bawah, meskipun tidak semua kemampuan akan tersedia untuk klien tersebut. Klien harus menggunakan parameter untai (karakter) kueri api-version untuk menentukan versi protokol yang mereka dukung karena tidak ada default.

Versi protokol Azure Key Vault mengikuti skema penomoran tanggal menggunakan format {YYYY}.{MM}.{DD}.

Isi Permintaan

Sesuai spesifikasi HTTP, operasi GET TIDAK boleh memiliki isi permintaan, dan operasi POST dan PUT harus memiliki isi permintaan. Isi dalam operasi DELETE bersifat opsional dalam HTTP.

Kecuali disebutkan lain di deskripsi operasi, jenis konten isi permintaan haruslah application/json dan harus berisi objek JSON berseri yang sesuai dengan jenis konten.

Kecuali disebutkan lain di deskripsi operasi, header permintaan Terima harus berisi jenis media application/json.

Isi Respons

Kecuali disebutkan lain di deskripsi operasi, jenis konten isi respons dari operasi yang berhasil dan gagal akan menjadi application/json dan berisi informasi kesalahan mendetail.

Menggunakan HTTP POST

Beberapa klien mungkin tidak dapat menggunakan kata kerja HTTP tertentu, seperti PATCH atau DELETE. Azure Key Vault mendukung HTTP POST sebagai alternatif untuk klien ini asalkan klien juga menyertakan header "X-HTTP-METHOD" untuk menentukan kata kerja HTTP asli. Dukungan untuk HTTP POST dicatat untuk setiap API yang ditentukan dalam dokumen ini.

Respons Kesalahan

Penanganan kesalahan akan menggunakan kode status HTTP. Hasil umumnya adalah:

  • 2xx – Sukses: Digunakan untuk operasi normal. Isi respons akan berisi hasil yang diharapkan

  • 3xx – Pengalihan: 304 "Tidak Dimodifikasi" dapat dikembalikan untuk memenuhi GET bersyarat. Kode 3xx lainnya dapat digunakan di masa mendatang untuk menunjukkan perubahan DNS dan jalur.

  • 4xx – Kesalahan Klien: Digunakan untuk permintaan yang buruk, kunci yang hilang, kesalahan sintaks, parameter yang tidak valid, kesalahan autentikasi, dll. Isi respons akan berisi penjelasan kesalahan terperinci.

  • 5xx – Kesalahan Server: Digunakan untuk kesalahan server internal. Isi respons akan berisi informasi kesalahan yang dirangkum.

    Sistem ini dirancang untuk bekerja di belakang proksi atau firewall. Oleh karena itu, klien mungkin menerima kode galat lainnya.

    Azure Key Vault juga menampilkan informasi kesalahan dalam isi respons saat masalah muncul. Isi respons berformat JSON dan berbentuk:


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

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

Autentikasi

Semua permintaan ke Azure Key Vault HARUS diautentikasi. Azure Key Vault mendukung token akses Microsoft Entra yang mungkin diperoleh menggunakan OAuth2 [RFC6749].

Untuk informasi selengkapnya tentang mendaftarkan aplikasi Anda dan mengautentikasi untuk menggunakan Azure Key Vault, lihat Mendaftarkan aplikasi klien Anda dengan ID Microsoft Entra.

Token akses harus dikirim ke layanan menggunakan header Otorisasi HTTP:

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

Ketika token akses tidak disediakan, atau ketika token tidak diterima oleh layanan, kesalahan HTTP 401 akan ditampilkan ke klien dan akan menyertakan header WWW-Authenticate, misalnya:

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

Parameter pada header WWW-Authenticate adalah:

  • otorisasi: alamat layanan otorisasi OAuth2 yang dapat digunakan untuk mendapatkan token akses untuk permintaan tersebut.

  • sumber daya: Nama sumber daya (https://vault.azure.net) yang akan digunakan di permintaan otorisasi.

Catatan

Klien SDK Key Vault untuk rahasia, sertifikat, dan kunci di panggilan pertama ke Key Vault tidak menyediakan token akses untuk mengambil informasi penyewa. Diharapkan untuk menerima HTTP 401 menggunakan klien SDK Key Vault di mana Key Vault menunjukkan ke aplikasi header WWW-Authenticate yang berisi sumber daya dan penyewa di mana ia harus pergi dan meminta token. Jika semuanya dikonfigurasi dengan benar, panggilan kedua dari aplikasi ke Key Vault akan berisi token yang valid dan akan berhasil.