Menyambungkan ke Azure AI Search menggunakan peran
Azure menyediakan autentikasi global dan kontrol akses berbasis peran melalui ID Microsoft Entra untuk semua layanan yang berjalan di platform. Dalam artikel ini, pelajari peran mana yang menyediakan akses ke konten pencarian dan administrasi di Azure AI Search.
Di Azure AI Search, Anda dapat menetapkan peran Azure untuk:
- Administrasi layanan
- Pengembangan atau akses tulis ke layanan pencarian
- Akses baca-saja untuk kueri
- Akses terlingkup ke satu indeks
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, Administrator Kontrol Akses berbasis Peran, atau peran kustom dengan izin Microsoft.Authorization/roleAssignments/write .
Cara menetapkan peran di portal Azure
Langkah-langkah berikut berfungsi untuk semua penetapan peran.
Masuk ke portal Azure.
Buka layanan pencarian Anda.
Aktifkan akses berbasis peran.
Pilih Kontrol akses (IAM) di panel navigasi kiri.
Pilih + Tambahkan>penetapan peran untuk memulai wizard Tambahkan penetapan peran.
Pilih peran. Anda dapat menetapkan beberapa prinsip keamanan, baik pengguna atau identitas terkelola ke peran dalam satu melewati wizard, tetapi Anda harus mengulangi langkah-langkah ini untuk setiap peran yang Anda tentukan.
Pada tab Anggota , pilih identitas pengguna atau grup Microsoft Entra. Jika Anda menyiapkan izin untuk layanan Azure lain, pilih sistem atau identitas yang dikelola pengguna.
Di tab Tinjau + tetapkan, pilih Tinjau + tetapkan untuk menetapkan peran.
Peran bawaan yang digunakan dalam pencarian
Bidang data mengacu pada operasi terhadap titik akhir layanan pencarian, seperti pengindeksan atau kueri, atau operasi lain yang ditentukan dalam REST API Layanan Pencarian atau pustaka klien Azure SDK yang setara.
Sarana kontrol mengacu pada manajemen sumber daya Azure, seperti membuat atau mengonfigurasi layanan pencarian.
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.
Ringkasan
Izin | Pembaca Data Indeks Pencarian | Kontributor Data Indeks Pencarian | Kontributor Layanan Pencarian | Pemilik/Kontributor | Pembaca |
---|---|---|---|---|---|
Menampilkan sumber daya di portal Azure | ❌ | ❌ | ✅ | ✅ | ✅ |
Menampilkan properti/metrik/titik akhir sumber daya | ❌ | ❌ | ✅ | ✅ | ✅ |
Mencantumkan semua objek pada sumber daya | ❌ | ❌ | ✅ | ✅ | ✅ |
Kuota akses dan statistik layanan | ❌ | ❌ | ✅ | ✅ | ❌ |
Membaca/mengkueri indeks | ✅ | ✅ | ❌ | ❌ | ❌ |
Mengunggah data untuk pengindeksan | ❌ | ✅ | ❌ | ❌ | ❌ |
Membuat atau mengedit indeks/alias | ❌ | ❌ | ✅ | ✅ | ❌ |
Membuat, mengedit, dan menjalankan pengindeks/sumber data/set keterampilan | ❌ | ❌ | ✅ | ✅ | ❌ |
Membuat atau mengedit peta sinonim | ❌ | ❌ | ✅ | ✅ | ❌ |
Membuat atau mengedit sesi debug | ❌ | ❌ | ✅ | ✅ | ❌ |
Membuat atau mengelola penyebaran | ❌ | ❌ | ✅ | ✅ | ❌ |
Membuat atau mengonfigurasi sumber daya Azure AI Search | ❌ | ❌ | ✅ | ✅ | ❌ |
Lihat/Salin/Regenerasi kunci di bawah Kunci | ❌ | ❌ | ✅ | ✅ | ❌ |
Melihat peran/kebijakan/definisi | ❌ | ❌ | ✅ | ✅ | ❌ |
Mengatur opsi autentikasi | ❌ | ❌ | ✅ | ✅ | ❌ |
Mengonfigurasi koneksi privat | ❌ | ❌ | ✅ | ✅ | ❌ |
Mengonfigurasi keamanan jaringan | ❌ | ❌ | ✅ | ✅ | ❌ |
Pemilik dan Kontributor memberikan izin yang sama, kecuali bahwa hanya Pemilik yang dapat menetapkan peran.
Pemilik dan Kontributor dapat membuat, membaca, memperbarui, dan menghapus objek di portal Azure jika kunci API diaktifkan. portal Azure menggunakan kunci pada panggilan internal ke API data plane. Di Anda kemudian mengonfigurasi Azure AI Search untuk menggunakan "peran saja", maka Pemilik dan Kontributor tidak akan dapat mengelola objek di portal Azure hanya menggunakan penetapan peran tersebut. Solusinya adalah menetapkan lebih banyak peran, seperti Pembaca Data Indeks Pencarian, Kontributor Data Indeks Pencarian, dan Kontributor Layanan Pencarian.
Menetapkan peran
Di bagian ini, tetapkan peran untuk:
- Administrasi layanan
- Pengembangan atau akses tulis ke layanan pencarian
- Akses baca-saja untuk kueri
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. Jika Anda adalah Pemilik atau Kontributor, Anda juga dapat melakukan sebagian besar tugas REST API Pencarian bidang data di portal Azure.
Peran | ID |
---|---|
Owner |
8e3af657-a8ff-443c-a75c-2fe8c4bcb635 |
Contributor |
b24988ac-6180-42a0-ab88-20f7382dd24c |
Reader |
acdd72a7-3385-48ef-bd42-f606fba81ae7 |
Masuk ke portal Azure.
Tetapkan peran ini:
- 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)
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.
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 |
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.
Tetapkan peran ini:
- 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)
Menetapkan peran untuk kueri baca-saja
Gunakan peran Pembaca Data Indeks Pencarian untuk aplikasi dan proses yang hanya memerlukan akses baca ke indeks.
Peran | ID |
---|---|
Search Index Data Reader
dengan PowerShell |
1407120a-92aa-4202-b7e9-c0e197c71c8f |
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.
Tetapkan peran Pembaca Data Indeks Pencarian.
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 Azure 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 Azure 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.
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.