Filter keamanan untuk memangkas hasil di Azure AI Search

Artikel
01/10/2024

Pencarian Azure AI tidak menyediakan izin tingkat dokumen dan tidak dapat memvariasikan hasil pencarian dari dalam indeks yang sama berdasarkan izin pengguna. Sebagai solusinya, Anda dapat membuat filter yang memangkas hasil pencarian berdasarkan string yang berisi grup atau identitas pengguna.

Artikel ini menjelaskan pola untuk pemfilteran keamanan yang menyertakan langkah-langkah berikut:

Merakit dokumen sumber dengan konten yang diperlukan
Membuat bidang untuk pengidentifikasi utama
Mendorong dokumen ke indeks pencarian untuk pengindeksan
Mengkueri indeks dengan search.in fungsi filter

Tentang pola filter keamanan

Meskipun Azure AI Search tidak terintegrasi dengan subsistem keamanan untuk akses ke konten dalam indeks, banyak pelanggan yang memiliki persyaratan keamanan tingkat dokumen telah menemukan bahwa filter dapat memenuhi kebutuhan mereka.

Di Azure AI Search, filter keamanan adalah filter OData reguler yang menyertakan atau mengecualikan hasil pencarian berdasarkan nilai yang cocok, kecuali bahwa dalam filter keamanan, kriterianya adalah string yang terdiri dari prinsip keamanan. Tidak ada autentikasi atau otorisasi melalui perwakilan keamanan. Prinsipal hanyalah string, yang digunakan dalam ekspresi filter, untuk menyertakan atau mengecualikan dokumen dari hasil pencarian.

Ada beberapa cara untuk mencapai pemfilteran keamanan. Salah satu caranya adalah melalui pembedaan rumit dari ekspresi kesetaraan: misalnya, Id eq 'id1' or Id eq 'id2', dan sebagainya. Pendekatan ini rentan terhadap kesalahan, sulit dipertahankan, dan dalam kasus di mana daftar berisi ratusan atau ribuan nilai, memperlambat waktu respons kueri dalam beberapa detik.

Solusi yang search.in lebih baik adalah menggunakan fungsi untuk filter keamanan, seperti yang dijelaskan dalam artikel ini. Jika Anda menggunakan search.in(Id, 'id1, id2, ...') alih-alih ekspresi kesetaraan, Anda dapat mengharapkan waktu respons sub-detik.

Prasyarat

Bidang yang berisi grup atau identitas pengguna harus berupa string dengan atribut yang dapat difilter. Ini harus menjadi koleksi. Seharusnya tidak mengizinkan null.
Bidang lain dalam dokumen yang sama harus menyediakan konten yang dapat diakses oleh grup atau pengguna tersebut. Dalam dokumen JSON berikut, bidang "security_id" berisi identitas yang digunakan dalam filter keamanan, dan nama, gaji, dan status perkawinan akan disertakan jika identitas pemanggil cocok dengan "security_id" dokumen.
```
{  
    "Employee-1": {  
        "id": "100-1000-10-1-10000-1",
        "name": "Abram",   
        "salary": 75000,   
        "married": true,
        "security_id": "10011"
    },
    "Employee-2": {  
        "id": "200-2000-20-2-20000-2",
        "name": "Adams",   
        "salary": 75000,   
        "married": true,
        "security_id": "20022"
    } 
}  
```
Catatan

Proses pengambilan pengidentifikasi utama dan menyuntikkan string tersebut ke dokumen sumber yang dapat diindeks oleh Azure AI Search tidak tercakup dalam artikel ini. Lihat dokumentasi penyedia layanan identitas Anda untuk bantuan dalam mendapatkan pengidentifikasi.

Membuat bidang keamanan

Dalam indeks pencarian, dalam kumpulan bidang, Anda memerlukan satu bidang yang berisi grup atau identitas pengguna, mirip dengan bidang "security_id" fiktif dalam contoh sebelumnya.

Tambahkan bidang keamanan sebagai Collection(Edm.String). Pastikan atribut memiliki atribut yang filterable diatur ke true sehingga hasil pencarian difilter berdasarkan akses yang dimiliki pengguna. Misalnya, jika Anda mengatur group_ids bidang ke ["group_id1, group_id2"] untuk dokumen dengan file_name "secured_file_b", hanya pengguna yang termasuk dalam ID grup "group_id1" atau "group_id2" yang memiliki akses baca ke file.

Atur atribut bidang retrievable ke false sehingga tidak dikembalikan sebagai bagian dari permintaan pencarian.

Indeks memerlukan kunci dokumen. Bidang "file_id" memenuhi persyaratan tersebut. Indeks juga harus berisi konten yang dapat dicari. Bidang "file_name" dan "file_description" mewakilinya dalam contoh ini.

POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2023-11-01
{
     "name": "securedfiles",  
     "fields": [
         {"name": "file_id", "type": "Edm.String", "key": true, "searchable": false },
         {"name": "file_name", "type": "Edm.String", "searchable": true },
         {"name": "file_description", "type": "Edm.String", "searchable": true },
         {"name": "group_ids", "type": "Collection(Edm.String)", "filterable": true, "retrievable": false }
     ]
 }

Mendorong data ke indeks Anda menggunakan REST API

Kirim permintaan HTTP POST ke kumpulan dokumen titik akhir URL indeks Anda (lihat Dokumen - Indeks). Isi permintaan HTTP adalah penyajian JSON dari dokumen yang akan diindeks:

POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2023-11-01

Dalam isi permintaan, tentukan konten dokumen Anda:

{
    "value": [
        {
            "@search.action": "upload",
            "file_id": "1",
            "file_name": "secured_file_a",
            "file_description": "File access is restricted to the Human Resources.",
            "group_ids": ["group_id1"]
        },
        {
            "@search.action": "upload",
            "file_id": "2",
            "file_name": "secured_file_b",
            "file_description": "File access is restricted to Human Resources and Recruiting.",
            "group_ids": ["group_id1", "group_id2"]
        },
        {
            "@search.action": "upload",
            "file_id": "3",
            "file_name": "secured_file_c",
            "file_description": "File access is restricted to Operations and Logistics.",
            "group_ids": ["group_id5", "group_id6"]
        }
    ]
}

Jika Anda perlu memperbarui dokumen yang sudah ada dengan daftar grup, Anda bisa menggunakan merge atau mergeOrUpload tindakan:

{
    "value": [
        {
            "@search.action": "mergeOrUpload",
            "file_id": "3",
            "group_ids": ["group_id7", "group_id8", "group_id9"]
        }
    ]
}

Menerapkan filter keamanan dalam kueri

Untuk memangkas dokumen berdasarkan akses group_ids, Anda harus mengeluarkan kueri pencarian dengan filter group_ids/any(g:search.in(g, 'group_id1, group_id2,...')), di mana 'group_id1, group_id2,...' adalah grup tempat penerbit permintaan pencarian berada.

Filter ini cocok dengan semua dokumen group_ids yang bidangnya berisi salah satu pengidentifikasi yang diberikan. Untuk detail selengkapnya tentang mencari dokumen menggunakan Pencarian Azure AI, Anda dapat membaca Cari Dokumen.

Sampel ini memperlihatkan cara menyiapkan kueri menggunakan permintaan POST.

Terbitkan permintaan HTTP POST:

POST https://[service name].search.windows.net/indexes/securedfiles/docs/search?api-version=2020-06-30
Content-Type: application/json  
api-key: [admin or query key]

Tentukan filter dalam isi permintaan:

{
   "filter":"group_ids/any(g:search.in(g, 'group_id1, group_id2'))"  
}

Anda harus mendapatkan dokumen kembali di mana group_ids berisi "group_id1" atau "group_id2". Dengan kata lain, Anda mendapatkan dokumen yang dapat diakses oleh penerbit permintaan.

{
 [
   {
    "@search.score":1.0,
     "file_id":"1",
     "file_name":"secured_file_a",
   },
   {
     "@search.score":1.0,
     "file_id":"2",
     "file_name":"secured_file_b"
   }
 ]
}

Langkah berikutnya

Artikel ini menjelaskan pola untuk memfilter hasil berdasarkan identitas pengguna dan search.in() fungsi. Anda dapat menggunakan fungsi ini untuk meneruskan pengidentifikasi utama agar pengguna yang meminta cocok dengan pengidentifikasi utama yang terkait dengan setiap dokumen target. Saat permintaan pencarian ditangani, fungsi search.in memfilter hasil pencarian yang tidak ada pengguna utama yang memiliki akses baca. Pengidentifikasi utama dapat mewakili hal-hal seperti grup keamanan, peran, atau bahkan identitas pengguna sendiri.

Untuk pola alternatif berdasarkan ID Microsoft Entra, atau untuk mengunjungi kembali fitur keamanan lainnya, lihat tautan berikut.