Connettersi a Azure AI Search usando i ruoli
Azure offre un’autenticazione globale e un sistema di autorizzazione basato su ruoli per tutti i servizi in esecuzione nella piattaforma. In Azure AI Search è possibile assegnare ruoli di Azure per:
L'accesso per utente ai risultati della ricerca (talvolta definito sicurezza a livello di riga o sicurezza a livello di documento) non è supportato tramite le assegnazioni di ruolo. Come soluzione alternativa, creare filtri di sicurezza che tagliano i risultati in base all'identità utente, rimuovendo i documenti ai quali il richiedente non deve avere accesso. Per una dimostrazione, vedere questo esempio di chat aziendale tramite RAG.
Le assegnazioni di ruolo sono cumulative e diffuse su tutti gli strumenti e le librerie client. È possibile assegnare ruoli usando uno degli approcci supportati descritti nella documentazione sul controllo degli accessi in base al ruolo di Azure.
L'accesso basato sui ruoli è facoltativo, ma consigliato. L'alternativa è l’autenticazione basata su chiave, ovvero l'impostazione predefinita.
Prerequisiti
Un servizio di ricerca in qualsiasi area, a qualsiasi livello, abilitato per l'accesso basato sui ruoli.
Proprietario, Amministratore accesso utenti o un ruolo personalizzato con autorizzazioni Microsoft.Authorization/roleAssignments/write.
Ruoli predefiniti usati in Azure AI Search
Vengono compilati i ruoli seguenti. Se questi ruoli non sono sufficienti, creare un ruolo personalizzato.
Ruolo | Plane | Descrizione |
---|---|---|
Proprietario | Controllo e dati | Accesso completo al piano di controllo della risorsa di ricerca, inclusa la possibilità di assegnare ruoli di Azure. Solo il ruolo Proprietario può abilitare o disabilitare le opzioni di autenticazione o gestire i ruoli per altri utenti. Gli amministratori delle sottoscrizioni sono membri per impostazione predefinita. Nel piano dati, questo ruolo ha lo stesso accesso del ruolo Collaboratore del servizio di ricerca. Include l'accesso a tutte le azioni del piano dati, ad eccezione della possibilità di eseguire query o indicizzare documenti. |
Collaboratore | Controllo e dati | Stesso livello di accesso al piano di controllo del ruolo Proprietario, ma senza la possibilità di assegnare ruoli o modificare le opzioni di autenticazione. Nel piano dati, questo ruolo ha lo stesso accesso del ruolo Collaboratore del servizio di ricerca. Include l'accesso a tutte le azioni del piano dati, ad eccezione della possibilità di eseguire query o indicizzare documenti. |
Lettore | Controllo e dati | Accesso in lettura sull’intero servizio, incluse le metriche di ricerca, le metriche del contenuto (archiviazione utilizzata, numero di oggetti) e le definizioni degli oggetti delle risorse del piano dati (indici, indicizzatori e così via). Tuttavia, non può leggere le chiavi API né il contenuto all'interno degli indici. |
Collaboratore servizi di ricerca | Controllo e dati | Accesso in lettura/scrittura alle definizioni di oggetti (indici, alias, mappe sinonimi, indicizzatori, origini dati e set di competenze). Questo ruolo è destinato agli sviluppatori che creano oggetti e agli amministratori che gestiscono un servizio di ricerca e i relativi oggetti, ma senza accesso al contenuto dell'indice. Usare questo ruolo per creare, eliminare ed elencare indici, ottenere definizioni di indice, ottenere informazioni sul servizio (statistiche e quote), testare analizzatori, creare e gestire mappe sinonimiche, indicizzatori, origini dati e set di competenze. Vedere Microsoft.Search/searchServices/* per consultare l'elenco delle autorizzazioni. |
Collaboratore ai dati dell'indice di ricerca | Dati | Accesso in lettura/scrittura al contenuto degli indici. Questo ruolo è destinato agli sviluppatori o ai proprietari di indici che devono importare, aggiornare o eseguire query sulla raccolta documenti di un indice. Questo ruolo non supporta la creazione o la gestione degli indici. Per impostazione predefinita, questo ruolo è per tutti gli indici in un servizio di ricerca. Vedere Concedere l'accesso a un singolo indice per restringere l'ambito. |
Lettore di dati dell'indice di ricerca | Dati | Accesso in sola lettura per l'esecuzione di query sugli indici di ricerca. Questo ruolo è destinato ad app e utenti che eseguono query. Questo ruolo non supporta l'accesso in lettura alle definizioni degli oggetti. Ad esempio, non è possibile leggere la definizione di un indice di ricerca o ottenere statistiche del servizio di ricerca. Per impostazione predefinita, questo ruolo è per tutti gli indici in un servizio di ricerca. Vedere Concedere l'accesso a un singolo indice per restringere l'ambito. |
Combinare questi ruoli per ottenere autorizzazioni sufficienti per il caso d’uso.
Nota
Se si disabilita l'accesso in base al ruolo di Azure, i ruoli predefiniti per il piano di controllo (Proprietario, Collaboratore, Lettore) continuano a essere disponibili. La disabilitazione dell'accesso basato sui ruoli rimuove solo le autorizzazioni correlate ai dati associate a tali ruoli. Se i ruoli del piano dati sono disabilitati, Collaboratore del servizio di ricerca equivale a Collaboratore del piano di controllo.
Assegnazione di ruoli
In questa sezione assegnare ruoli per:
-
Ruolo ID Owner
8e3af657-a8ff-443c-a75c-2fe8c4bcb635 Contributor
b24988ac-6180-42a0-ab88-20f7382dd24c Reader
acdd72a7-3385-48ef-bd42-f606fba81ae7 Sviluppo o accesso in scrittura a un servizio di ricerca
Attività Ruolo ID Operazioni CRUD Search Service Contributor
7ca78c08-252a-4471-8644-bb5ff32d4ba0 Caricare documenti ed eseguire processi di indicizzazione Search Index Data Contributor
8ebe5a00-799e-43f5-93ac-243d3dce84a7 Eseguire una query su un indice Search Index Data Reader
1407120a-92aa-4202-b7e9-c0e197c71c8f Accesso in sola lettura per le query
Ruolo ID Search Index Data Reader
con PowerShell1407120a-92aa-4202-b7e9-c0e197c71c8f
Assegnare ruoli per l'amministrazione del servizio
Gli amministratori del servizio possono creare e configurare un servizio di ricerca ed eseguire tutte le operazioni del piano di controllo descritte nell'API REST di gestione o nelle librerie client equivalenti. A seconda del ruolo, è inoltre possibile eseguire la maggior parte delle attività dell'API REST di ricerca del piano dati.
Accedere al portale di Azure.
Passare al servizio di ricerca.
Selezionare Controllo di accesso (IAM) nel riquadro di spostamento a sinistra.
Selezionare Aggiungi>Aggiungi assegnazione di ruolo.
Selezionare un ruolo valido:
- Proprietario (accesso completo a tutte le operazioni del piano dati e del piano di controllo, ad eccezione delle autorizzazioni di query)
- Collaboratore (uguale a Proprietario, ad eccezione delle autorizzazioni per assegnare i ruoli)
- Lettore (accettabile per il monitoraggio e la visualizzazione delle metriche)
Nella scheda Membri selezionare l'identità dell'utente o del gruppo Microsoft Entra.
Nella scheda Rivedi e assegna selezionare Rivedi e assegna per assegnare il ruolo.
Assegnare ruoli per lo sviluppo
Le assegnazioni di ruolo sono globali su tutto il servizio di ricerca. Per definire l'ambito delle autorizzazioni per un singolo indice, usare PowerShell o l'interfaccia della riga di comando di Azure per creare un ruolo personalizzato.
Un'altra combinazione di ruoli che fornisce l'accesso completo è Collaboratore o Proprietario, oltre a Lettore dati dell’indice di ricerca.
Importante
Se si configura l’accesso in base al ruolo per un servizio o un indice e si fornisce anche una chiave API nella richiesta, il servizio di ricerca usa la chiave API per l’autenticazione.
Accedere al portale di Azure.
Passare al servizio di ricerca.
Selezionare Controllo di accesso (IAM) nel riquadro di spostamento a sinistra.
Selezionare Aggiungi>Aggiungi assegnazione di ruolo.
Selezionare un ruolo:
- Collaboratore al servizio di ricerca (operazioni create-read-update-delete su indici, indicizzatori, set di competenze e altri oggetti di primo livello)
- Collaboratore ai dati dell'indice di ricerca (caricare documenti ed eseguire processi di indicizzazione)
- Lettore di dati dell'indice di ricerca (eseguire query su un indice)
Un'altra combinazione di ruoli che fornisce l'accesso completo è Collaboratore o Proprietario, oltre a Lettore dati dell’indice di ricerca.
Nella scheda Membri selezionare l'identità dell'utente o del gruppo Microsoft Entra.
Nella scheda Rivedi e assegna selezionare Rivedi e assegna per assegnare il ruolo.
Ripetere l’operazione per gli altri ruoli. La maggior parte degli sviluppatori ha bisogno di tutti e tre.
Assegnare ruoli per query di sola lettura
Usare il ruolo Lettore dati dell'indice di ricerca per app e processi che richiedono il solo accesso in lettura a un indice.
Questo è un ruolo molto specifico. Concede l'accesso GET o POST alla raccolta di documenti di un indice di ricerca per la ricerca, il completamento automatico e i suggerimenti. Non supporta operazioni GET o LIST su un indice o su altri oggetti di primo livello, né statistiche del servizio GET.
Questa sezione illustra i passaggi di base per configurare l’assegnazione di ruolo ed è qui per completezza ma è consigliabile Usare Azure AI Search senza chiavi per istruzioni complete sulla configurazione dell’app per l’accesso basato sui ruoli.
Accedere al portale di Azure.
Passare al servizio di ricerca.
Selezionare Controllo di accesso (IAM) nel riquadro di spostamento a sinistra.
Selezionare Aggiungi>Aggiungi assegnazione di ruolo.
Selezionare il ruolo Lettore dati dell’indice di ricerca.
Nella scheda Membri selezionare l'identità dell'utente o del gruppo Microsoft Entra. Se si configurano le autorizzazioni per un altro servizio, è possibile usare un'identità gestita dal sistema o dall'utente. Scegliere questa opzione se l'assegnazione di ruolo è per un'identità del servizio.
Nella scheda Rivedi e assegna selezionare Rivedi e assegna per assegnare il ruolo.
Testare le assegnazioni di ruolo
Usare un client per testare le assegnazioni di ruolo. Tenere presente che i ruoli sono cumulativi e che i ruoli ereditati con ambito a livello di sottoscrizione o gruppo di risorse non possono essere eliminati o negati a livello di risorsa (servizio di ricerca).
Configurare l’applicazione per le connessioni senza chiave e disporre di assegnazioni di ruolo prima del test.
Accedere al portale di Azure.
Passare al servizio di ricerca.
Nella pagina di panoramica selezionare la scheda Indici:
I collaboratori del servizio di ricerca possono visualizzare e creare qualsiasi oggetto, ma non caricare documenti o eseguire query su un indice. Per verificare le autorizzazioni, creare un indice di ricerca.
I collaboratori ai dati dell'indice di ricerca possono caricare documenti. Non è disponibile alcuna opzione per caricare i documenti nel portale al di fuori dell’Importazione guidata dati, ma è possibile reimpostare ed eseguire un indicizzatore per confermare le autorizzazioni per il caricamento dei documenti.
I lettori dati dell'indice di ricerca possono eseguire query sull'indice. Per verificare le autorizzazioni, usare Esplora ricerche. Dovrebbe essere possibile inviare query e visualizzare i risultati, ma non visualizzare la definizione dell'indice o crearne una.
Testare come utente corrente
Se si è già un collaboratore o proprietario del servizio di ricerca, è possibile presentare un token di connessione per l'autenticazione dell’identità utente in Azure AI Search.
Ottenere un token di connessione per l'utente corrente usando l'interfaccia della riga di comando di Azure:
az account get-access-token --scope https://search.azure.com/.default
O usando PowerShell:
Get-AzAccessToken -ResourceUrl https://search.azure.com
Incollare queste variabili in un nuovo file di testo in Visual Studio Code.
@baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE @index-name = PASTE-YOUR-INDEX-NAME-HERE @token = PASTE-YOUR-TOKEN-HERE
Incollare e inviare una richiesta per confermare l'accesso. In questo esempio viene eseguita una query sull'indice hotels-quickstart
POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2024-07-01 HTTP/1.1 Content-type: application/json Authorization: Bearer {{token}} { "queryType": "simple", "search": "motel", "filter": "", "select": "HotelName,Description,Category,Tags", "count": true }
Concedere l'accesso a un singolo indice
In alcuni scenari, è possibile limitare l'accesso di un'applicazione a una singola risorsa, ad esempio un indice.
Il portale attualmente non supporta le assegnazioni di ruolo a questo livello di granularità, ma può essere eseguito con PowerShell o con l'interfaccia della riga di comando di Azure.
In PowerShell usare New-AzRoleAssignment, specificando il nome dell'utente o del gruppo di Azure e l'ambito dell'assegnazione.
Caricare i moduli
Azure
eAzureAD
e connettersi all'account Azure:Import-Module -Name Az Import-Module -Name AzureAD Connect-AzAccount
Aggiungere un'assegnazione di ruolo con ambito definito per un singolo indice:
New-AzRoleAssignment -ObjectId <objectId> ` -RoleDefinitionName "Search Index Data Contributor" ` -Scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"
Creare un ruolo personalizzato
Se i ruoli predefiniti non forniscono la corretta combinazione di autorizzazioni, è possibile creare un ruolo personalizzato per supportare le operazioni necessarie.
In questo esempio viene clonato Lettore dati dell'indice di ricerca e poi viene aggiunta la possibilità di elencare gli indici in base al nome. In genere, elencare gli indici in un servizio di ricerca è considerato un diritto amministrativo.
Questi passaggi sono derivati da Creare o aggiornare ruoli personalizzati di Azure con il portale di Azure. La clonazione di un ruolo esistente è supportata in una pagina del servizio di ricerca.
Questa procedura crea un ruolo personalizzato che aumenta i diritti di query di ricerca includendo la possibilità di elencare gli indici in base al nome. In genere, l'elenco degli indici è considerato una funzione da amministratore.
Nel portale di Azure passare al servizio di ricerca.
Nel pannello di navigazione a sinistra selezionare Controllo di accesso (IAM).
Nella barra delle azioni selezionare Ruoli.
Fare clic con il pulsante destro del mouse su Lettore dati dell’indice di ricercar (o su un altro ruolo) e selezionare Clona per aprire la procedura guidata Crea un ruolo personalizzato.
Nella scheda Informazioni di base specificare un nome per il ruolo personalizzato, ad esempio "Esplora dati dell'indice di ricerca", quindi selezionare Avanti.
Nella scheda Autorizzazioni selezionare Aggiungi autorizzazione.
Nella scheda Aggiungi autorizzazioni cercare e selezionare il riquadro Microsoft Search.
Impostare le autorizzazioni per il ruolo personalizzato. Nella parte superiore della pagina, usando la selezione predefinita Azioni:
- In Microsoft.Search/operations selezionare Lettura: elencare tutte le operazioni disponibili.
- In Microsoft.Search/searchServices/indexes selezionare Lettura: Lettura indice.
Nella stessa pagina passare a Azioni dati e in Microsoft.Search/searchServices/indexes/documents selezionare Lettura: Lettura documenti.
La definizione JSON è simile all'esempio seguente:
{ "properties": { "roleName": "search index data explorer", "description": "", "assignableScopes": [ "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc" ], "permissions": [ { "actions": [ "Microsoft.Search/operations/read", "Microsoft.Search/searchServices/indexes/read" ], "notActions": [], "dataActions": [ "Microsoft.Search/searchServices/indexes/documents/read" ], "notDataActions": [] } ] } }
Selezionare Rivedi e crea per creare il ruolo. È ora possibile assegnare utenti e gruppi al ruolo.
Accesso condizionale
È consigliabile usare l'accesso condizionale Microsoft Entra se è necessario applicare criteri aziendali, ad esempio l'autenticazione a più fattori.
Per abilitare determinati criteri di accesso condizionale per Azure AI Search, seguire questa procedura:
Accedere al portale di Azure.
Cercare Accesso condizionale Microsoft Entra.
Selezionare Criteri.
Selezionare Nuovi criteri.
Nella sezione App o azioni cloud dei criteri aggiungere Azure AI Search come app cloud a seconda di come si vogliono configurare i criteri.
Aggiornare i parametri rimanenti dei criteri. Ad esempio, specificare a quali utenti e gruppi si applica questo criterio.
Salvare il criterio.
Importante
Se al servizio di ricerca è assegnata un'identità gestita, il servizio di ricerca specifico verrà visualizzato come app cloud che può essere inclusa o esclusa dai criteri di accesso condizionale. I criteri di accesso condizionale non possono essere applicati a un servizio di ricerca specifico. Assicurarsi invece di selezionare l'app cloud Azure AI Search generale.
Limiti
Il controllo degli accessi in base al ruolo può aumentare la latenza di alcune richieste. Ogni combinazione univoca di risorsa del servizio (indice, indicizzatore e così via) ed entità servizio attiva un controllo di autorizzazione. Questi controlli di autorizzazione possono aggiungere fino a 200 millisecondi di latenza per richiesta.
Nei rari casi in cui le richieste provengono da un numero elevato di entità servizio diverse, tutte destinate a risorse del servizio diverse (indici, indicizzatori e così via), è possibile che i controlli di autorizzazione comportino una limitazione delle richieste. La limitazione si verifica solo se vengono usate centinaia di combinazioni univoche di risorse del servizio di ricerca ed entità servizio nell’arco di un secondo.
Risoluzione dei problemi relativi al controllo di accesso basato sui ruoli
Quando si sviluppano applicazioni che usano il controllo degli accessi in base al ruolo per l'autenticazione, possono verificarsi alcuni problemi comuni:
Se il token di autorizzazione proviene da un'identità gestita e le autorizzazioni appropriate sono state assegnate di recente, potrebbero essere necessarie diverse ore affinché queste assegnazioni delle autorizzazioni siano effettive.
La configurazione predefinita per un servizio di ricerca è l’autenticazione basata su chiave. Se l'impostazione della chiave predefinita non è stata modificata in Entrambi o Controllo degli accessi in base al ruolo, tutte le richieste che usano l'autenticazione basata su ruoli vengono negate in automatico, indipendentemente dalle autorizzazioni sottostanti.