Connessione a Ricerca di intelligenza artificiale di Azure usando l'autenticazione con chiave

Articolo
04/25/2024

Ricerca di intelligenza artificiale di Azure offre l'autenticazione basata su chiavi che è possibile usare nelle connessioni al servizio di ricerca. Una chiave API è una stringa univoca composta da 52 numeri e lettere generati in modo casuale. 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 disabilitarla se si acconsente esplicitamente all'autenticazione basata su ruoli.

Nota

Una breve nota sulla terminologia chiave . Una chiave API è un GUID usato per l'autenticazione. Un termine separato, chiave documento è una stringa univoca nel contenuto indicizzato che identifica in modo univoco i documenti in un indice di ricerca.

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.

¹ Avere due consente di eseguire il rollover di una chiave durante l'uso della seconda chiave per l'accesso continuo al servizio.

Visivamente, non esiste alcuna distinzione tra una chiave di amministrazione 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.

Amministrazione chiavi vengono usate per la creazione, la modifica o l'eliminazione di oggetti. Amministrazione chiavi 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. Amministrazione chiavi vengono usate per l'operazione create-read-update-delete e sulle richieste inviate al servizio di ricerca stesso, ad esempio List Indexes or GET Service Statistics.LIST Indexes or 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=2023-11-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 raccolta: Ricerca documenti, completamento automatico, suggerimento o GET documento.index/docs

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=2023-11-01&api-key={{queryApiKey}}

Nota

È considerata una procedura di sicurezza scarsa per passare dati sensibili, ad esempio un api-key nell'URI della richiesta. Per questo motivo, Ricerca di intelligenza artificiale di Azure accetta solo una chiave di api-key query come 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 Avvio rapido: Creare un indice di Ricerca di intelligenza artificiale di Azure 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
Amministrazione istrator e coamministratore (versione classica)

I ruoli seguenti non hanno accesso alle chiavi API:

Lettore
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 Az.Search modulo:
```
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 Amministrazione 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 i servizio di ricerca di intelligenza artificiale di Azure 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 i servizio di ricerca di intelligenza artificiale di Azure 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 e quindi copiare la chiave secondaria.
Per tutte le applicazioni, aggiornare le impostazioni della chiave 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 i stringa di connessione nelle definizioni degli oggetti origine dati) possono essere crittografati tramite chiave gestita dal cliente.

Passare alla pagina del servizio di ricerca in portale di Azure.
Nel riquadro di spostamento sinistro 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 all'ID Microsoft Entra 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 a cadenza regolare.