Bagikan melalui

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

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

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 Azure REST, termasuk autentikasi/otorisasi dan cara memperoleh token akses, lihat Referensi AZURE 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 X-HTTP-REQUEST header 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 dengan nama IMPORTEDKEY ke dalam Key Vault gunakan - POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

  • Untuk mendapatkan rahasia bernama MYSECRET dari Key Vault gunakan - GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

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

  • Otoritas untuk permintaan ke Key Vault adalah sebagai berikut:

    • Untuk vault: https://{keyvault-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.

Versi protokol Azure Key Vault mengikuti skema penomoran tanggal menggunakan {YYYY}. {MM}. Format {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 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 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

Klien-klien SDK Key Vault untuk rahasia, sertifikat, dan kunci pada panggilan pertama ke Key Vault tidak menyediakan token akses untuk mengakses informasi penyewa. Diharapkan akan menerima HTTP 401 ketika menggunakan klien SDK Key Vault di mana Key Vault memberikan kepada aplikasi header WWW-Authenticate yang berisi sumber daya dan penyewa di mana aplikasi tersebut 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.