Mengotorisasi akses ke aplikasi pencarian menggunakan ID Microsoft Entra

Aplikasi pencarian yang dibangun di Azure AI Search sekarang dapat menggunakan platform identitas Microsoft untuk akses yang diautentikasi dan diotorisasi. Di Azure, idP adalah ID Microsoft Entra. Manfaat utama menggunakan ID Microsoft Entra adalah kredensial dan kunci API Anda tidak perlu lagi disimpan dalam kode Anda. Microsoft Entra mengautentikasi prinsip keamanan (pengguna, grup, atau layanan) yang menjalankan aplikasi. Jika autentikasi berhasil, ID Microsoft Entra mengembalikan token akses ke aplikasi, dan aplikasi kemudian dapat menggunakan token akses untuk mengotorisasi permintaan ke Azure AI Search.

Artikel ini memperlihatkan kepada Anda cara mengonfigurasi klien Anda untuk ID Microsoft Entra:

• Untuk autentikasi, buat identitas terkelola untuk aplikasi Anda. Anda dapat menggunakan jenis objek utama keamanan yang berbeda, tetapi artikel ini menggunakan identitas terkelola karena menghilangkan kebutuhan untuk mengelola kredensial.

• Untuk otorisasi, tetapkan peran Azure ke identitas terkelola yang memberikan izin untuk menjalankan kueri atau mengelola pekerjaan pengindeksan.

• Perbarui kode klien Anda untuk memanggil TokenCredential(). Misalnya, Anda dapat mulai menggunakan SearchClient(titik akhir, baru) baru DefaultAzureCredential()untuk mengautentikasi melalui ID Microsoft Entra menggunakan Azure.Identity.

Mengonfigurasi akses berbasis peran untuk bidang data

Berlaku pada: Kontributor Data Indeks Pencarian, Pembaca Data Indeks, Kontributor Layanan Pencarian

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

Portal Azure

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

2. Di panel navigasi sebelah kiri, pilih Kunci.

   

3. Pilih opsi kontrol akses API. Kami merekomendasikan Keduanya jika Anda menginginkan fleksibilitas atau perlu memigrasikan aplikasi.

   Opsi	Deskripsi
   Kunci API	(default) Memerlukan kunci API admin atau kueri pada header permintaan untuk otorisasi. Tidak ada peran yang digunakan.
   Kontrol Akses Berbasis Peran	Membutuhkan keanggotaan dalam penetapan peran untuk menyelesaikan tugas, yang dijelaskan pada langkah berikutnya. Hal ini juga memerlukan header otorisasi.
   Keduanya	Permintaan valid menggunakan kunci API atau kontrol akses berbasis peran.

Perubahan segera efektif, tetapi tunggu beberapa detik sebelum pengujian.

Semua panggilan jaringan untuk operasi layanan pencarian dan konten mematuhi opsi yang Anda pilih: Kunci API, token pembawa, atau salah satu jika Anda memilih Keduanya.

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

REST API

Gunakan Management REST API Create atau Update Service untuk mengonfigurasi layanan Anda.

Semua panggilan ke Rest API Manajemen diautentikasi melalui ID Microsoft Entra, dengan izin Kontributor atau Pemilik. Untuk bantuan dalam menyiapkan permintaan terautentikasi di klien REST, 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"
               }
           }
       }
   }
   

Buat identitas terkelola

Dalam langkah ini, buat identitas terkelola untuk aplikasi klien Anda.

1. Masuk ke portal Azure.

2. Cari Identitas Terkelola.

3. Pilih Buat.

4. Beri nama identitas terkelola Anda dan pilih wilayah. Lalu, pilih Buat.

   

Menetapkan peran ke identitas terkelola

Selanjutnya, Anda perlu memberikan akses identitas terkelola klien Anda ke layanan pencarian Anda. Azure AI Search memiliki berbagai peran bawaan. Anda juga dapat membuat peran kustom.

Ini adalah praktik terbaik untuk memberikan izin minimum. Jika aplikasi Anda hanya perlu menangani kueri, Anda harus menetapkan peran Pembaca Data Indeks Pencarian. Atau, jika klien memerlukan akses baca dan tulis pada indeks pencarian, Anda harus menggunakan peran Kontributor Data Indeks Pencarian.

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

   • Kontributor

   • Pembaca

   • Kontributor Layanan Pencarian

   • Kontributor Data Indeks Pencarian

   • Pembaca Data Indeks Pencarian

     Catatan

     Pemilik, Kontributor, Pembaca, dan Kontributor Layanan Pencarian adalah peran sarana kontrol dan tidak memberi Anda akses ke data dalam indeks pencarian. Untuk akses data, pilih peran Kontributor Data Indeks Pencarian atau Pembaca Data Indeks Pencarian. Untuk informasi selengkapnya tentang cakupan dan tujuan setiap peran, lihat Peran bawaan yang digunakan dalam Pencarian.

6. Pada tab Anggota , pilih identitas terkelola yang ingin Anda berikan akses ke layanan pencarian Anda.

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

Anda dapat menetapkan beberapa peran, seperti Kontributor Layanan Pencarian dan Kontributor Data Indeks Pencarian, jika aplikasi Anda memerlukan akses komprehensif ke layanan pencarian, objek, dan konten.

Anda juga dapat menetapkan peran menggunakan PowerShell.

Menyiapkan autentikasi Microsoft Entra di klien Anda

Setelah Anda memiliki identitas terkelola dan penetapan peran pada layanan pencarian, Anda siap untuk menambahkan kode ke aplikasi Anda untuk mengautentikasi prinsip keamanan dan memperoleh token OAuth 2.0.

Gunakan pustaka klien berikut untuk kontrol akses berbasis peran:

• azure.search.documents (Azure SDK untuk .NET)
• azure-search-documents (Azure SDK for Java)
• azure/search-documents (Azure SDK for JavaScript)
• azure.search.documents (Azure SDK for Python)

Catatan

Untuk mempelajari selengkapnya tentang alur pemberian kode OAuth 2.0 yang digunakan oleh ID Microsoft Entra, lihat Mengotorisasi akses ke aplikasi web Microsoft Entra menggunakan alur pemberian kode OAuth 2.0.

.NET SDK

Instruksi berikut mereferensikan sampel C# yang ada untuk menunjukkan perubahan kode.

1. Sebagai titik awal, klon kode sumber untuk bagian C# dari Mulai Cepat: Pencarian teks lengkap menggunakan Azure SDK.

   Sampel saat ini menggunakan autentikasi berbasis kunci dan AzureKeyCredential untuk membuat SearchClient dan SearchIndexClient tetapi Anda dapat membuat perubahan kecil untuk beralih ke autentikasi berbasis peran.

2. Perbarui paket NuGet Azure.Search.Documents ke versi 11.4 atau yang lebih baru.

3. Impor pustaka Azure.Identity untuk mendapatkan akses ke teknik autentikasi lainnya.

4. Alih-alih menggunakan AzureKeyCredential di awal Main() Program.cs, gunakan DefaultAzureCredential seperti dalam cuplikan kode di bawah ini:

   // 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());
   

Pengujian lokal

Identitas terkelola yang ditetapkan pengguna hanya berfungsi di lingkungan Azure. Jika Anda menjalankan kode ini secara lokal, DefaultAzureCredential kembali ke autentikasi dengan kredensial Anda. Pastikan Anda memberi diri Anda akses yang diperlukan ke layanan pencarian jika Anda berencana untuk menjalankan kode secara lokal.

1. Verifikasi bahwa akun Anda memiliki penetapan peran untuk menjalankan semua operasi dalam sampel mulai cepat. Untuk membuat dan mengkueri indeks, gunakan "Pembaca Data Indeks Pencarian" dan "Kontributor Data Indeks Pencarian".

2. Buka Opsi>Alat>Autentikasi Layanan Azure untuk memilih akun masuk Azure Anda.

Anda sekarang dapat menjalankan proyek dari Visual Studio pada sistem lokal Anda, menggunakan kontrol akses berbasis peran untuk otorisasi.

Catatan

Dokumentasi Azure.Identity memiliki detail selengkapnya tentang DefaultAzureCredential dan menggunakan autentikasi Microsoft Entra dengan Azure SDK untuk .NET. DefaultAzureCredential dimaksudkan untuk menyederhanakan memulai SDK dengan menangani skenario umum dengan perilaku default yang wajar. Pengembang yang menginginkan lebih banyak kontrol atau skenarionya tidak dilayani oleh pengaturan default harus menggunakan jenis kredensial lainnya.

REST API

Azure SDK memudahkan alur OAuth 2.0 tetapi Anda juga dapat memprogram langsung terhadap protokol dalam aplikasi Anda. Detail selengkapnya tersedia di Platform identitas Microsoft dan alur info masuk klien OAuth 2.0.

1. Mulai dengan mendapatkan token dari platform identitas Microsoft:

   POST /[tenant id]/oauth2/v2.0/token HTTP/1.1
   Host: login.microsoftonline.com
   Content-Type: application/x-www-form-urlencoded
   
   client_id=[client id]
   &scope=https%3A%2F%2Fsearch.azure.com%2F.default
   &client_secret=[client secret]
   &grant_type=client_credentials
   

   Cakupan yang diperlukan adalah "https://search.azure.com/.default".

2. Setelah memiliki token, Anda siap untuk menerbitkan permintaan ke layanan pencarian.

   GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters]
   Content-Type: application/json   
   Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
   

Lihat juga

• Menggunakan kontrol akses berbasis peran Azure di Azure AI Search
• Mengotorisasi akses ke aplikasi web Microsoft Entra menggunakan alur pemberian kode OAuth 2.0
• Mengintegrasikan dengan MICROSOFT Entra ID
• Peran kustom Azure