Dukungan JSON Patch di API web ASP.NET Core

Artikel ini menjelaskan cara menangani permintaan JSON Patch di API web ASP.NET Core.

Penting

Standar Patch JSON memiliki risiko keamanan yang melekat. Implementasi ini tidak mencoba mengurangi risiko keamanan yang melekat ini. Ini adalah tanggung jawab pengembang untuk memastikan bahwa dokumen Patch JSON aman untuk diterapkan ke objek target. Untuk informasi selengkapnya, lihat bagian Mitigasi Risiko Keamanan .

Penginstalan paket

Dukungan JSON Patch di API web ASP.NET Core didasarkan pada Newtonsoft.Json dan memerlukan Microsoft.AspNetCore.Mvc.NewtonsoftJson paket NuGet.

Untuk mengaktifkan dukungan JSON Patch:

• Microsoft.AspNetCore.Mvc.NewtonsoftJson Instal paket NuGet.

• Panggil AddNewtonsoftJson. Contohnya:

  var builder = WebApplication.CreateBuilder(args);
  
  builder.Services.AddControllers()
      .AddNewtonsoftJson();
  
  var app = builder.Build();
  
  app.UseHttpsRedirection();
  
  app.UseAuthorization();
  
  app.MapControllers();
  
  app.Run();
  

AddNewtonsoftJson menggantikan pemformat input dan output berbasis default System.Text.Jsonyang digunakan untuk memformat semua konten JSON. Metode ekstensi ini kompatibel dengan metode pendaftaran layanan MVC berikut:

• AddRazorPages
• AddControllersWithViews
• AddControllers

JsonPatch memerlukan pengaturan Content-Type header ke application/json-patch+json.

Menambahkan dukungan untuk JSON Patch saat menggunakan System.Text.Json

Formatter System.Text.Jsoninput berbasis tidak mendukung JSON Patch. Untuk menambahkan dukungan untuk JSON Patch menggunakan Newtonsoft.Json, sambil membiarkan pemformat input dan output lainnya tidak berubah:

• Microsoft.AspNetCore.Mvc.NewtonsoftJson Instal paket NuGet.

• Perbarui Program.cs:

  using JsonPatchSample;
  using Microsoft.AspNetCore.Mvc.Formatters;
  
  var builder = WebApplication.CreateBuilder(args);
  
  builder.Services.AddControllers(options =>
  {
      options.InputFormatters.Insert(0, MyJPIF.GetJsonPatchInputFormatter());
  });
  
  var app = builder.Build();
  
  app.UseHttpsRedirection();
  
  app.UseAuthorization();
  
  app.MapControllers();
  
  app.Run();
  

  using Microsoft.AspNetCore.Mvc;
  using Microsoft.AspNetCore.Mvc.Formatters;
  using Microsoft.Extensions.Options;
  
  namespace JsonPatchSample;
  
  public static class MyJPIF
  {
      public static NewtonsoftJsonPatchInputFormatter GetJsonPatchInputFormatter()
      {
          var builder = new ServiceCollection()
              .AddLogging()
              .AddMvc()
              .AddNewtonsoftJson()
              .Services.BuildServiceProvider();
  
          return builder
              .GetRequiredService<IOptions<MvcOptions>>()
              .Value
              .InputFormatters
              .OfType<NewtonsoftJsonPatchInputFormatter>()
              .First();
      }
  }
  

Kode sebelumnya membuat instans NewtonsoftJsonPatchInputFormatter dan menyisipkannya sebagai entri pertama dalam MvcOptions.InputFormatters koleksi. Urutan pendaftaran ini memastikan bahwa:

• NewtonsoftJsonPatchInputFormatter memproses permintaan Patch JSON.
• Input dan formatter berbasis yang ada System.Text.Jsonmemproses semua permintaan dan respons JSON lainnya.

Newtonsoft.Json.JsonConvert.SerializeObject Gunakan metode untuk membuat JsonPatchDocumentserialisasi .

Metode permintaan HTTP PATCH

Metode PUT dan PATCH digunakan untuk memperbarui sumber daya yang ada. Perbedaannya adalah PUT menggantikan seluruh sumber daya, sementara PATCH hanya menentukan perubahan.

JSON Patch

JSON Patch adalah format untuk menentukan pembaruan yang akan diterapkan ke sumber daya. Dokumen JSON Patch memiliki array operasi. Setiap operasi mengidentifikasi jenis perubahan tertentu. Contoh perubahan tersebut termasuk menambahkan elemen array atau mengganti nilai properti.

Misalnya, dokumen JSON berikut mewakili sumber daya, dokumen Patch JSON untuk sumber daya, dan hasil penerapan operasi Patch.

Contoh sumber daya

{
  "customerName": "John",
  "orders": [
    {
      "orderName": "Order0",
      "orderType": null
    },
    {
      "orderName": "Order1",
      "orderType": null
    }
  ]
}

Contoh patch JSON

[
  {
    "op": "add",
    "path": "/customerName",
    "value": "Barry"
  },
  {
    "op": "add",
    "path": "/orders/-",
    "value": {
      "orderName": "Order2",
      "orderType": null
    }
  }
]

Dalam JSON sebelumnya:

• Properti op menunjukkan jenis operasi.
• Properti path menunjukkan elemen yang akan diperbarui.
• Properti value menyediakan nilai baru.

Sumber daya setelah patch

Berikut adalah sumber daya setelah menerapkan dokumen Patch JSON sebelumnya:

{
  "customerName": "Barry",
  "orders": [
    {
      "orderName": "Order0",
      "orderType": null
    },
    {
      "orderName": "Order1",
      "orderType": null
    },
    {
      "orderName": "Order2",
      "orderType": null
    }
  ]
}

Perubahan yang dilakukan dengan menerapkan dokumen JSON Patch ke sumber daya adalah atomik. Jika ada operasi dalam daftar yang gagal, tidak ada operasi dalam daftar yang diterapkan.

Sintaksis jalur

Properti jalur objek operasi memiliki garis miring antar level. Contohnya,"/address/zipCode".

Indeks berbasis nol digunakan untuk menentukan elemen array. Elemen pertama dari addresses array akan berada di /addresses/0. Untuk add ke akhir array, gunakan tanda hubung (-) daripada nomor indeks: /addresses/-.

Operasional

Tabel berikut ini memperlihatkan operasi yang didukung seperti yang didefinisikan dalam spesifikasi Patch JSON:

Operasi	Catatan
add	Tambahkan elemen properti atau array. Untuk properti yang ada: tetapkan nilai.
remove	Menghapus elemen properti atau array.
replace	Sama seperti remove diikuti oleh add di lokasi yang sama.
move	Sama seperti remove dari sumber diikuti oleh add ke tujuan menggunakan nilai dari sumber.
copy	Sama seperti add tujuan menggunakan nilai dari sumber.
test	Mengembalikan kode status keberhasilan jika nilai di path = disediakan value.

Patch JSON di ASP.NET Core

Implementasi ASP.NET Core dari JSON Patch disediakan dalam paket NuGet Microsoft.AspNetCore.JsonPatch .

Kode metode tindakan

Dalam pengontrol API, metode tindakan untuk JSON Patch:

• Diannotasikan dengan HttpPatch atribut .
• JsonPatchDocument<TModel>Menerima , biasanya dengan [FromBody].
• ApplyTo(Object) Panggilan pada dokumen patch untuk menerapkan perubahan.

Berikut contohnya:

[HttpPatch]
public IActionResult JsonPatchWithModelState(
    [FromBody] JsonPatchDocument<Customer> patchDoc)
{
    if (patchDoc != null)
    {
        var customer = CreateCustomer();

        patchDoc.ApplyTo(customer, ModelState);

        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }

        return new ObjectResult(customer);
    }
    else
    {
        return BadRequest(ModelState);
    }
}

Kode dari aplikasi sampel ini berfungsi dengan model berikut Customer :

namespace JsonPatchSample.Models;

public class Customer
{
    public string? CustomerName { get; set; }
    public List<Order>? Orders { get; set; }
}

namespace JsonPatchSample.Models;

public class Order
{
    public string OrderName { get; set; }
    public string OrderType { get; set; }
}

Metode tindakan sampel:

• Membangun sebuah Customer.
• Menerapkan patch.
• Mengembalikan hasil dalam isi respons.

Dalam aplikasi nyata, kode akan mengambil data dari penyimpanan seperti database dan memperbarui database setelah menerapkan patch.

Status model

Contoh metode tindakan sebelumnya memanggil kelebihan beban ApplyTo yang mengambil status model sebagai salah satu parameternya. Dengan opsi ini, Anda bisa mendapatkan pesan kesalahan sebagai respons. Contoh berikut menunjukkan isi respons Permintaan Buruk 400 untuk test operasi:

{
  "Customer": [
    "The current value 'John' at path 'customerName' != test value 'Nancy'."
  ]
}

Objek dinamis

Contoh metode tindakan berikut menunjukkan cara menerapkan patch ke objek dinamis:

[HttpPatch]
public IActionResult JsonPatchForDynamic([FromBody]JsonPatchDocument patch)
{
    dynamic obj = new ExpandoObject();
    patch.ApplyTo(obj);

    return Ok(obj);
}

Operasi tambahkan

• Jika path menunjuk ke elemen array: menyisipkan elemen baru sebelum elemen yang ditentukan oleh path.
• Jika path menunjuk ke properti: mengatur nilai properti.
• Jika path menunjuk ke lokasi yang tidak ada:
  • Jika sumber daya yang akan di-patch adalah objek dinamis: menambahkan properti.
  • Jika sumber daya untuk di-patch adalah objek statis: permintaan gagal.

Contoh dokumen patch berikut mengatur nilai CustomerName dan menambahkan Order objek ke akhir Orders array.

[
  {
    "op": "add",
    "path": "/customerName",
    "value": "Barry"
  },
  {
    "op": "add",
    "path": "/orders/-",
    "value": {
      "orderName": "Order2",
      "orderType": null
    }
  }
]

Operasi hapus

• Jika path menunjuk ke elemen array: menghapus elemen .
• Jika path menunjuk ke properti:
  • Jika sumber daya untuk patch adalah objek dinamis: menghapus properti .
  • Jika sumber daya untuk di-patch adalah objek statis:
    • Jika properti nullable: mengaturnya ke null.
    • Jika properti tidak dapat diubah ke null, atur ke default<T>.

Contoh kumpulan CustomerName dokumen patch berikut ke null dan hapus Orders[0]:

[
  {
    "op": "remove",
    "path": "/customerName"
  },
  {
    "op": "remove",
    "path": "/orders/0"
  }
]

Operasi ganti

Operasi ini secara fungsional sama remove dengan diikuti oleh add.

Contoh dokumen patch berikut menetapkan nilai CustomerName dan mengganti Orders[0]dengan objek baru Order :

[
  {
    "op": "replace",
    "path": "/customerName",
    "value": "Barry"
  },
  {
    "op": "replace",
    "path": "/orders/0",
    "value": {
      "orderName": "Order2",
      "orderType": null
    }
  }
]

Operasi pemindahan

• Jika path menunjuk ke elemen array: menyalin from elemen ke lokasi path elemen, maka menjalankan remove operasi pada from elemen .
• Jika path menunjuk ke properti: menyalin nilai from properti ke path properti, maka menjalankan remove operasi pada from properti .
• Jika path menunjuk ke properti yang tidak ada:
  • Jika sumber daya untuk di-patch adalah objek statis: permintaan gagal.
  • Jika sumber daya untuk patch adalah objek dinamis: menyalin from properti ke lokasi yang path ditunjukkan oleh remove, maka menjalankan operasi pada from properti .

Contoh dokumen patch berikut:

• Menyalin nilai Orders[0].OrderName ke CustomerName.
• Orders[0].OrderName Mengatur ke null.
• Orders[1] Pindah ke sebelum Orders[0].

[
  {
    "op": "move",
    "from": "/orders/0/orderName",
    "path": "/customerName"
  },
  {
    "op": "move",
    "from": "/orders/1",
    "path": "/orders/0"
  }
]

Operasi salin

Operasi ini secara fungsional sama move dengan operasi tanpa langkah terakhir remove .

Contoh dokumen patch berikut:

• Menyalin nilai Orders[0].OrderName ke CustomerName.
• Menyisipkan salinan Orders[1] sebelum Orders[0].

[
  {
    "op": "copy",
    "from": "/orders/0/orderName",
    "path": "/customerName"
  },
  {
    "op": "copy",
    "from": "/orders/1",
    "path": "/orders/0"
  }
]

Operasi pengujian

Jika nilai di lokasi yang ditunjukkan oleh path berbeda dari nilai yang disediakan dalam value, permintaan gagal. Dalam hal ini, seluruh permintaan PATCH gagal bahkan jika semua operasi lain dalam dokumen patch akan berhasil.

Operasi test ini umumnya digunakan untuk mencegah pembaruan ketika ada konflik konkurensi.

Contoh dokumen patch berikut tidak berpengaruh jika nilai CustomerName awal adalah "John", karena pengujian gagal:

[
  {
    "op": "test",
    "path": "/customerName",
    "value": "Nancy"
  },
  {
    "op": "add",
    "path": "/customerName",
    "value": "Barry"
  }
]

Mendapatkan kode

Melihat atau mengunduh kode sampel. (Cara mengunduh).

Untuk menguji sampel, jalankan aplikasi dan kirim permintaan HTTP dengan pengaturan berikut:

• URL: http://localhost:{port}/jsonpatch/jsonpatchwithmodelstate
• Metode HTTP: PATCH
• Judul: Content-Type: application/json-patch+json
• Isi: Salin dan tempel salah satu sampel dokumen patch JSON dari folder proyek JSON .

Mengurangi risiko keamanan

Saat menggunakan paket Microsoft.AspNetCore.JsonPatch dengan implementasi berbasis Newtonsoft.Json, memahami dan mengurangi potensi risiko keamanan adalah sangat penting. Bagian berikut menguraikan risiko keamanan yang diidentifikasi yang terkait dengan Patch JSON dan memberikan mitigasi yang direkomendasikan untuk memastikan penggunaan paket yang aman.

Penting

Ini bukan daftar ancaman yang lengkap. Pengembang aplikasi harus melakukan tinjauan model ancaman mereka sendiri untuk menentukan daftar komprehensif khusus aplikasi dan membuat mitigasi yang sesuai kebutuhan. Misalnya, aplikasi yang mengekspos koleksi ke operasi patch harus mempertimbangkan potensi serangan kompleksitas algoritma jika operasi tersebut menyisipkan atau menghapus elemen di awal koleksi.

Dengan menjalankan model ancaman komprehensif untuk aplikasi mereka sendiri dan mengatasi ancaman yang diidentifikasi saat mengikuti mitigasi yang direkomendasikan di bawah ini, konsumen paket ini dapat mengintegrasikan fungsionalitas JSON Patch ke dalam aplikasi mereka sambil meminimalkan risiko keamanan.

Penolakan Layanan (DoS) melalui amplifikasi memori

• Skenario: Klien berbahaya mengirimkan copy operasi yang menduplikasi grafik objek besar beberapa kali, yang mengarah ke konsumsi memori yang berlebihan.
• Dampak: Potensi kondisi Out-Of-Memory (OOM), menyebabkan gangguan layanan.
• Mitigasi:
  • Validasi dokumen JSON Patch masuk untuk ukuran dan struktur sebelum memanggil ApplyTo.
  • Validasi harus spesifik untuk aplikasi, tetapi contoh validasi dapat terlihat mirip dengan yang berikut ini:

public void Validate(JsonPatchDocument patch)
{
    // This is just an example. It's up to the developer to make sure that
    // this case is handled properly, based on the app needs.
    if (patch.Operations.Where(op => op.OperationType == OperationType.Copy).Count()
                              > MaxCopyOperationsCount)
    {
        throw new InvalidOperationException();
    }
}

Pengacauan Logika Bisnis

• Skenario: Operasi patch dapat memanipulasi bidang dengan invarian implisit (misalnya, bendera internal, ID, atau bidang komputasi), melanggar batasan bisnis.
• Dampak: Masalah integritas data dan perilaku aplikasi yang tidak diinginkan.
• Mitigasi:
  • Gunakan objek POCO dengan properti yang ditentukan secara eksplisit yang aman untuk dimodifikasi.
  • Hindari mengekspos properti sensitif atau kritis keamanan di objek target.
  • Jika tidak ada objek POCO yang digunakan, validasi objek yang di-patch setelah menerapkan operasi untuk memastikan aturan bisnis dan invarian tidak dilanggar.

Autentikasi dan otorisasi

• Skenario: Klien yang tidak diautentikasi atau tidak sah mengirim permintaan Patch JSON berbahaya.
• Dampak: Akses tidak sah untuk memodifikasi data sensitif atau mengganggu perilaku aplikasi.
• Mitigasi:
  • Lindungi titik akhir yang menerima permintaan JSON Patch dengan mekanisme autentikasi dan otorisasi yang tepat.
  • Batasi akses ke klien atau pengguna tepercaya dengan izin yang sesuai.

Sumber Daya Tambahan:

• Spesifikasi metode IETF RFC 5789 PATCH
• Spesifikasi IETF RFC 6902 JSON Patch
• IETF RFC 6901 JSON Pointer
• ASP.NET kode sumber Core JSON Patch