Mengaktifkan atau menonaktifkan kontrol akses berbasis peran di Azure AI Search

Artikel
06/20/2024

Sebelum Anda dapat menetapkan peran untuk akses resmi ke Azure AI Search, aktifkan kontrol akses berbasis peran pada layanan pencarian Anda.

Akses berbasis peran untuk operasi sarana data bersifat opsional, tetapi direkomendasikan sebagai opsi yang lebih aman. Alternatifnya adalah autentikasi berbasis kunci, yang merupakan default.

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 Pencarian atau pustaka klien Azure SDK yang setara.

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 buka halaman layanan pencarian.
Pilih Pengaturan lalu pilih Kunci di panel navigasi kiri.

Pilih Kontrol berbasis peran atau 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	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 ketiga peran 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 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.

Balikkan langkah-langkah yang Anda ikuti sebelumnya untuk mengaktifkan akses berbasis peran.

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).

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.

Langkah berikutnya

Menyiapkan peran untuk akses ke layanan pencarian

Bagikan melalui