Connettersi a Azure AI Search usando le chiavi

Articolo
10/30/2024

Azure AI Search offre l'autenticazione basata su chiave per le connessioni al servizio di ricerca. Una chiave API è una stringa unica composta da 52 lettere e numeri generati casualmente. Nel codice sorgente è possibile specificarlo come variabile di ambiente o come impostazione dell'app nel progetto e quindi fare riferimento alla variabile nella richiesta. Una richiesta inviata a un endpoint del servizio di ricerca viene accettata se la richiesta e la chiave API sono valide.

L'autenticazione basata su chiave è l'impostazione predefinita.

È possibile sostituirlo con l'accesso in base al ruolo, eliminando la necessità di chiavi hardcoded nella codebase.

Tipi di chiavi API

Esistono due tipi di chiavi usate per l'autenticazione di una richiesta:

Type	Livello di autorizzazione	Massimo	Modalità di creazione
Amministratore	Accesso completo (lettura/scrittura) per tutte le operazioni sul contenuto	2 ¹	Due chiavi amministratore, chiamate chiave primaria e secondaria nel portale, vengono generate quando il servizio viene creato e possono essere generate di nuovo singolarmente su richiesta.
Query	Accesso in sola lettura, con ambito alla raccolta documenti di un indice di ricerca	50	Viene generata una chiave di query con il servizio. Altre informazioni possono essere create su richiesta da un amministratore del servizio di ricerca.

¹ Averne due consente di eseguire il rollover di una chiave mentre si usa la seconda per l'accesso continuo al servizio.

Non esiste alcuna distinzione visiva tra una chiave amministratore o una chiave di query. Entrambe le chiavi sono stringhe composte da 52 caratteri alfanumerici generati in modo casuale. Se si perde traccia del tipo di chiave specificato nell'applicazione, è possibile controllare i valori delle chiavi nel portale.

Usare le chiavi API nelle connessioni

Le chiavi API vengono usate per le richieste del piano dati (contenuto), ad esempio la creazione o l'accesso a un indice o per qualsiasi altra richiesta rappresentata nelle API REST di ricerca. Al momento della creazione del servizio, una chiave API è l'unico meccanismo di autenticazione per le operazioni del piano dati, ma è possibile sostituire o integrare l'autenticazione della chiave con i ruoli di Azure se non è possibile usare chiavi hardcoded nel codice.

Le chiavi di amministrazione vengono usate per la creazione, la modifica o l'eliminazione di oggetti. Le chiavi di amministrazione vengono usate anche per ottenere definizioni di oggetti e informazioni di sistema.

Le chiavi di query vengono in genere distribuite alle applicazioni client che eseguono query.

Modalità di utilizzo delle chiavi API nelle chiamate REST:

Impostare una chiave amministratore nell'intestazione della richiesta. Non è possibile passare chiavi di amministratore nell'URI o nel corpo della richiesta. Le chiavi di amministrazione vengono usate per l'operazione create-read-update-delete e per le richieste rilasciate al servizio di ricerca stesso, ad esempio indici LIST o GET Service Statistics.

Di seguito è riportato un esempio di utilizzo della chiave API di amministrazione in una richiesta di creazione dell'indice:

### Create an index
POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{adminApiKey}}

    {
        "name": "my-new-index",  
        "fields": [
            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "Name", "type": "Edm.String", "searchable": true }
         ]
   }

Impostare una chiave di query in un'intestazione di richiesta per POST o nell'URI per GET. Le chiavi di query vengono usate per le operazioni destinate alla raccoltaindex/docs: Ricerca documenti , completamento automatico, suggerimento o GET Document.

Di seguito è riportato un esempio di utilizzo della chiave API di query in una richiesta GET (Search Documents):

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2024-07-01&api-key={{queryApiKey}}

Nota

Passare dati sensibili, ad esempio un elemento api-key, nell'URI della richiesta è considerato una procedura di sicurezza non ottimale. Per questo motivo, Azure AI Search accetta solo una chiave di query come api-key nella stringa di query. Come regola generale, è consigliabile passare l'elemento api-key come intestazione della richiesta.

Come vengono usate le chiavi API in PowerShell:

Impostare le chiavi API nell'intestazione della richiesta usando la sintassi seguente:

$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

Un esempio di script che mostra l'utilizzo della chiave API per varie operazioni è disponibile in Guida introduttiva: Creare un indice di Azure AI Search in PowerShell usando le API REST.

Autorizzazioni per visualizzare o gestire le chiavi API

Le autorizzazioni per la visualizzazione e la gestione delle chiavi API vengono trasmesse tramite assegnazioni di ruolo. I membri dei ruoli seguenti possono visualizzare e ricreare una chiave:

Proprietario
Collaboratore
Collaboratore servizi di ricerca
Amministratore del servizio e coamministratore (versione classica)

I ruoli seguenti non hanno accesso alle chiavi API:

Reader
Collaboratore ai dati dell'indice di ricerca
Lettore di dati dell'indice di ricerca

Trovare le chiavi esistenti

È possibile visualizzare e gestire le chiavi API nel portale di Azure oppure tramite PowerShell, l'interfaccia della riga di comando di Azure o l'API REST.

Accedere al portale di Azure e trovare il servizio di ricerca.
In Impostazioni, selezionare Chiavi per visualizzare le chiavi di amministratore ed eseguire query.

Installare il modulo Az.Search:
```
Install-Module Az.Search
```

Restituire le chiavi di amministratore:

Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Restituire le chiavi di query:

Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Usare i comandi seguenti per restituire le chiavi API di amministrazione ed esecuzione di query rispettivamente:

az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>

az search query-key list --resource-group <myresourcegroup> --service-name <myservice>

Usare List Admin Keys o List Query Keys nell'API REST di gestione per restituire le chiavi API.

È necessario disporre di un'assegnazione di ruolo valida per restituire o aggiornare le chiavi API. Vedere Gestire il servizio Azure AI Search con le API REST per indicazioni su come soddisfare i requisiti dei ruoli usando le API REST.

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01

Creare chiavi di query

Le chiavi di query vengono usate per l'accesso in sola lettura ai documenti all'interno di un indice per le operazioni destinate a una raccolta di documenti. Le query di ricerca, filtro e suggerimento sono tutte operazioni che accettano una chiave di query. Qualsiasi operazione di sola lettura che restituisce definizioni di dati o oggetti di sistema, ad esempio una definizione di indice o uno stato dell'indicizzatore, richiede una chiave di amministratore.

Limitare l'accesso e le operazioni nelle app client è essenziale per proteggere gli asset di ricerca nel servizio. Usare sempre una chiave di query anziché una chiave di amministrazione per qualsiasi query proveniente da un'app client.

Accedere al portale di Azure e trovare il servizio di ricerca.
In Impostazioni, selezionare Chiavi per visualizzare le chiavi API.
In Gestisci chiavi di query, usare la chiave di query già generata per il servizio o creare nuove chiavi di query. La chiave di query predefinita non è denominata, ma altre chiavi di query generate possono essere denominate per la gestibilità.

Usare Creare chiavi di query nell'API REST di gestione.

È necessario avere un'assegnazione di ruolo valida per creare o gestire chiavi API. Vedere Gestire il servizio Azure AI Search con le API REST per indicazioni su come soddisfare i requisiti dei ruoli usando le API REST.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2023-11-01

Riscrivere una chiave amministratore

Vengono create due chiavi di amministrazione per ogni servizio in modo che sia possibile ruotare una chiave primaria usando la chiave secondaria per la continuità aziendale.

In Impostazioni. selezionare Chiavi, quindi copiare la chiave secondaria.
Per tutte le applicazioni, aggiornare le impostazioni relative alle chiavi API per usare la chiave secondaria.
Riscrivere la chiave primaria.
Aggiornare tutte le applicazioni affinché usino la nuova chiave primaria.

Se si rigenerano inavvertitamente entrambe le chiavi contemporaneamente, tutte le richieste client che usano tali chiavi avranno esito negativo con HTTP 403 Non consentito. Tuttavia, il contenuto non viene eliminato e non viene bloccato in modo permanente.

È comunque possibile accedere al servizio tramite il portale o a livello di codice. Le funzioni di gestione sono operative tramite un ID sottoscrizione non una chiave API del servizio e sono quindi ancora disponibili anche se le chiavi API non sono.

Dopo aver creato nuove chiavi tramite il portale o il livello di gestione, l'accesso viene ripristinato al contenuto (indici, indicizzatori, origini dati, mappe sinonimi) dopo aver fornito tali chiavi alle richieste.

Proteggere le chiavi API

Usare le assegnazioni di ruolo per limitare l'accesso alle chiavi API.

Non è possibile usare la crittografia della chiave gestita dal cliente per crittografare le chiavi API. Solo i dati sensibili all'interno del servizio di ricerca stesso (ad esempio, il contenuto dell'indice o le stringhe di connessione nelle definizioni degli oggetti dell'origine dati) possono essere crittografati tramite chiave gestita dal cliente.

Passare alla pagina del servizio di ricerca nel portale di Azure.
Nel pannello di navigazione a sinistra, selezionare controllo di accesso (IAM) e quindi selezionare la scheda Assegnazioni di ruolo.
Nel filtro Ruolo, selezionare i ruoli che dispongono dell'autorizzazione per visualizzare o gestire le chiavi (Proprietario, Collaboratore, Collaboratore servizio di ricerca). Le entità di sicurezza risultanti assegnate a tali ruoli dispongono delle autorizzazioni chiave per il servizio di ricerca.
Per precauzione, controllare anche la scheda Amministratori classici per determinare se gli amministratori e i coamministratori hanno accesso.

Procedure consigliate

Usare le chiavi API solo se la divulgazione dei dati non è un rischio (ad esempio, quando si usano dati di esempio) e se si opera dietro un firewall. L'esposizione delle chiavi API è un rischio sia per i dati che per l'uso non autorizzato del servizio di ricerca.
Controllare sempre il codice, gli esempi e il materiale di training prima della pubblicazione per assicurarsi di non aver lasciato le chiavi API valide.
Per i carichi di lavoro di produzione, passare a Microsoft Entra ID e all'accesso in base al ruolo. In alternativa, se si vuole continuare a usare le chiavi API, assicurarsi di monitorare sempre chi può accedere alle chiavi API e rigenerare le chiavi API regolarmente.

Condividi tramite