Autentikasi, permintaan, dan respons

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

Jenis kontainer Jenis objek yang didukung Titik akhir data-plane
Vaults
  • Kunci yang dilindungi perangkat lunak
  • Kunci yang terproteksi oleh HSM (dengan SKU Premium)
  • Sertifikat
 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

Jenis objek Akhiran URL
Kunci yang dilindungi perangkat lunak /kunci
Kunci yang dilindungi HSM /kunci
Rahasia /rahasia
Sertifikat /sertifikat

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

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

Struktur URL Permintaan

Operasi manajemen kunci menggunakan kata kerja HTTP termasuk DELETE, GET, PATCH, dan PUT. Operasi kriptografi pada objek kunci yang ada menggunakan HTTP POST.

Untuk klien yang tidak dapat mendukung kata kerja HTTP tertentu, Azure Key Vault memungkinkan penggunaan HTTP POST dengan header X-HTTP-REQUEST untuk menentukan kata kerja yang dimaksudkan. Saat menggunakan POST sebagai pengganti (misalnya, alih-alih DELETE), sertakan isi kosong untuk permintaan yang biasanya tidak memerlukannya.

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

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

  • Untuk MENGIMPOR kunci yang disebut IMPORTEDKEY ke dalam Key Vault gunakan - POST /keys/IMPORTEDKEY/import?api-version=<api-version> HTTP/1.1

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

  • Untuk menandatangani ringkasan menggunakan kunci yang disebut TESTKEY dalam Key Vault, gunakan - POST /keys/TESTKEY/sign?api-version=<api-version> HTTP/1.1

  • Otoritas untuk permintaan ke Key Vault selalu adalah sebagai berikut,

    • Untuk vault: https://<vault-name>.vault.azure.net/
    • Untuk HSM Terkelola: https://{HSM-name}.managedhsm.azure.net/ Kunci selalu disimpan di bawah jalur /keys, sementara Rahasia selalu disimpan di bawah jalur /secrets.

Versi API yang didukung

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

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

Persyaratan Badan 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 di HTTP.

Kecuali dinyatakan lain dalam deskripsi operasi, jenis konten isi permintaan harus aplikasi/json dan harus berisi objek JSON berseri sesuai dengan jenis konten.

Kecuali dinyatakan lain dalam deskripsi operasi, header Permintaan terima harus berisi jenis media aplikasi/json.

Format isi respons

Kecuali dinyatakan lain dalam deskripsi operasi, jenis konten isi respons dari operasi yang berhasil dan gagal adalah aplikasi/json dan berisi informasi kesalahan terperinci.

Menggunakan HTTP POST sebagai alternatif

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 jika klien juga menyertakan header "X-HTTP-METHOD" untuk spesifik kata kerja HTTP asli. Dukungan untuk HTTP POST dicatat untuk setiap API yang ditentukan dalam dokumen ini.

Menangani respons kesalahan

Penanganan kesalahan menggunakan kode status HTTP. Hasil umumnya adalah:

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

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

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

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

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

    Azure Key Vault juga mengembalikan informasi kesalahan dalam isi respons saat masalah terjadi. Isi respons diformat dalam bentuk JSON dan memiliki struktur:


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

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

Persyaratan autentikasi

Semua permintaan untuk 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 Mendatakan aplikasi klien Anda dengan Microsoft Entra ID.

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 layanan tidak menerima token, kesalahan HTTP 401 dikembalikan ke klien dan 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) untuk digunakan dalam permintaan otorisasi.

Nota

Key Vault klien SDK untuk rahasia, sertifikat, dan kunci dalam 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 menampilkan ke aplikasi header WWW-Authenticate yang berisi sumber daya dan penyewa tempat aplikasi perlu pergi untuk meminta token. Jika semuanya dikonfigurasi dengan benar, panggilan kedua dari aplikasi ke Key Vault akan berisi token yang valid dan akan berhasil.

  • Last updated on