Menyambungkan ke Azure AI Search menggunakan peran
Azure menyediakan sistem otorisasi berbasis peran dan autentikasi global untuk semua layanan yang berjalan di platform. Di Azure AI Search, Anda dapat menetapkan peran Azure untuk:
Akses per pengguna melalui hasil pencarian (terkadang disebut sebagai keamanan tingkat baris atau keamanan tingkat dokumen) tidak didukung melalui penetapan peran. Sebagai solusinya, buat filter keamanan yang memangkas hasil berdasarkan identitas pengguna, menghapus dokumen yang tidak boleh diakses pemohon. Lihat sampel obrolan Enterprise ini menggunakan RAG untuk demonstrasi.
Penetapan peran bersifat kumulatif dan pervasif di semua alat dan pustaka klien. Anda dapat menetapkan peran menggunakan salah satu pendekatan yang didukung yang dijelaskan dalam dokumentasi kontrol akses berbasis peran Azure.
Akses berbasis peran bersifat opsional, tetapi disarankan. Alternatifnya adalah autentikasi berbasis kunci, yang merupakan default.
Prasyarat
Layanan pencarian di wilayah mana pun, pada tingkat mana pun, diaktifkan untuk akses berbasis peran.
Pemilik, Administrator Akses Pengguna, atau peran kustom dengan izin Microsoft.Authorization/roleAssignments/write .
Peran bawaan yang digunakan dalam Azure AI Search
Peran berikut dibangun. Jika peran ini tidak mencukup, buat peran kustom.
Peran | Pesawat | Deskripsi |
---|---|---|
Pemilik | Kontrol & Data | Akses penuh ke sarana kontrol sumber daya pencarian, termasuk kemampuan untuk menetapkan peran Azure. Hanya peran Pemilik yang dapat mengaktifkan atau menonaktifkan opsi autentikasi atau mengelola peran untuk pengguna lain. Admin langganan menjadi anggota secara default. Pada bidang data, peran ini memiliki akses yang sama dengan peran Kontributor Layanan Pencarian. Ini termasuk akses ke semua tindakan bidang data kecuali kemampuan untuk mengkueri atau mengindeks dokumen. |
Kontributor | Kontrol & Data | Tingkat akses sarana kontrol yang sama dengan Pemilik, dikurangi kemampuan untuk menetapkan peran atau mengubah opsi autentikasi. Pada bidang data, peran ini memiliki akses yang sama dengan peran Kontributor Layanan Pencarian. Ini termasuk akses ke semua tindakan bidang data kecuali kemampuan untuk mengkueri atau mengindeks dokumen. |
Pembaca | Kontrol & Data | Membaca akses di seluruh layanan, termasuk metrik pencarian, metrik konten (penyimpanan yang digunakan, jumlah objek), dan definisi objek sumber daya data plane (indeks, pengindeks, dan sebagainya). Namun, itu tidak dapat membaca kunci API atau membaca konten dalam indeks. |
Kontributor Layanan Pencarian | Kontrol & Data | Akses baca-tulis ke definisi objek (indeks, alias, peta sinonim, pengindeks, sumber data, dan set keterampilan). Peran ini untuk pengembang yang membuat objek, dan untuk administrator yang mengelola layanan pencarian dan objeknya, tetapi tanpa akses ke konten indeks. Gunakan peran ini untuk membuat, menghapus, dan mencantumkan indeks, mendapatkan definisi indeks, mendapatkan informasi layanan (statistik dan kuota), penganalisis pengujian, membuat dan mengelola peta sinonim, pengindeks, sumber data, dan set keterampilan. Lihat Microsoft.Search/searchServices/* untuk daftar izin. |
Kontributor Data Indeks Pencarian | Data | Akses baca-tulis ke konten dalam indeks. Peran ini untuk pengembang atau pemilik indeks yang perlu mengimpor, me-refresh, atau mengkueri koleksi dokumen indeks. Peran ini tidak mendukung pembuatan atau manajemen indeks. Secara default, peran ini adalah untuk semua indeks pada layanan pencarian. Lihat Memberikan akses ke satu indeks untuk mempersempit cakupan. |
Pembaca Data Indeks Pencarian | Data | Akses baca-saja untuk mengkueri indeks pencarian. Peran ini untuk aplikasi dan pengguna yang menjalankan kueri. Peran ini tidak mendukung akses baca ke definisi objek. Misalnya, Anda tidak dapat membaca definisi indeks pencarian atau mendapatkan statistik layanan pencarian. Secara default, peran ini adalah untuk semua indeks pada layanan pencarian. Lihat Memberikan akses ke satu indeks untuk mempersempit cakupan. |
Gabungkan peran ini untuk mendapatkan izin yang memadai untuk kasus penggunaan Anda.
Catatan
Jika Anda menonaktifkan akses berbasis peran Azure, peran bawaan untuk sarana kontrol (Pemilik, Kontributor, Pembaca) terus tersedia. Menonaktifkan akses berbasis peran hanya menghapus izin terkait data yang terkait dengan peran tersebut. Jika peran sarana data dinonaktifkan, Kontributor Layanan Pencarian setara dengan Kontributor sarana kontrol.
Menetapkan peran
Di bagian ini, tetapkan peran untuk:
-
Peran ID Owner
8e3af657-a8ff-443c-a75c-2fe8c4bcb635 Contributor
b24988ac-6180-42a0-ab88-20f7382dd24c Reader
acdd72a7-3385-48ef-bd42-f606fba81ae7 Pengembangan atau akses tulis ke layanan pencarian
Tugas Peran ID Operasi CRUD Search Service Contributor
7ca78c08-252a-4471-8644-bb5ff32d4ba0 Memuat dokumen, menjalankan pekerjaan pengindeksan Search Index Data Contributor
8ebe5a00-799e-43f5-93ac-243d3dce84a7 Mengkueri indeks Search Index Data Reader
1407120a-92aa-4202-b7e9-c0e197c71c8f -
Peran ID Search Index Data Reader
dengan PowerShell1407120a-92aa-4202-b7e9-c0e197c71c8f
Menetapkan peran untuk administrasi layanan
Sebagai administrator layanan, Anda dapat membuat dan mengonfigurasi layanan pencarian, dan melakukan semua operasi sarana kontrol yang dijelaskan dalam REST API Manajemen atau pustaka klien yang setara. Bergantung pada perannya, Anda juga dapat melakukan sebagian besar tugas REST API Pencarian bidang data.
Masuk ke portal Azure.
Buka layanan pencarian Anda.
Pilih Kontrol akses (IAM) di panel navigasi kiri.
Pilih + Tambahkan>Tambahkan penetapan peran.
Pilih peran yang berlaku:
- Pemilik (akses penuh ke semua bidang data dan operasi sarana kontrol, kecuali untuk izin kueri)
- Kontributor (sama seperti Pemilik, kecuali izin untuk menetapkan peran)
- Pembaca (dapat diterima untuk memantau dan melihat metrik)
Pada tab Anggota , pilih identitas pengguna atau grup Microsoft Entra.
Di tab Tinjau + tetapkan, pilih Tinjau + tetapkan untuk menetapkan peran.
Menetapkan peran untuk pengembangan
Penetapan peran bersifat global di seluruh layanan pencarian. Untuk mencakup izin ke satu indeks, gunakan PowerShell atau Azure CLI untuk membuat peran kustom.
Kombinasi peran lain yang menyediakan akses penuh adalah Kontributor atau Pemilik, ditambah Pembaca Data Indeks Pencarian.
Penting
Jika Anda mengonfigurasi akses berbasis peran untuk layanan atau indeks dan Anda juga menyediakan kunci API atas permintaan, layanan pencarian menggunakan kunci API untuk mengautentikasi.
Masuk ke portal Azure.
Buka layanan pencarian Anda.
Pilih Kontrol akses (IAM) di panel navigasi kiri.
Pilih + Tambahkan>Tambahkan penetapan peran.
Pilih peran:
- Kontributor Layanan Pencarian (operasi create-read-update-delete pada indeks, pengindeks, set keterampilan, dan objek tingkat atas lainnya)
- Kontributor Data Indeks Pencarian (memuat dokumen dan menjalankan pekerjaan pengindeksan)
- Pembaca Data Indeks Pencarian (mengkueri indeks)
Kombinasi peran lain yang menyediakan akses penuh adalah Kontributor atau Pemilik, ditambah Pembaca Data Indeks Pencarian.
Pada tab Anggota , pilih identitas pengguna atau grup Microsoft Entra.
Di tab Tinjau + tetapkan, pilih Tinjau + tetapkan untuk menetapkan peran.
Ulangi untuk peran lain. Sebagian besar pengembang membutuhkan ketiganya.
Menetapkan peran untuk kueri baca-saja
Gunakan peran Pembaca Data Indeks Pencarian untuk aplikasi dan proses yang hanya memerlukan akses baca ke indeks.
Ini adalah peran yang sangat spesifik. Ini memberikan akses GET atau POST ke kumpulan dokumen indeks pencarian untuk pencarian, lengkapi otomatis, dan saran. Ini tidak mendukung operasi GET atau LIST pada indeks atau objek tingkat atas lainnya, atau statistik layanan GET.
Bagian ini menyediakan langkah-langkah dasar untuk menyiapkan penetapan peran dan berada di sini untuk kelengkapan, tetapi sebaiknya Gunakan Azure AI Search tanpa kunci untuk instruksi komprehensif tentang mengonfigurasi aplikasi Anda untuk akses berbasis peran.
Masuk ke portal Azure.
Buka layanan pencarian Anda.
Pilih Kontrol akses (IAM) di panel navigasi kiri.
Pilih + Tambahkan>Tambahkan penetapan peran.
Pilih peran Pembaca Data Indeks Pencarian.
Pada tab Anggota , pilih identitas pengguna atau grup Microsoft Entra. Jika Anda menyiapkan izin untuk layanan lain, Anda mungkin menggunakan sistem atau identitas yang dikelola pengguna. Pilih opsi tersebut jika penetapan peran adalah untuk identitas layanan.
Di tab Tinjau + tetapkan, pilih Tinjau + tetapkan untuk menetapkan peran.
Menguji penetapan peran
Gunakan klien untuk menguji penetapan peran. Ingatlah bahwa peran adalah peran kumulatif dan diwariskan yang terlingkup ke tingkat langganan atau grup sumber daya tidak dapat dihapus atau ditolak di tingkat sumber daya (layanan pencarian).
Konfigurasikan aplikasi Anda untuk koneksi tanpa kunci dan siapkan penetapan peran sebelum pengujian.
Masuk ke portal Azure.
Buka layanan pencarian Anda.
Di halaman Ringkasan, pilih Indeks:
Kontributor Layanan Pencarian dapat menampilkan dan membuat objek apa pun, tetapi tidak dapat memuat dokumen atau mengkueri indeks. Untuk memverifikasi izin, buat indeks pencarian.
Kontributor Data Indeks Pencarian dapat memuat dokumen. Tidak ada opsi muat dokumen di portal di luar wizard Impor data, tetapi Anda dapat mengatur ulang dan menjalankan pengindeks untuk mengonfirmasi izin pemuatan dokumen.
Pembaca Data Indeks Pencarian dapat mengkueri indeks. Untuk memverifikasi izin, gunakan Penjelajah pencarian. Anda seharusnya dapat mengirim kueri dan melihat hasil, tetapi Anda seharusnya tidak dapat melihat definisi indeks atau membuatnya.
Uji sebagai pengguna saat ini
Jika Anda sudah menjadi Kontributor atau Pemilik layanan pencarian, Anda dapat menyajikan token pembawa untuk identitas pengguna Anda untuk autentikasi ke Azure AI Search.
Dapatkan token pembawa untuk pengguna saat ini menggunakan Azure CLI:
az account get-access-token --scope https://search.azure.com/.default
Atau dengan menggunakan PowerShell:
Get-AzAccessToken -ResourceUrl https://search.azure.com
Tempelkan variabel ini ke dalam file teks baru di Visual Studio Code.
@baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE @index-name = PASTE-YOUR-INDEX-NAME-HERE @token = PASTE-YOUR-TOKEN-HERE
Tempelkan lalu kirim permintaan untuk mengonfirmasi akses. Berikut adalah salah satu yang mengkueri indeks hotel-quickstart
POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2024-07-01 HTTP/1.1 Content-type: application/json Authorization: Bearer {{token}} { "queryType": "simple", "search": "motel", "filter": "", "select": "HotelName,Description,Category,Tags", "count": true }
Memberikan akses ke satu indeks
Dalam beberapa skenario, Anda mungkin ingin membatasi akses aplikasi ke satu sumber daya, seperti indeks.
Portal saat ini tidak mendukung penetapan peran pada tingkat granularitas ini, tetapi dapat dilakukan dengan PowerShell atau Azure CLI.
Di PowerShell, gunakan New-AzRoleAssignment, memberikan nama pengguna atau grup Azure, dan cakupan penugasan.
Azure
Muat modul danAzureAD
dan sambungkan ke akun Azure Anda:Import-Module -Name Az Import-Module -Name AzureAD Connect-AzAccount
Tambahkan penetapan peran yang terlingkup ke indeks individual:
New-AzRoleAssignment -ObjectId <objectId> ` -RoleDefinitionName "Search Index Data Contributor" ` -Scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"
Membuat peran kustom
Jika peran bawaan tidak memberikan kombinasi izin yang tepat, Anda dapat membuat peran kustom untuk mendukung operasi yang Anda butuhkan.
Contoh ini mengkloning Pembaca Data Indeks Pencarian lalu menambahkan kemampuan untuk mencantumkan indeks berdasarkan nama. Biasanya, mencantumkan indeks pada layanan pencarian dianggap sebagai hak administratif.
Langkah-langkah ini berasal dari Membuat atau memperbarui peran kustom Azure menggunakan portal Azure. Kloning dari peran yang ada didukung di halaman layanan pencarian.
Langkah-langkah ini membuat peran kustom yang menambah hak kueri pencarian untuk menyertakan daftar indeks menurut nama. Biasanya, mencantumkan indeks dianggap sebagai fungsi admin.
Di portal Azure, navigasikan ke layanan pencarian Anda.
Di panel navigasi kiri, pilih Kontrol Akses (IAM).
Di bilah tindakan, pilih Peran.
Klik kanan Pembaca Data Indeks Pencarian (atau peran lain) dan pilih Kloning untuk membuka wizard Buat peran kustom.
Pada tab Dasar, berikan nama untuk peran kustom, seperti "Search Index Data Explorer", lalu pilih Berikutnya.
Pada tab Izin, pilih Tambahkan izin.
Pada tab Tambahkan izin, cari lalu pilih petak peta Microsoft Search .
Atur izin untuk peran kustom Anda. Di bagian atas halaman, menggunakan pilihan Tindakan default:
- Di bawah Microsoft.Search/operations, pilih Baca : Cantumkan semua operasi yang tersedia.
- Di bawah Microsoft.Search/searchServices/indexes, pilih Baca : Baca Indeks.
Pada halaman yang sama, beralihlah ke Tindakan data dan di bawah Microsoft.Search/searchServices/indexes/documents, pilih Baca : Baca Dokumen.
Definisi JSON terlihat seperti contoh berikut:
{ "properties": { "roleName": "search index data explorer", "description": "", "assignableScopes": [ "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc" ], "permissions": [ { "actions": [ "Microsoft.Search/operations/read", "Microsoft.Search/searchServices/indexes/read" ], "notActions": [], "dataActions": [ "Microsoft.Search/searchServices/indexes/documents/read" ], "notDataActions": [] } ] } }
Pilih Tinjau + buat untuk membuat peran. Sekarang Anda dapat menetapkan pengguna dan grup ke peran tersebut.
Akses Bersyarat
Kami merekomendasikan Akses Bersyarkat Microsoft Entra jika Anda perlu menerapkan kebijakan organisasi, seperti autentikasi multifaktor.
Untuk mengaktifkan kebijakan Akses Bersyar untuk Pencarian Azure AI, ikuti langkah-langkah berikut:
Cari Microsoft Entra Conditional Access.
Pilih Kebijakan.
Pilih Kebijakan baru.
Di bagian Aplikasi cloud atau tindakan kebijakan, tambahkan Azure AI Search sebagai aplikasi cloud tergantung pada cara Anda ingin menyiapkan kebijakan Anda.
Perbarui parameter kebijakan yang tersisa. Misalnya, tentukan pengguna dan grup mana yang berlaku untuk kebijakan ini.
Simpan kebijakan.
Penting
Jika layanan pencarian Anda memiliki identitas terkelola yang ditetapkan, layanan pencarian tertentu akan muncul sebagai aplikasi cloud yang dapat disertakan atau dikecualikan sebagai bagian dari kebijakan Akses Bersyarat. Kebijakan Akses Bersyarkat tidak dapat diberlakukan pada layanan pencarian tertentu. Sebagai gantinya, pastikan Anda memilih aplikasi cloud Azure AI Search umum.
Batasan
Kontrol akses berbasis peran dapat meningkatkan latensi beberapa permintaan. Setiap kombinasi unik sumber daya layanan (indeks, pengindeks, dll.) dan perwakilan layanan memicu pemeriksaan otorisasi. Pemeriksaan otorisasi ini dapat menambahkan hingga 200 milidetik latensi per permintaan.
Dalam kasus yang jarang terjadi di mana permintaan berasal dari sejumlah besar perwakilan layanan yang berbeda, semua menargetkan sumber daya layanan yang berbeda (indeks, pengindeks, dll.), dimungkinkan bagi pemeriksaan otorisasi untuk menghasilkan pembatasan. Pembatasan hanya akan terjadi jika ratusan kombinasi unik sumber daya layanan pencarian dan perwakilan layanan digunakan dalam hitungan detik.
Pemecahan masalah kontrol akses berbasis peran
Saat mengembangkan aplikasi yang menggunakan kontrol akses berbasis peran untuk autentikasi, beberapa masalah umum mungkin terjadi:
Jika token otorisasi berasal dari identitas terkelola dan izin yang sesuai baru-baru ini ditetapkan, mungkin perlu waktu beberapa jam agar penetapan izin ini berlaku.
Konfigurasi default untuk layanan pencarian adalah autentikasi berbasis kunci. Jika Anda tidak mengubah pengaturan kunci default ke Kontrol akses berbasis Peran atau Keduanya, maka semua permintaan yang menggunakan autentikasi berbasis peran secara otomatis ditolak terlepas dari izin yang mendasar.