Menyambungkan aplikasi Anda ke Pencarian Azure AI menggunakan identitas

Dalam kode aplikasi, Anda dapat menyiapkan koneksi tanpa kunci ke Pencarian Azure AI yang menggunakan Microsoft Entra ID dan peran untuk autentikasi dan otorisasi. Permintaan aplikasi ke sebagian besar layanan Azure harus diautentikasi dengan kunci atau koneksi tanpa kunci. Pengembang harus rajin untuk tidak pernah mengekspos kunci di lokasi yang tidak aman. Siapa pun yang mendapatkan akses ke kunci dapat mengautentikasi ke layanan. Autentikasi tanpa kunci menawarkan peningkatan manfaat manajemen dan keamanan dibandingkan dengan kunci akun karena tidak ada kunci (atau string koneksi) yang perlu disimpan.

Artikel ini menjelaskan cara menggunakan DefaultAzureCredential dalam kode aplikasi Anda.

Untuk menerapkan koneksi tanpa kunci dalam kode Anda, ikuti langkah-langkah berikut:

  • Mengaktifkan akses berbasis peran pada layanan pencarian Anda
  • Atur variabel lingkungan, sesuai kebutuhan.
  • Gunakan jenis kredensial pustaka identitas Azure untuk membuat objek klien Pencarian Azure AI.

Prasyarat

  • Pencarian Azure AI, wilayah mana pun tetapi harus tingkat berbayar (tingkat dasar atau lebih tinggi).

  • Akses berbasis peran diaktifkan pada layanan pencarian Anda.

  • Penetapan peran pada Pencarian Azure AI. Tetapkan peran ini ke identitas Anda:

    • Kontributor Layanan Pencarian dan Kontributor Data Indeks Pencarian untuk pengembangan lokal (akses penuh)
    • Pembaca Data Indeks Pencarian untuk kueri baca-saja di lingkungan produksi

    Untuk instruksi langkah demi langkah, lihat Menetapkan peran untuk pengembangan.

Menginstal pustaka klien identitas Azure

Untuk menggunakan pendekatan tanpa kunci, perbarui kode yang diaktifkan Pencarian AI Anda dengan pustaka klien Azure Identity.

Instal pustaka klien Azure Identity untuk .NET dan Azure Search Documents:

dotnet add package Azure.Identity
dotnet add package Azure.Search.Documents

Memperbarui kode sumber untuk menggunakan DefaultAzureCredential

DefaultAzureCredential pustaka identitas Azure memungkinkan Anda menjalankan kode yang sama di lingkungan pengembangan lokal dan di cloud Azure. Buat satu kredensial dan gunakan ulang instans kredensial sesuai kebutuhan untuk memanfaatkan penyimpanan token.

Untuk informasi selengkapnya tentang DefaultAzureCredential untuk .NET, lihat pada pustaka klien Azure Identity untuk .NET.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;
using System;
using static System.Environment;

string endpoint = GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT");
string indexName = "my-search-index";

DefaultAzureCredential credential = new();
SearchClient searchClient = new(new Uri(endpoint), indexName, credential);
SearchIndexClient searchIndexClient = new(endpoint, credential);

Referensi:SearchClient, SearchIndexClient, DefaultAzureCredential

Memverifikasi koneksi Anda

Setelah menyiapkan klien, verifikasi koneksi Anda dengan menjalankan operasi sederhana. Contoh berikut mencantumkan indeks pada layanan pencarian Anda:

// List indexes to verify connection
var indexes = searchIndexClient.GetIndexNames();
foreach (var name in indexes)
{
    Console.WriteLine(name);
}

Koneksi yang berhasil mencetak nama indeks Anda (atau daftar kosong jika tidak ada indeks). Jika Anda menerima kesalahan autentikasi, verifikasi bahwa akses berbasis peran diaktifkan dan identitas Anda memiliki penetapan peran yang diperlukan.

Otoritas default adalah Azure cloud publik. Nilai kustom audience untuk sovereign atau cloud khusus meliputi:

  • https://search.azure.us untuk Azure Government
  • https://search.azure.cn untuk Azure yang dioperasikan oleh 21Vianet
  • https://search.microsoftazure.de untuk Azure Jerman

Pengembangan lokal

Pengembangan lokal menggunakan peran mencakup langkah-langkah berikut:

  • Tetapkan identitas pribadi Anda ke peran RBAC pada sumber daya tertentu.
  • Gunakan alat seperti Azure CLI atau Azure PowerShell untuk mengautentikasi dengan Azure.
  • Buat variabel lingkungan untuk sumber daya Anda.

Peran untuk pengembangan lokal

Sebagai pengembang lokal, identitas Azure Anda memerlukan kontrol penuh atas operasi sarana data. Ini adalah peran yang disarankan:

  • Kontributor Layanan Pencarian, membuat dan mengelola objek
  • Kontributor Data Indeks Pencarian, memuat dan menjalankan kueri indeks serta mengambil data dari pangkalan pengetahuan

Temukan identitas pribadi Anda dengan salah satu alat berikut. Gunakan identitas tersebut <identity-id> sebagai nilai.

Ganti placeholder <role-name>, <identity-id>, <subscription-id>, dan <resource-group-name> dengan nilai aktual Anda dalam perintah berikut.

  1. Masuk ke Azure CLI.

    az login

    Jendela browser terbuka untuk autentikasi. Setelah berhasil masuk, terminal akan menampilkan informasi langganan Anda.

  2. Dapatkan identitas pribadi Anda.

    az ad signed-in-user show \
    --query id -o tsv

    Perintah mengembalikan ID objek pengguna Anda (GUID). Simpan nilai ini untuk langkah berikutnya.

  3. Tetapkan peran kontrol akses berbasis peran (RBAC) ke identitas untuk grup sumber daya.

    az role assignment create \
    --role "<role-name>" \
    --assignee "<identity-id>" \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"

    Penugasan yang berhasil akan mengembalikan berupa objek JSON dengan detail penugasan peran.

Autentikasi untuk pengembangan lokal

Gunakan alat di lingkungan pengembangan lokal Anda untuk mengautentikasi identitas Azure. Setelah Anda diautentikasi, DefaultAzureCredential instans dalam kode sumber Anda menemukan dan menggunakan identitas Anda untuk tujuan autentikasi.

Pilih alat untuk autentikasi selama pengembangan lokal.

Mengonfigurasi variabel lingkungan untuk pengembangan lokal

Untuk menyambungkan ke Pencarian Azure AI, kode Anda perlu mengetahui titik akhir sumber daya Anda.

Buat variabel lingkungan bernama AZURE_SEARCH_ENDPOINT untuk titik akhir Pencarian Azure AI Anda. URL ini umumnya memiliki format https://<YOUR-RESOURCE-NAME>.search.windows.net/.

Beban kerja produksi

Menyebarkan beban kerja produksi mencakup langkah-langkah berikut:

  • Pilih peran RBAC yang mematuhi prinsip hak istimewa paling sedikit.
  • Tetapkan peran RBAC ke identitas produksi Anda pada sumber daya tertentu.
  • Siapkan variabel lingkungan untuk sumber daya Anda.

Peran dalam beban kerja produksi

Untuk membuat sumber daya produksi, Anda perlu membuat identitas terkelola yang ditetapkan pengguna lalu menetapkan identitas tersebut ke sumber daya Anda dengan peran yang benar.

Peran berikut disarankan untuk aplikasi produksi:

Nama peran Nomor Identitas
Pembaca Data Indeks Pencarian 1407120a-92aa-4202-b7e9-c0e197c71c8f

Autentikasi untuk beban kerja produksi

Gunakan templat Pencarian Azure AI Bicep berikut untuk membuat sumber daya dan mengatur autentikasi untuk identityId. Bicep memerlukan ID peran. name yang ditampilkan dalam cuplikan Bicep ini bukan peran Azure, hal ini khusus untuk penyebaran Bicep.

// main.bicep
param environment string = 'production'
param roleGuid string = ''

module aiSearchRoleUser 'core/security/role.bicep' = {
    scope: aiSearchResourceGroup
    name: 'aiSearch-role-user'
    params: {
        principalId: (environment == 'development') ? principalId : userAssignedManagedIdentity.properties.principalId 
        principalType: (environment == 'development') ? 'User' : 'ServicePrincipal'
        roleDefinitionId: roleGuid
    }
}

File main.bicep memanggil kode Bicep generik berikut untuk membuat peran apa pun. Anda memiliki opsi untuk membuat beberapa peran RBAC, seperti satu untuk pengguna dan yang lain untuk produksi. Ini memungkinkan Anda mengaktifkan lingkungan pengembangan dan produksi dalam penyebaran Bicep yang sama.

// core/security/role.bicep
metadata description = 'Creates a role assignment for an identity.'
param principalId string // passed in from main.bicep

@allowed([
    'Device'
    'ForeignGroup'
    'Group'
    'ServicePrincipal'
    'User'
])
param principalType string = 'ServicePrincipal'
param roleDefinitionId string // Role ID

resource role 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    name: guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)
    properties: {
        principalId: principalId
        principalType: principalType
        roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    }
}

Mengonfigurasi variabel lingkungan untuk beban kerja produksi

Untuk menyambungkan ke Pencarian Azure AI, kode Anda perlu mengetahui titik akhir sumber daya Anda, dan ID identitas terkelola.

Buat variabel lingkungan untuk sumber daya Pencarian Azure AI yang disebarkan dan tanpa kunci:

  • AZURE_SEARCH_ENDPOINT: URL ini adalah titik akses untuk sumber daya Pencarian Azure AI Anda. URL ini umumnya memiliki format https://<YOUR-RESOURCE-NAME>.search.windows.net/.
  • AZURE_CLIENT_ID: Ini adalah identitas untuk mengautentikasi sebagai.

Memecahkan masalah kesalahan umum

Kesalahan Penyebab Solusi
AuthenticationFailedException Kredensial hilang atau tidak valid Pastikan Anda masuk dengan az login (CLI) atau Connect-AzAccount (PowerShell). Verifikasi akun Azure Anda memiliki akses ke langganan.
403 Forbidden Identitas tidak memiliki peran yang diperlukan Tetapkan peran yang sesuai (Pembaca Data Indeks Pencarian untuk kueri, Kontributor Data Indeks Pencarian untuk pengindeksan). Penetapan peran dapat memakan waktu hingga 10 menit untuk disebarluaskan.
401 Unauthorized RBAC tidak diaktifkan pada layanan pencarian Aktifkan akses berbasis peran di portal Azure di bawah Settings>Keys>Kontrol akses berbasisRole.
ResourceNotFoundException Titik akhir atau nama indeks tidak valid Verifikasi variabel lingkungan cocok dengan AZURE_SEARCH_ENDPOINT URL layanan pencarian Anda (format: https://<service-name>.search.windows.net).
CredentialUnavailableException Tidak ditemukan kredensial yang valid DefaultAzureCredential mencoba beberapa metode autentikasi. Pastikan setidaknya satu dikonfigurasi (Azure CLI, Visual Studio, variabel lingkungan).

Konten terkait

  • Last updated on