Penegakan ACL dan RBAC saat kueri di Pencarian Azure AI (pratinjau)

Kontrol akses saat kueri (pratinjau) memastikan bahwa pengguna hanya mendapatkan hasil pencarian yang berwenang mereka akses, berdasarkan identitas, keanggotaan grup, peran, atau atribut mereka. Fungsionalitas ini sangat penting untuk pencarian perusahaan yang aman dan alur kerja berbasis kepatuhan.

Akses resmi bergantung pada metadata izin yang diserap selama pengindeksan. Untuk sumber data pengindeks yang memiliki model akses bawaan, seperti Azure Data Lake Storage (ADLS) Gen2 dan SharePoint di Microsoft 365, pengindeks dapat menarik metadata izin untuk setiap dokumen secara otomatis. Untuk sumber data lain, Anda harus merakit payload dokumen sendiri, dan payload harus menyertakan konten dan metadata izin terkait. Anda kemudian menggunakan API pendorongan untuk memuat indeks.

Artikel ini menjelaskan cara menyiapkan kueri yang menggunakan metadata izin untuk memfilter hasil.

Prasyarat

• Metadata izin harus dalam bentuk bidang string. Anda tidak akan menggunakan filter dalam kueri Anda, tetapi mesin pencari membuat filter secara internal untuk mengecualikan konten yang tidak sah.

• Metadata izin harus terdiri dari izin gaya POSIX yang mengidentifikasi tingkat akses dan ID grup atau pengguna, atau ID sumber daya kontainer di ADLS Gen2 jika Anda menggunakan cakupan RBAC.

• Untuk penerapan berbasis ACL dengan penyerapan kustom, simpan userIds dan groupIds sebagai ID objek (GUID) Microsoft Entra di bidang yang dapat difilter. Pada saat kueri, layanan mencocokkan identitas dalam x-ms-query-source-authorization dengan ID yang tersimpan tersebut. Untuk detail skema, lihat Mengindeks daftar kontrol akses dokumen (ACL) menggunakan REST API push (pratinjau).

• Bergantung pada sumber data:

  • Untuk sumber data ADLS Gen2, Anda harus memiliki daftar kontrol akses (ACL) dan/atau peran kontrol akses berbasis peran (RBAC) Azure yang telah dikonfigurasi di tingkat kontainer.
  • Untuk sumber data Blob Azure, Anda harus memiliki penetapan peran pada wadah. Anda dapat menggunakan pengindeks bawaan, sumber pengetahuan, atau API Push untuk mengindeks metadata izin dalam indeks Anda.
  • Untuk sumber data SharePoint, Anda harus mengonfigurasi daftar kontrol akses (ACL). Anda dapat menggunakan pengindeks SharePoint bawaan dan mengonfigurasinya dengan kemampuan ingestasi ACL. Anda juga dapat menggunakan sumber pengetahuan SharePoint terindeks dan mengonfigurasinya untuk menerapkan izin tingkat dokumen. Izin berbasis grup, termasuk Grup Microsoft 365, didukung jika dimasukkan sebagai ID objek Entra. Perluasan grup terjadi saat kueri dijalankan melalui Microsoft Graph.

• Gunakan REST API pratinjau terbaru atau paket pratinjau Azure SDK untuk meminta indeks atau sumber pengetahuan. Versi API ini mendukung kueri internal yang memfilter hasil yang tidak sah.

Keterbatasan

• Jika evaluasi ACL gagal (misalnya, Graph API tidak tersedia), layanan mengembalikan 5xx dan tidak mengembalikan set hasil yang difilter sebagian.

• Kesegaran ACL tergantung pada metode penyerapan. Untuk menghindari keputusan otorisasi kedaluarsa, rencanakan bagaimana setiap sumber menyebarluaskan perubahan izin ke indeks:

  • Pengindeks SharePoint terjadwal memperbarui perubahan izin tingkat item setiap kali dijalankan. Perubahan pada cakupan induk (situs, pustaka, daftar, atau folder) yang diwariskan oleh item turunan memerlukan sinkronisasi ulang.
  • Pengindeks ADLS Gen2 memerlukan sinkronisasi ulang untuk merefresh ACL.
  • Proses ingest kustom atau ingest push mengharuskan Anda untuk melakukan ingest ulang pada dokumen yang terdampak.

• Visibilitas dokumen memerlukan keduanya:

  • Peran RBAC aplikasi panggilan (header Otorisasi).
  • Identitas pengguna yang dibawa oleh x-ms-query-source-authorization.

• Kueri berbasis ACL pada awalnya mungkin mengalami latensi yang lebih tinggi dibanding permintaan berikutnya karena mekanisme cache dan overhead proses resolusi izin.

• Untuk konten SharePoint yang diindeks, grup Microsoft Entra yang disarangkan dalam grup SharePoint tidak diperluas. Resolusi grup transitif Microsoft Entra tidak mendukung hubungan campuran ini. Lihat Hubungan grup yang didukung.

Batas entri ACL per sumber data

Batas entri daftar kontrol akses (ACL) menentukan berapa banyak rekaman izin berbeda yang dapat dikaitkan dengan file, folder, atau item dalam sumber data yang tersambung. Setiap entri mewakili satu identitas pengguna atau grup dan hak akses yang diberikan kepada identitas tersebut (misalnya, Baca, Tulis, atau Jalankan).

Jumlah maksimum entri ACL yang didukung oleh fungsionalitas Pencarian Azure AI bervariasi tergantung pada jenis sumber data:

Azure Data Lake Storage Gen2 (ADLS Gen2): Setiap file atau direktori dapat memiliki izin entri ACL 32. Dalam konteks ini, entri berarti satu entitas utama (pengguna atau kelompok) dengan set izin tertentu. Contoh: menetapkan akses baca "Semua Orang" dan akses eksekusi "pengguna Azure" akan dihitung sebagai dua entri ACL.

SharePoint dalam Microsoft 365: SharePoint sumber data dalam pencarian mendukung hingga 1.000 entri izin per file. Setiap entri mewakili penetapan pengguna atau grup unik dalam daftar izin item. Ini berbeda dari batas cakupan izin unik keseluruhan per daftar atau pustaka, yang mengatur berapa banyak item yang dapat memiliki izin unik.

Batas ini menentukan seberapa terperinci Pencarian Azure AI dapat mematuhi izin tingkat item saat mengindeks atau memfilter hasil pencarian. Jika item melebihi batas entri ACL ini, izin di luar batas mungkin tidak diberlakukan pada waktu kueri.

Cara kerja penerapan pada saat pemrosesan kueri

Bagian ini mencantumkan urutan operasi untuk penerapan ACL saat kueri dilakukan. Operasi bervariasi tergantung pada apakah Anda menggunakan cakupan RBAC Azure atau grup Microsoft Entra ID atau ID pengguna.

1. Input izin pengguna

Aplikasi pengguna akhir menyertakan token akses kueri sebagai bagian dari permintaan kueri pencarian, dan token akses tersebut biasanya merupakan identitas pengguna. Tabel berikut ini mencantumkan sumber izin pengguna yang didukung oleh Pencarian Azure AI untuk penerapan ACL:

2. Konstruksi filter keamanan

Secara internal, Pencarian Azure AI membangun filter keamanan secara dinamis berdasarkan izin pengguna yang disediakan. Filter keamanan ini secara otomatis ditambahkan ke filter apa pun yang mungkin disertakan dengan kueri jika indeks mengaktifkan opsi filter izin.

Untuk RBAC di Azure, izin terdiri dari daftar string ID sumber daya. Harus ada penetapan peran Azure (Pembaca Data Blob Penyimpanan) pada sumber data yang memberikan akses ke token utama keamanan di header otorisasi. Filter mengecualikan dokumen jika tidak ada penetapan peran untuk prinsipal di belakang token akses dalam permintaan.

3. Pemfilteran hasil

Filter keamanan secara efisien mencocokkan userIds, groupIds, dan rbacScope dari permintaan dengan setiap daftar ACL di setiap dokumen dalam indeks pencarian untuk membatasi hasil yang dikembalikan hanya pada yang dapat diakses oleh pengguna. Penting untuk dicatat bahwa setiap filter diterapkan secara independen dan dokumen dianggap diotorisasi jika ada filter yang berhasil. Misalnya, jika pengguna memiliki akses ke dokumen melalui userIds tetapi tidak melalui groupIds, dokumen masih dianggap valid dan dikembalikan kepada pengguna.

Grup SharePoint saat kueri dijalankan

Mulai dengan REST API pratinjau 2026-05-01, Pencarian Azure AI dapat menerapkan keanggotaan grup situs SharePoint, seperti Owners, Members, Visitors, dan grup situs kustom, saat kueri dijalankan. Untuk mengaktifkan skenario ini, indeks harus mencakup:

• Properti sharePointConnectorAppRegistration yang mereferensikan kredensial identitas federasi aplikasi Microsoft Entra yang digunakan untuk memanggil SharePoint atas nama pengguna.
• Bidang yang ditandai dengan atribut sharepointSiteUrl: true yang menyimpan URL situs SharePoint untuk setiap item terindeks (biasanya bernama SharePointSiteUrl dan diisi dari bidang sumber metadata_spo_site_url).

Saat kueri, Pencarian Azure AI menggunakan aplikasi yang terdaftar dan URL situs pada setiap dokumen kandidat untuk menentukan keanggotaan grup SharePoint dari pengguna pemanggil di situs tersebut. Grup yang dihasilkan dicocokkan dengan nilai berawalan spg: yang disimpan di bidang filter izin groupIds. Awalan spg: membedakan grup situs SharePoint dari ID objek grup Microsoft Entra, yang disimpan tanpa awalan.

Untuk detail dan batasan konfigurasi, lihat Konfigurasi dukungan grup SharePoint.

Jika pemfilteran izin SharePoint mengembalikan hasil yang hilang atau tidak terduga, lihat Memecahkan masalah pemfilteran izin SharePoint.

Contoh: Kueri dengan penerapan grup situs SharePoint

Permintaan ini identik dengan kueri standar yang diberlakukan ACL. Layanan pencarian menggunakan indeks sharePointConnectorAppRegistration untuk menyelesaikan keanggotaan kelompok SharePoint atas nama pemanggil. Sertakan GroupIds dalam klausa select untuk melihat nilai dengan awalan spg: dalam respons.

POST {{endpoint}}/indexes/{index}/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: {{query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,SharePointSiteUrl,GroupIds",
    "orderby": "name asc"
}

Contoh kueri

Berikut adalah contoh permintaan kueri dari kode sample. Token kueri adalah token akses Microsoft Entra bagi pengguna yang melakukan kueri.

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: {{query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

Izin tingkat lanjut untuk menyelidiki hasil yang tidak tepat (pratinjau)

Meng-debug kueri yang menyertakan data izin dapat menimbulkan masalah karena hasil pencarian khusus untuk setiap pengguna. Sebagai pengembang atau administrator, Anda mungkin memerlukan izin yang ditinggikan untuk mengembalikan hasil terlepas dari metadata izin sehingga Anda dapat menyelidiki masalah dengan kueri yang mengembalikan konten yang tidak sah.

Untuk menyelidikinya, Anda harus dapat:

• Tampilkan kumpulan dokumen yang dapat dilihat pengguna akhir berdasarkan izin pengguna tersebut.

• Tampilkan semua dokumen dalam indeks untuk menyelidiki mengapa beberapa mungkin tidak terlihat oleh pengguna akhir.

Anda dapat menyelesaikan tugas-tugas ini dengan menambahkan header kustom, x-ms-enable-elevated-read: true, ke kueri.

Izin untuk permintaan baca dengan hak akses yang ditingkatkan

Anda harus memiliki izin Kontributor Data Indeks Pencarian atau peran kustom yang menyertakan izin Tingkatkan Baca.

Kueri adalah operasi lapisan data, oleh karena itu peran kustom hanya dapat terdiri dari izin lapisan data atomik. Untuk peran kustom, tambahkan izin Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read.

Menambahkan header baca yang ditingkatkan ke kueri

Setelah menyiapkan izin, Anda bisa menjalankan kueri. Contoh berikut adalah permintaan kueri terhadap indeks pencarian.

POST {endpoint}/indexes('{indexName}')/search.post.search?api-version=2026-08-01-preview
Authorization: Bearer {AUTH_TOKEN}
x-ms-query-source-authorization: {TOKEN}
x-ms-enable-elevated-read: true

{
    "search": "prototype tests",
    "select": "filename, author, date",
    "count": true
}

Perubahan perilaku fungsionalitas ACL penting dalam versi API pratinjau tertentu

Sebelum REST API versi 2025-11-01-preview, versi pratinjau sebelumnya 2025-05-01-preview dan 2025-08-01-preview mengembalikan semua dokumen saat menggunakan kunci API layanan atau peran Entra yang diberi otorisasi, bahkan jika tidak ada token pengguna yang disediakan. Aplikasi yang tidak memvalidasi keberadaan token pengguna secara tidak sengaja dapat mengekspos hasil kepada pengguna akhir jika tidak diterapkan dengan benar atau mengikuti praktik terbaik.

Mulai November 2025, perilaku ini berubah:

• Filter izin ACL sekarang berlaku bahkan saat hanya menggunakan kunci API layanan atau autentikasi Entra di semua versi yang mendukung ACL.
• Jika token pengguna dihilangkan, konten yang dilindungi ACL tidak dikembalikan.
• Untuk melihat semua dokumen untuk pemecahan masalah, Anda harus secara eksplisit menyertakan header elevated-read saat menggunakan versi REST API 2026-05-01-preview atau yang lebih baru.

Pembaruan ini membantu menjaga konten tetap terlindungi ketika aplikasi tidak menerapkan praktik terbaik untuk validasi token.

Konten terkait

• Tutorial: Mengindeks metadata izin dari ADLS Gen2 dan membuat kueri dengan hasil yang difilter berdasarkan izin (pratinjau)
• Mengindeks daftar kontrol akses dokumen (ACL) menggunakan REST API pendorongan (pratinjau)
• Menggunakan pengindeks ADLS Gen2 untuk menyerap metadata izin dan memfilter hasil pencarian berdasarkan hak akses pengguna (pratinjau)
• Menggunakan pengindeks blob atau sumber pengetahuan untuk menyerap metadata cakupan RBAC
• Gunakan pengindeks SharePoint untuk menyerap metadata izin dan memfilter hasil pencarian berdasarkan hak akses pengguna (pratinjau)