Mengaktifkan atau menonaktifkan kontrol akses berbasis peran di Pencarian Azure AI

Note

Pencarian Azure AI tersedia melalui portal Azure, REST API, dan Azure SDK. Ini juga mendukung Foundry IQ, lapisan pengetahuan terkelola yang mengubah konten perusahaan menjadi pangkalan pengetahuan yang dapat digunakan kembali dan sadar izin untuk agen di portal Microsoft Foundry.

Artikel ini menjelaskan cara mengaktifkan kontrol akses berbasis peran (RBAC) untuk operasi sarana data di Pencarian Azure AI. Dengan RBAC diaktifkan, Anda dapat menggunakan autentikasi ID Microsoft Entra alih-alih kunci API.

Penting

Saat Anda membuat layanan pencarian, autentikasi berbasis kunci adalah default, tetapi ini bukan opsi yang paling aman. Kami menyarankan agar Anda menggantinya dengan akses berbasis peran seperti yang dijelaskan dalam artikel ini.

Hanya peran data plane yang dapat dinonaktifkan. Peran untuk administrasi layanan (pengaturan kontrol) sudah terintegrasi dan tidak dapat diaktifkan atau dinonaktifkan.

Jika Anda mengamati aktivitas terkait kunci, seperti Mengambil Kunci Admin, di Log Aktivitas pada layanan pencarian yang hanya untuk peran tertentu, tindakan tersebut dimulai pada lapisan kontrol dan tidak memengaruhi konten atau operasi terkait konten Anda.

Prasyarat

Layanan pencarian di wilayah mana pun, pada tingkat apa pun, termasuk gratis.
Pemilik, Administrator Akses Pengguna, atau peran kustom dengan izin Microsoft.Authorization/roleAssignments/write untuk mengaktifkan RBAC.
Setelah mengaktifkan RBAC, Anda memerlukan peran sarana data untuk mengakses konten: Kontributor Layanan Pencarian, Kontributor Data Indeks Pencarian, dan Pembaca Data Indeks Pencarian. Lihat Menetapkan peran untuk detailnya.

Mengaktifkan akses berbasis peran untuk operasi data plane

Konfigurasikan layanan pencarian Anda untuk mengenali header otorisasi pada permintaan data yang menyediakan token akses OAuth2.

Saat Anda mengaktifkan peran untuk bidang data, perubahan akan segera efektif, tetapi tunggu beberapa detik sebelum menetapkan peran.

Mode kegagalan default untuk permintaan yang tidak sah adalah http401WithBearerChallenge. Atau, Anda dapat mengatur mode kegagalan ke http403.

Buka layanan pencarian Anda di portal Microsoft Azure.
Pilih Pengaturan lalu pilih Kunci di panel kiri.

Pilih Kontrol berbasis peran. Hanya pilih Keduanya jika Anda saat ini menggunakan kunci dan memerlukan waktu untuk transisi klien ke kontrol akses berbasis peran.

Opsi	Deskripsi
Kunci API (bawaan)	Memerlukan kunci API pada header permintaan untuk otorisasi.
Kontrol akses berbasis peran (disarankan)	Memerlukan keanggotaan untuk penetapan peran guna menyelesaikan tugas. Ini juga memerlukan header otorisasi pada permintaan.
Keduanya	Permintaan valid menggunakan kunci API atau kontrol akses berbasis peran, tetapi jika Anda menyediakan keduanya dalam permintaan yang sama, kunci API digunakan.

Sebagai administrator, jika Anda memilih pendekatan hanya peran, tetapkan peran bidang data ke akun pengguna Anda untuk memulihkan akses administratif penuh atas operasi bidang data di portal Azure. Peran termasuk Kontributor Layanan Pencarian, Kontributor Data Indeks Pencarian, dan Pembaca Data Indeks Pencarian. Anda memerlukan dua peran pertama jika Anda menginginkan akses yang setara.

Terkadang perlu waktu lima hingga sepuluh menit agar penetapan peran diterapkan. Hingga itu terjadi, pesan berikut muncul di halaman portal Azure yang digunakan untuk operasi sarana data.

Jalankan skrip ini hanya untuk mendukung peran:

az search service update \
  --name YOUR-SEARCH-SERVICE-NAME \
  --resource-group YOUR-RESOURCE-GROUP-NAME \
  --disable-local-auth

Atau, jalankan skrip ini untuk mendukung kunci dan peran:

az search service update \
  --name YOUR-SEARCH-SERVICE-NAME \
  --resource-group YOUR-RESOURCE-GROUP-NAME \
  --aad-auth-failure-mode http401WithBearerChallenge \
  --auth-options aadOrApiKey

Referensi:pembaruan layanan pencarian az

Untuk informasi selengkapnya, lihat Mengelola layanan Pencarian Azure AI Anda dengan Azure CLI.

Jalankan perintah ini untuk mengatur jenis autentikasi ke peran saja:

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

Atau, jalankan perintah ini untuk mendukung kunci dan peran:

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -AuthOption AadOrApiKey

Referensi:Set-AzSearchService

Untuk informasi selengkapnya, lihat Mengelola layanan Pencarian Azure AI Anda dengan PowerShell.

Gunakan Management REST API Create atau Update Service untuk mengonfigurasi layanan Anda untuk kontrol akses berbasis peran.

Semua panggilan ke API REST Manajemen diautentikasi melalui ID Microsoft Entra. Untuk bantuan dalam menyiapkan permintaan terautentikasi, lihat Mengelola Pencarian Azure AI menggunakan REST.

Dapatkan pengaturan layanan sehingga Anda dapat meninjau konfigurasi saat ini.

GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01

Gunakan PATCH untuk memperbarui konfigurasi layanan. Modifikasi berikut memungkinkan kunci dan akses berbasis peran. Jika Anda menginginkan konfigurasi khusus peran, lihat Menonaktifkan kunci API.

Di bagian "properti", atur "authOptions" ke "aadOrApiKey". Properti "disableLocalAuth" harus bernilai "false" untuk menetapkan "authOptions".

Secara opsional, atur "aadAuthFailureMode" untuk menentukan apakah 401 dikembalikan alih-alih 403 saat autentikasi gagal. Nilai yang valid adalah "http401WithBearerChallenge" atau "http403".
```
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2025-05-01
{
    "properties": {
        "disableLocalAuth": false,
        "authOptions": {
            "aadOrApiKey": {
                "aadAuthFailureMode": "http401WithBearerChallenge"
            }
        }
    }
}
```
Permintaan 200 OK yang berhasil akan mengembalikan konfigurasi layanan yang diperbarui.

Referensi:Layanan - Membuat atau Memperbarui

Menonaktifkan kontrol akses berbasis peran

Dimungkinkan untuk menonaktifkan kontrol akses berbasis peran untuk operasi sarana data dan menggunakan autentikasi berbasis kunci sebagai gantinya. Anda mungkin melakukan ini sebagai bagian dari alur kerja pengujian, misalnya untuk mengesampingkan masalah izin.

Untuk menonaktifkan kontrol akses berbasis peran di portal Azure:

Buka layanan pencarian Anda di portal Microsoft Azure.
Pilih Pengaturan lalu pilih Kunci di panel kiri.
Pilih Tombol API.

Menonaktifkan autentikasi kunci API

Akses kunci, atau autentikasi lokal, dapat dinonaktifkan pada layanan Anda jika Anda secara eksklusif menggunakan peran bawaan dan autentikasi Microsoft Entra. Menonaktifkan kunci API menyebabkan layanan pencarian menolak semua permintaan terkait data yang meneruskan kunci API di header.

Kunci API admin dapat dinonaktifkan, tetapi tidak dihapus. Kunci API kueri dapat dihapus.

Izin Pemilik atau Kontributor diperlukan untuk menonaktifkan fitur keamanan.

Buka layanan pencarian Anda di portal Microsoft Azure.
Di panel navigasi kiri, pilih Kunci.
Pilih Kontrol akses berbasis peran.

Perubahan segera efektif, tetapi tunggu beberapa detik sebelum pengujian. Dengan asumsi Anda memiliki izin untuk menetapkan peran sebagai anggota Pemilik, administrator layanan, atau koadministrator, Anda dapat menggunakan fitur portal untuk menguji akses berbasis peran.

Untuk menonaktifkan autentikasi berbasis kunci, atur -disableLocalAuth ke true. Ini adalah sintaks yang sama dengan skrip "aktifkan peran saja" yang disajikan di bagian sebelumnya.

az search service update \
  --name YOUR-SEARCH-SERVICE-NAME \
  --resource-group YOUR-RESOURCE-GROUP-NAME \
  --disable-local-auth

Untuk mengaktifkan kembali autentikasi kunci, atur -disableLocalAuth ke false. Layanan pencarian secara otomatis kembali menerima kunci API pada permintaan (dengan asumsi bahwa sudah ditentukan).

Untuk informasi selengkapnya, lihat Mengelola layanan Pencarian Azure AI Anda dengan Azure CLI.

Untuk menonaktifkan autentikasi berbasis kunci, atur DisableLocalAuth ke true. Ini adalah sintaks yang sama dengan skrip "aktifkan peran saja" yang disajikan di bagian sebelumnya.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

Untuk mengaktifkan kembali autentikasi kunci, atur DisableLocalAuth ke false. Layanan pencarian secara otomatis kembali menerima kunci API pada permintaan (dengan asumsi bahwa sudah ditentukan).

Untuk informasi selengkapnya, lihat Mengelola layanan Pencarian Azure AI Anda dengan PowerShell.

Untuk menonaktifkan autentikasi berbasis kunci, atur "disableLocalAuth" ke true.

Dapatkan pengaturan layanan sehingga Anda dapat meninjau konfigurasi saat ini.

GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01

Gunakan PATCH untuk memperbarui konfigurasi layanan. Modifikasi berikut menetapkan "authOptions" ke null.

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2025-05-01
{
    "properties": {
        "disableLocalAuth": true
    }
}

Permintaan 200 OK yang berhasil akan mengembalikan konfigurasi layanan yang diperbarui.

Untuk mengaktifkan kembali autentikasi kunci, atur "disableLocalAuth" ke false. Layanan pencarian secara otomatis kembali menerima kunci API pada permintaan (dengan asumsi bahwa sudah ditentukan).

Referensi:Layanan - Membuat atau Memperbarui

Langkah berikutnya

Menyiapkan peran untuk akses ke layanan pencarian

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-03-13