Connettere l'app a Azure AI Search usando le identità

Nel codice dell'applicazione è possibile configurare una connessione senza chiave per Azure AI Search che usa Microsoft Entra ID e ruoli per l'autenticazione e l'autorizzazione. Le richieste dell'applicazione alla maggior parte dei servizi di Azure devono essere autenticate con chiavi o connessioni senza chiave. Gli sviluppatori devono essere diligenti per non esporre mai le chiavi in una posizione non sicura. Chiunque possa accedere alla chiave è in grado di eseguire l'autenticazione al servizio. L'autenticazione senza chiave offre vantaggi di gestione e sicurezza migliorati rispetto alla chiave dell'account perché non è presente alcuna chiave (o stringa di connessione) da archiviare.

Questo articolo illustra come usare DefaultAzureCredential nel codice dell'applicazione.

Per implementare connessioni senza chiave nel codice, seguire questa procedura:

• Abilitare l'accesso in base al ruolo nel servizio di ricerca
• Impostare le variabili di ambiente in base alle esigenze.
• Usare un tipo di credenziale della libreria di identità Azure per creare un oggetto client Azure AI Search.

Prerequisiti

• Azure AI Search, qualsiasi area, ma deve essere un livello fatturabile (basic o superiore).

• Accesso basato sui ruoli abilitato nel servizio di ricerca.

• Assegnazioni di ruolo in Azure AI Search. Assegna questi ruoli alla tua identità:

  • Collaboratore al servizio di ricerca e Collaboratore ai dati dell'indice di ricerca per lo sviluppo locale (accesso completo)
  • Lettore di dati dell'indice di ricerca per query di sola lettura in produzione

  Per istruzioni dettagliate, vedere Assegnare ruoli per lo sviluppo.

Installare la libreria client Azure Identity

Per usare un approccio senza chiave, aggiornare il codice abilitato per la ricerca di intelligenza artificiale con la libreria client Azure Identity.

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

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.15.1</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-search-documents</artifactId>
            <version>11.7.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

npm install --save @azure/identity @azure/search-documents

pip install azure-identity azure-search-documents

Aggiornare il codice sorgente per usare DefaultAzureCredential

La libreria Azure identity DefaultAzureCredential consente di eseguire lo stesso codice nell'ambiente di sviluppo locale e nel cloud Azure. Creare una singola credenziale e riutilizzare l'istanza delle credenziali in base alle esigenze per sfruttare i vantaggi della memorizzazione nella cache dei token.

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

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.search.documents.SearchAsyncClient;
import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.indexes.SearchIndexAsyncClient;
import com.azure.search.documents.indexes.SearchIndexClientBuilder;

String ENDPOINT = System.getenv("AZURE_SEARCH_ENDPOINT");
String INDEX_NAME = "my-index";

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

// Sync SearchClient
SearchClient searchClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildClient();

// Sync IndexClient
SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildClient();

// Async SearchClient
SearchAsyncClient searchAsyncClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildAsyncClient();

// Async IndexClient
SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildAsyncClient();

import { DefaultAzureCredential } from "@azure/identity";
import {
  SearchClient,
  SearchIndexClient
} from "@azure/search-documents";

const AZURE_SEARCH_ENDPOINT = process.env.AZURE_SEARCH_ENDPOINT;
const index = "my-index";
const credential = new DefaultAzureCredential();

// To query and manipulate documents
const searchClient = new SearchClient(
  AZURE_SEARCH_ENDPOINT,
  index,
  credential
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient(
  AZURE_SEARCH_ENDPOINT, 
  credential
);

import os
from azure.search.documents import SearchClient
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Azure Public Cloud
audience = "https://search.azure.com"
authority = AzureAuthorityHosts.AZURE_PUBLIC_CLOUD

service_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
credential = DefaultAzureCredential(authority=authority)

search_client = SearchClient(
    endpoint=service_endpoint, 
    index_name=index_name, 
    credential=credential, 
    audience=audience)

search_index_client = SearchIndexClient(
    endpoint=service_endpoint, 
    credential=credential, 
    audience=audience)

Verificare la connessione

Dopo aver configurato il client, verificare la connessione eseguendo una semplice operazione. L'esempio seguente elenca gli indici nel servizio di ricerca:

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

// List indexes to verify connection
searchIndexClient.listIndexNames().forEach(System.out::println);

// List indexes to verify connection
for await (const name of indexClient.listIndexesNames()) {
  console.log(name);
}

# List indexes to verify connection
for index in search_index_client.list_index_names():
    print(index)

Una connessione riuscita stampa i nomi degli indici (o un elenco vuoto se non esistono indici). Se viene visualizzato un errore di autenticazione, verificare che l'accesso basato su ruoli sia abilitato e che l'identità disponga delle assegnazioni di ruolo necessarie.

L'autorità predefinita è Azure cloud pubblico. I valori personalizzati audience per cloud sovrani o specializzati includono:

• https://search.azure.us per Azure per enti pubblici
• https://search.azure.cn per Azure gestita da 21Vianet
• https://search.microsoftazure.de per Azure Germania

Sviluppo locale

Lo sviluppo locale utilizzando i ruoli include questi passaggi:

• Assegnare la propria identità personale ai ruoli RBAC sulla risorsa specifica.
• Usare uno strumento come interfaccia della riga di comando di Azure o Azure PowerShell per eseguire l'autenticazione con Azure.
• Stabilire le variabili di ambiente per la risorsa.

Ruoli per lo sviluppo locale

In qualità di sviluppatore locale, la tua identità Azure richiede il controllo completo sulle operazioni del piano dati. Questi sono i ruoli suggeriti:

• Collaboratore servizio di ricerca, creazione e gestione di oggetti
• Collaboratore ai dati dell'indice di ricerca, caricare ed eseguire query su un indice e recuperare da una knowledge base

Trovare l'identità personale con uno degli strumenti seguenti. Usare tale identità come valore <identity-id>.

Autenticazione per lo sviluppo locale

Usare uno strumento nell'ambiente di sviluppo locale per autenticarsi con l'identità di Azure. Dopo l'autenticazione, l'istanza DefaultAzureCredential nel codice sorgente trova e usa l'identità a scopo di autenticazione.

Selezionare uno strumento per l'autenticazione durante lo sviluppo locale.

Configurare le variabili di ambiente per lo sviluppo locale

Per connettersi a Azure AI Search, il codice deve conoscere l'endpoint della risorsa.

Creare una variabile di ambiente denominata AZURE_SEARCH_ENDPOINT per l'endpoint Azure AI Search. Questo URL ha in genere il formato https://<YOUR-RESOURCE-NAME>.search.windows.net/.

Carichi di lavoro di produzione

La distribuzione dei carichi di lavoro di produzione include i passaggi seguenti:

• Scegliere i ruoli di controllo degli accessi che rispettano il principio del minimo privilegio.
• Assegnare i ruoli RBAC alla propria identità di produzione sulla risorsa specifica.
• Configurare le variabili di ambiente per la risorsa.

Ruoli per i carichi di lavoro di produzione

Per creare le risorse di produzione, è necessario creare un'identità gestita assegnata dall'utente e quindi assegnare tale identità alle risorse con i ruoli corretti.

Il ruolo seguente è consigliato per un'applicazione di produzione:

Autenticazione per carichi di lavoro di produzione

Usare il seguente modello Azure AI Search Bicep per creare la risorsa e impostare l'autenticazione per l'identityId. Bicep richiede l'ID ruolo. Il name illustrato in questo frammento di codice di Bicep non rappresenta il ruolo di Azure; è specifico della distribuzione 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
    }
}

Il file main.bicep chiama il seguente codice Bicep generico per creare qualunque ruolo. Puoi creare più ruoli RBAC, ad esempio uno per l'utente e un altro per la produzione. In questo modo è possibile abilitare sia gli ambienti di sviluppo che di produzione all'interno della stessa distribuzione Bicep.

// 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)
    }
}

Configurare le variabili di ambiente per i carichi di lavoro di produzione

Per connettersi a Azure AI Search, il codice deve conoscere l'endpoint della risorsa e l'ID dell'identità gestita.

Creare variabili di ambiente per la risorsa Azure AI Search distribuita e senza chiave:

• AZURE_SEARCH_ENDPOINT: questo URL è il punto di accesso per la risorsa Azure AI Search. Questo URL ha in genere il formato https://<YOUR-RESOURCE-NAME>.search.windows.net/.
• AZURE_CLIENT_ID: Questa è l'identità con cui autenticarsi.

Risolvere gli errori comuni

Contenuti correlati

• Guida per gli sviluppatori di connessioni senza chiavi
• Ruoli predefiniti di Azure
• Impostare le variabili di ambiente