Koneksi ke Azure AI Search menggunakan kontrol akses berbasis peran

Azure menyediakan sistem otorisasi kontrol akses berbasis peran global untuk semua layanan yang berjalan di platform. 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

• Pemilik, Administrator Akses Pengguna, atau peran dengan izin Microsoft.Authorization/roleAssignments/write .

• Layanan pencarian di wilayah mana pun, pada tingkat mana pun.

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.

Mengaktifkan akses berbasis peran untuk operasi sarana data

Peran untuk administrasi layanan (sarana kontrol) adalah wajib. Peran untuk operasi data plane bersifat opsional. Anda harus mengaktifkan akses berbasis peran sebelum dapat menetapkan peran Kontributor Layanan Pencarian, Kontributor Data Indeks Pencarian, atau Pembaca Data Indeks Pencarian untuk operasi data.

Dalam langkah ini, konfigurasikan layanan pencarian Anda untuk mengenali header otorisasi pada permintaan sarana data yang menyediakan token akses OAuth2.

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 yang setara.

Portal Azure

1. Masuk ke portal Azure dan buka halaman layanan pencarian.

2. Di panel navigasi sebelah kiri, pilih Kunci.

   

3. Pilih Kontrol berbasis peran atau Keduanya jika Anda menginginkan fleksibilitas.

   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.

Perubahan segera efektif, tetapi tunggu beberapa detik sebelum menetapkan peran.

Saat Anda mengaktifkan kontrol akses berbasis peran, mode kegagalan adalah "http401WithBearerChallenge" jika otorisasi gagal.

REST API

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.

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

2. 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"
               }
           }
       }
   }
   

Perubahan segera efektif, tetapi tunggu beberapa detik sebelum menetapkan peran.

Saat Anda mengaktifkan kontrol akses berbasis peran, mode kegagalan adalah "http401WithBearerChallenge" jika otorisasi gagal.

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.

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:

• 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. Bergantung pada perannya, Anda juga dapat melakukan sebagian besar tugas REST API Pencarian bidang data.

Portal Azure

1. Masuk ke portal Azure.

2. Buka layanan pencarian Anda.

3. Pilih Kontrol akses (IAM) di panel navigasi kiri.

4. Pilih + Tambahkan>Tambahkan penetapan peran.

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

6. Pada tab Anggota , pilih identitas pengguna atau grup Microsoft Entra.

7. Di tab Tinjau + tetapkan, pilih Tinjau + tetapkan untuk menetapkan peran.

PowerShell

Saat Anda menggunakan PowerShell untuk menetapkan peran, panggil New-AzRoleAssignment, menyediakan nama pengguna atau grup Azure, dan cakupan penugasan.

Contoh ini membuat penetapan peran yang dilingkup ke layanan pencarian:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

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.

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.

Portal Azure

1. Masuk ke portal Azure.

2. Buka layanan pencarian Anda.

3. Pilih Kontrol akses (IAM) di panel navigasi kiri.

4. Pilih + Tambahkan>Tambahkan penetapan peran.

   

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

6. Pada tab Anggota , pilih identitas pengguna atau grup Microsoft Entra.

7. Di tab Tinjau + tetapkan, pilih Tinjau + tetapkan untuk menetapkan peran.

8. Ulangi untuk peran lain. Sebagian besar pengembang membutuhkan ketiganya.

PowerShell

Saat Anda menggunakan PowerShell untuk menetapkan peran, panggil New-AzRoleAssignment, menyediakan nama pengguna atau grup Azure, dan cakupan penugasan.

Contoh ini membuat penetapan peran yang dilingkup ke layanan pencarian:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Contoh ini membuat penetapan peran yang dilingkup ke indeks tertentu:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

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.

Portal Azure

1. Masuk ke portal Azure.

2. Buka layanan pencarian Anda.

3. Pilih Kontrol akses (IAM) di panel navigasi kiri.

4. Pilih + Tambahkan>Tambahkan penetapan peran.

5. Pilih peran Pembaca Data Indeks Pencarian.

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

7. Di tab Tinjau + tetapkan, pilih Tinjau + tetapkan untuk menetapkan peran.

PowerShell

Saat menggunakan PowerShell untuk menetapkan peran, panggil New-AzRoleAssignment, yang menyediakan nama pengguna atau grup Azure dan cakupan penetapan.

1. Dapatkan ID langganan Anda, grup sumber daya layanan pencarian, dan nama layanan pencarian.

2. Dapatkan pengidentifikasi objek layanan Azure Anda, seperti Azure OpenAI.

    Get-AzADServicePrincipal -SearchString <YOUR AZURE OPENAI RESOURCE NAME>
   

3. Dapatkan definisi peran dan tinjau izin untuk memastikan ini adalah peran yang Anda inginkan.

   Get-AzRoleDefinition -Name "Search Index Data Reader"
   

4. Buat penetapan peran, ganti nilai yang valid untuk tempat penampung.

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME
   

5. Berikut adalah contoh penetapan peran yang dilingkup ke indeks tertentu:

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID `
       -RoleDefinitionName "Search Index Data Reader" `
       -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME/indexes/YOUR-INDEX-NAME
   

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

Pastikan Anda mendaftarkan aplikasi klien dengan ID Microsoft Entra dan memiliki penetapan peran sebelum menguji akses.

Portal Azure

1. Masuk ke portal Azure.

2. Buka layanan pencarian Anda.

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

REST API

Pendekatan ini mengasumsikan Visual Studio Code dengan ekstensi klien REST.

1. Buka shell perintah untuk Azure CLI dan masuk ke langganan Azure Anda.

   az login
   

2. Dapatkan ID penyewa dan ID langganan Anda. ID digunakan sebagai variabel di langkah mendatang.

   az account show
   

3. Mendapatkan token akses.

   az account get-access-token --query accessToken --output tsv
   

4. Dalam file teks baru di Visual Studio Code, tempelkan dalam variabel ini:

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

5. Tempelkan lalu kirim permintaan yang menggunakan variabel yang telah Anda tentukan. Untuk peran "Pembaca Data Indeks Pencarian", Anda bisa mengirim kueri. Anda dapat menggunakan versi API yang didukung.

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

Untuk informasi selengkapnya tentang cara memperoleh token untuk lingkungan tertentu, lihat Mengelola azure AI layanan Pencarian dengan REST API dan pustaka autentikasi platform identitas Microsoft.

.NET

1. Gunakan paket Azure.Search.Documents.

2. Gunakan Azure.Identity untuk .NET untuk autentikasi token. Microsoft merekomendasikan DefaultAzureCredential() untuk sebagian besar skenario.

3. Berikut adalah contoh koneksi klien menggunakan DefaultAzureCredential().

   // Create a SearchIndexClient to send create/delete index commands
   SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
   
   // Create a SearchClient to load and query documents
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());
   

4. Berikut adalah contoh lain menggunakan kredensial rahasia klien:

   var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);
   

Python

1. Gunakan azure.search.documents (Azure SDK for Python).

2. Gunakan Azure.Identity untuk Python untuk autentikasi token.

3. Gunakan DefaultAzureCredential jika klien Python adalah aplikasi yang menjalankan sisi server. Aktifkan autentikasi interaktif jika aplikasi berjalan di browser.

4. Berikut contohnya:

   from azure.search.documents import SearchClient
   from azure.identity import DefaultAzureCredential
   
   credential = DefaultAzureCredential()
   endpoint = "https://<mysearch>.search.windows.net"
   index_name = "myindex"
   client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)
   

JavaScript

1. Gunakan @azure/search-documents (Azure SDK untuk JavaScript), versi 11.3.

2. Gunakan Azure.Identity untuk JavaScript untuk autentikasi token.

3. Jika Anda menggunakan React, gunakan InteractiveBrowserCredential untuk autentikasi Microsoft Entra ke Pencarian. Lihat Kapan menggunakan @azure/identity untuk detailnya.

Java

1. Gunakan azure-search-documents (Azure SDK for Java).

2. Gunakan Azure.Identity untuk Java untuk autentikasi token.

3. Microsoft merekomendasikan DefaultAzureCredential untuk aplikasi yang berjalan di Azure.

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.

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

2. Dalam file teks baru di Visual Studio Code, tempelkan dalam variabel ini:

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

3. 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=2023-11-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.

1. Azure Muat modul dan AzureAD dan sambungkan ke akun Azure Anda:

   Import-Module -Name Az
   Import-Module -Name AzureAD
   Connect-AzAccount
   

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

Portal Azure

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.

1. Di portal Azure, navigasikan ke layanan pencarian Anda.

2. Di panel navigasi kiri, pilih Kontrol Akses (IAM).

3. Di bilah tindakan, pilih Peran.

4. Klik kanan Pembaca Data Indeks Pencarian (atau peran lain) dan pilih Kloning untuk membuka wizard Buat peran kustom.

5. Pada tab Dasar, berikan nama untuk peran kustom, seperti "Search Index Data Explorer", lalu pilih Berikutnya.

6. Pada tab Izin, pilih Tambahkan izin.

7. Pada tab Tambahkan izin, cari lalu pilih petak peta Microsoft Search .

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

9. 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": []
            }
        ]
      }
    }
   

10. Pilih Tinjau + buat untuk membuat peran. Sekarang Anda dapat menetapkan pengguna dan grup ke peran tersebut.

Azure PowerShell

Contoh PowerShell memperlihatkan sintaks JSON untuk membuat peran kustom yang merupakan kloning Pembaca Data Indeks Pencarian, tetapi dengan kemampuan untuk mencantumkan semua indeks berdasarkan nama.

1. Tinjau daftar izin atom untuk menentukan izin mana yang Anda butuhkan. Untuk contoh ini, Anda memerlukan hal berikut:

   "Microsoft.Search/operations/read",
   "Microsoft.Search/searchServices/read",
   "Microsoft.Search/searchServices/indexes/read"
   

2. Siapkan sesi PowerShell untuk membuat peran kustom. Untuk instruksi mendetail, lihat Azure PowerShell

3. Berikan definisi peran sebagai dokumen JSON. Contoh berikut menunjukkan sintaks untuk membuat peran kustom dengan PowerShell.

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

Catatan

Jika cakupan yang dapat ditetapkan berada di tingkat indeks, tindakan data harus "Microsoft.Search/searchServices/indexes/documents/read".

REST API

1. Tinjau daftar izin atom untuk menentukan izin mana yang Anda butuhkan.

2. Lihat Membuat atau memperbarui peran kustom Azure menggunakan REST API untuk langkah-langkahnya.

3. Kloning atau buat peran, atau gunakan JSON untuk menentukan peran kustom (lihat tab PowerShell untuk sintaks JSON).

Azure CLI

1. Tinjau daftar izin atom untuk menentukan izin mana yang Anda butuhkan.

2. Lihat Membuat atau memperbarui peran kustom Azure menggunakan Azure CLI untuk langkah-langkahnya.

3. Kloning atau buat peran, atau gunakan JSON untuk menentukan peran kustom (lihat tab PowerShell untuk sintaks JSON).

Menonaktifkan autentikasi kunci API

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

Catatan

Kunci API admin hanya dapat dinonaktifkan, bukan dihapus. Kunci API kueri dapat dihapus.

Izin Pemilik atau Kontributor diperlukan untuk menonaktifkan fitur.

Untuk menonaktifkan autentikasi berbasis kunci, gunakan portal Azure atau REST API Manajemen.

Portal

1. Di portal Azure, navigasikan ke layanan pencarian Anda.

2. Di panel navigasi kiri, pilih Kunci.

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

REST API

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

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

2. Gunakan PATCH untuk memperbarui konfigurasi layanan. Modifikasi berikut akan mengatur "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
       }
   }
   

Permintaan yang hanya menyertakan kunci API, tanpa token pembawa, gagal dengan HTTP 401.

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

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:

1. Masuk ke portal Microsoft Azure.

2. Cari Microsoft Entra Conditional Access.

3. Pilih Kebijakan.

4. Pilih Kebijakan baru.

5. Di bagian Aplikasi cloud atau tindakan kebijakan, tambahkan Azure AI Search sebagai aplikasi cloud tergantung pada cara Anda ingin menyiapkan kebijakan Anda.

6. Perbarui parameter kebijakan yang tersisa. Misalnya, tentukan pengguna dan grup mana yang berlaku untuk kebijakan ini.

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