Mengaktifkan atau menonaktifkan kontrol akses berbasis peran di Azure AI Search

Artikel
01/18/2025

Azure AI Search mendukung autentikasi tanpa kunci dan berbasis kunci untuk semua operasi sarana kontrol dan sarana data. Anda dapat menggunakan autentikasi dan otorisasi ID Microsoft Entra untuk semua operasi sarana kontrol dan sarana data melalui kontrol akses berbasis peran (RBAC) Azure.

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.

Sebelum dapat menetapkan peran untuk akses data plane resmi ke Azure AI Search, Anda harus mengaktifkan kontrol akses berbasis peran pada layanan pencarian Anda. Peran untuk administrasi layanan (sarana kontrol) dibangun dan tidak dapat diaktifkan atau dinonaktifkan.

Catatan

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.

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 .

Mengaktifkan akses berbasis peran untuk operasi sarana data

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.

Masuk ke portal Azure dan navigasi ke layanan pencarian Anda.
Pilih Pengaturan lalu pilih Kunci di panel navigasi 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 (default)	Memerlukan kunci API pada header permintaan untuk otorisasi.
Kontrol akses berbasis peran (disarankan)	Memerlukan keanggotaan dalam penetapan peran untuk 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 khusus peran, tetapkan peran bidang data ke akun pengguna Anda untuk memulihkan akses administratif penuh melalui operasi sarana 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

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

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 Rest API 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=2023-11-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 false untuk mengatur "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=2023-11-01
{
    "properties": {
        "disableLocalAuth": false,
        "authOptions": {
            "aadOrApiKey": {
                "aadAuthFailureMode": "http401WithBearerChallenge"
            }
        }
    }
}
```

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:

Masuk ke portal Azure dan buka halaman layanan pencarian.
Pilih Pengaturan lalu pilih Kunci di panel navigasi 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.

Di portal Azure, navigasikan ke layanan pencarian Anda.
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 melanjutkan penerimaan kunci API pada permintaan secara otomatis (dengan asumsi mereka 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 melanjutkan penerimaan kunci API pada permintaan secara otomatis (dengan asumsi mereka 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=2023-11-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=2023-11-01
{
    "properties": {
        "disableLocalAuth": true
    }
}

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

Langkah berikutnya

Menyiapkan peran untuk akses ke layanan pencarian

Bagikan melalui