Autorizzare l'accesso a un'app di ricerca usando Microsoft Entra ID

Le applicazioni di ricerca basate su Ricerca intelligenza artificiale di Azure possono ora usare Microsoft Identity Platform per l'accesso autenticato e autorizzato. In Azure il provider di identità è Microsoft Entra ID. Un vantaggio fondamentale dell'uso di Microsoft Entra ID è che le credenziali e le chiavi API non devono più essere archiviate nel codice. Microsoft Entra autentica l'entità di sicurezza (un utente, un gruppo o un servizio) che esegue l'applicazione. Se l'autenticazione ha esito positivo, Microsoft Entra ID restituisce il token di accesso all'applicazione e l'applicazione può quindi usare il token di accesso per autorizzare le richieste a Ricerca di intelligenza artificiale di Azure.

Questo articolo illustra come configurare il client per Microsoft Entra ID:

• Per l'autenticazione, creare un'identità gestita per l'applicazione. È possibile usare un tipo diverso di oggetto entità di sicurezza, ma questo articolo usa le identità gestite perché eliminano la necessità di gestire le credenziali.

• Per l'autorizzazione, assegnare un ruolo di Azure all'identità gestita che concede le autorizzazioni per eseguire query o gestire i processi di indicizzazione.

• Aggiornare il codice client per chiamare TokenCredential(). Ad esempio, è possibile iniziare a usare il nuovo searchClient(endpoint, nuovo DefaultAzureCredential()) per eseguire l'autenticazione tramite un ID Microsoft Entra usando Azure.Identity.

Configurare l'accesso in base al ruolo per il piano dati

Si applica a: Collaboratore ai dati dell'indice di ricerca, Lettore dati indice di ricerca, Collaboratore servizio di ricerca

In questo passaggio configurare il servizio di ricerca per riconoscere un'intestazione di autorizzazione nelle richieste di dati che forniscono un token di accesso OAuth2.

Azure portal

1. Accedere al portale di Azure e aprire la pagina del servizio di ricerca.

2. Selezionare Chiavi nel riquadro di spostamento a sinistra.

   

3. Scegliere un'opzione di controllo di accesso api. È consigliabile eseguire entrambe le operazioni se si vuole flessibilità o se è necessario eseguire la migrazione delle app.

   Opzione	Descrizione
   Chiave API	(impostazione predefinita) Richiede un amministratore o eseguire query sulle chiavi API nell'intestazione della richiesta per l'autorizzazione. Non vengono usati ruoli.
   Controllo degli accessi in base al ruolo	Richiede l'appartenenza a un'assegnazione di ruolo per completare l'attività, descritta nel passaggio successivo. Richiede anche un'intestazione di autorizzazione.
   Entrambi	Le richieste sono valide usando una chiave API o un controllo degli accessi in base al ruolo.

La modifica è effettiva immediatamente, ma attendere alcuni secondi prima del test.

Tutte le chiamate di rete per le operazioni del servizio di ricerca e il contenuto rispettano l'opzione selezionata: chiavi API, token di connessione o una se si seleziona Entrambi.

Quando si abilita il controllo degli accessi in base al ruolo nel portale, la modalità di errore è "http401WithBearerChallenge" se l'autorizzazione non riesce.

REST API

Usare l'API REST di gestione Creare o aggiornare il servizio per configurare il servizio.

Tutte le chiamate all'API REST di gestione vengono autenticate tramite Microsoft Entra ID, con autorizzazioni di collaboratore o proprietario. Per informazioni sulla configurazione delle richieste autenticate in un client REST, vedere Gestire Ricerca di intelligenza artificiale di Azure con REST.

1. Ottenere le impostazioni del servizio in modo da poter esaminare la configurazione corrente.

   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
   

2. Usare PATCH per aggiornare la configurazione del servizio. Le modifiche seguenti consentono sia le chiavi che l'accesso in base al ruolo. Se si vuole una configurazione solo ruoli, vedere Disabilitare le chiavi API.

   In "properties" impostare "authOptions" su "aadOrApiKey". La proprietà "disableLocalAuth" deve essere false per impostare "authOptions".

   Facoltativamente, impostare "aadAuthFailureMode" per specificare se 401 viene restituito anziché 403 quando l'autenticazione non riesce. I valori validi sono "http401WithBearerChallenge" o "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"
               }
           }
       }
   }
   

Creare un'identità gestita

In questo passaggio creare un'identità gestita per l'applicazione client.

1. Accedere al portale di Azure.

2. Cercare Identità gestite.

3. Seleziona Crea.

4. Assegnare un nome all'identità gestita e selezionare un'area. Quindi, selezionare Crea.

   

Assegnare un ruolo all'identità gestita

Successivamente, è necessario concedere all'identità gestita del client l'accesso al servizio di ricerca. Ricerca di intelligenza artificiale di Azure include diversi ruoli predefiniti. È anche possibile creare un ruolo personalizzato.

È consigliabile concedere autorizzazioni minime. Se l'applicazione deve gestire solo le query, è necessario assegnare il ruolo lettore dati dell'indice di ricerca. In alternativa, se il client necessita sia dell'accesso in lettura che in scrittura in un indice di ricerca, è consigliabile usare il ruolo Collaboratore ai dati dell'indice di ricerca.

1. Accedere al portale di Azure.

2. Passare al servizio di ricerca.

3. Selezionare Controllo di accesso (IAM) nel riquadro di spostamento a sinistra.

4. Selezionare Aggiungi>Aggiungi assegnazione di ruolo.

   

5. Selezionare un ruolo applicabile:

   • Proprietario

   • Collaboratore

   • Lettore

   • Collaboratore servizi di ricerca

   • Collaboratore ai dati dell'indice di ricerca

   • Lettore di dati dell'indice di ricerca

     Nota

     Proprietario, Collaboratore, Lettore e Collaboratore servizio di ricerca sono ruoli del piano di controllo e non consentono l'accesso ai dati all'interno di un indice di ricerca. Per l'accesso ai dati, scegliere il ruolo Collaboratore dati indice di ricerca o Lettore dati indice di ricerca. Per altre informazioni sull'ambito e sullo scopo di ogni ruolo, vedere Ruoli predefiniti usati nella ricerca.

6. Nella scheda Membri selezionare l'identità gestita a cui si vuole concedere l'accesso al servizio di ricerca.

7. Nella scheda Rivedi e assegna selezionare Rivedi e assegna per assegnare il ruolo.

È possibile assegnare più ruoli, ad esempio Collaboratore al servizio di ricerca e Collaboratore ai dati dell'indice di ricerca, se l'applicazione necessita di accesso completo ai servizi di ricerca, agli oggetti e al contenuto.

È anche possibile assegnare ruoli usando PowerShell.

Configurare l'autenticazione di Microsoft Entra nel client

Dopo aver creato un'identità gestita e un'assegnazione di ruolo nel servizio di ricerca, è possibile aggiungere codice all'applicazione per autenticare l'entità di sicurezza e acquisire un token OAuth 2.0.

Usare le librerie client seguenti per il controllo degli accessi in base al ruolo:

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

Nota

Per altre informazioni sul flusso di concessione del codice OAuth 2.0 usato da Microsoft Entra ID, vedere Autorizzare l'accesso alle applicazioni Web di Microsoft Entra usando il flusso di concessione del codice OAuth 2.0.

.NET SDK

Le istruzioni seguenti fanno riferimento a un esempio C# esistente per illustrare le modifiche al codice.

1. Come punto di partenza, clonare il codice sorgente per la sezione C# di Avvio rapido: Ricerca full-text usando gli SDK di Azure.

   L'esempio usa attualmente l'autenticazione basata su chiave e per AzureKeyCredential creare SearchClient e SearchIndexClient , ma è possibile apportare una piccola modifica per passare all'autenticazione basata su ruoli.

2. Aggiornare il pacchetto NuGet Azure.Search.Documents alla versione 11.4 o successiva.

3. Importare la libreria Azure.Identity per ottenere l'accesso ad altre tecniche di autenticazione.

4. Anziché usare AzureKeyCredential all'inizio di Main() in Program.cs, usare DefaultAzureCredential come nel frammento di codice seguente:

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

Test locale

Le identità gestite assegnate dall'utente funzionano solo negli ambienti Azure. Se si esegue questo codice in locale, DefaultAzureCredential esegue il fallback all'autenticazione con le credenziali. Assicurarsi di concedere a se stessi l'accesso necessario al servizio di ricerca se si prevede di eseguire il codice in locale.

1. Verificare che l'account disponga di assegnazioni di ruolo per eseguire tutte le operazioni nell'esempio di avvio rapido. Per creare ed eseguire query su un indice, usare "Search Index Data Reader" e "Search Index Data Contributor".

2. Passare a Strumenti>Opzioni>autenticazione del servizio di Azure per scegliere l'account di accesso di Azure.

È ora possibile eseguire il progetto da Visual Studio nel sistema locale, usando il controllo degli accessi in base al ruolo per l'autorizzazione.

Nota

La documentazione di Azure.Identity contiene altri dettagli sull'autenticazione DefaultAzureCredential di Microsoft Entra con Azure SDK per .NET. DefaultAzureCredential è destinato a semplificare l'avvio dell'uso dell'SDK gestendo scenari comuni con comportamenti predefiniti ragionevoli. Gli sviluppatori che vogliono un maggior controllo o i cui requisiti non vengono soddisfatti dalle impostazioni predefinite dovranno usare altri tipi di credenziali.

REST API

L'uso di Azure SDK semplifica il flusso OAuth 2.0, ma è anche possibile programmare direttamente sul protocollo nell'applicazione. I dettagli completi sono disponibili in Microsoft Identity Platform e nel flusso di credenziali client OAuth 2.0.

1. Per iniziare, ottenere un token da Microsoft Identity Platform:

   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
   

   L'ambito obbligatorio è "https://search.azure.com/.default".

2. Dopo aver ottenuto un token, è possibile eseguire una richiesta al servizio di ricerca.

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

Vedi anche

• Usare il controllo degli accessi in base al ruolo di Azure in Ricerca di intelligenza artificiale di Azure
• Autorizzare l'accesso alle applicazioni Web di Microsoft Entra usando il flusso di concessione del codice OAuth 2.0
• Integrazione con Microsoft Entra ID
• Ruoli personalizzati di Azure