Controllo di accesso a livello di documento in Azure AI Search

Azure AI Search supporta il controllo di accesso a livello di documento, consentendo alle organizzazioni di applicare autorizzazioni con granularità fine a livello di documento, dall'inserimento dei dati all'esecuzione di query. Questa funzionalità è essenziale per creare dati di base di sistemi agentici di IA sicuri, applicazioni di generazione aumentata dal recupero (RAG) e soluzioni di ricerca aziendale che richiedono controlli di autorizzazione a livello di documento.

Approcci per il controllo di accesso a livello di documento

Azure AI Search offre quattro approcci principali per applicare autorizzazioni a livello di documento, ognuna adatta a origini dati e modelli di identità diversi.

Per le origini delle informazioni indicizzate, ingestionPermissionOptions non è possibile combinare con assetStore. Pertanto, la gestione delle immagini (anteprima) non è disponibile quando è abilitata l'inserimento di autorizzazioni a livello di documento nativo.

Scegliere un approccio

Usare i criteri seguenti per identificare l'approccio più adatto ai requisiti di origine dati, modello di identità e conformità.

Modello per la gestione della sicurezza attraverso filtri

Negli scenari in cui l'integrazione degli ambiti ACL/RBAC nativi non è praticabile, utilizzare i filtri di stringa di sicurezza per sfoltire i risultati in base ai criteri di esclusione. Il modello include i componenti seguenti:

• Per archiviare le identità utente o di gruppo, creare un campo stringa nell'indice.
• Caricate l'indice utilizzando documenti di origine che includono elenchi di controllo di accesso associati.
• Includere un'espressione di filtro nella logica di query affinché corrisponda alla stringa.
• In fase di query ottenere l'identità del chiamante.
• Trasmettere l'identità del chiamante come stringa del filtro.
• I risultati vengono tagliati per escludere eventuali corrispondenze che non riescono a includere la stringa di identità dell'utente o del gruppo.

È possibile usare le API del modello push o pull. Poiché questo approccio è indipendente dall'API, è sufficiente verificare che l'indice e la query abbiano stringhe (identità) valide per il passaggio di filtraggio.

Questo approccio è utile per i sistemi con modelli di accesso personalizzati o framework di sicurezza non Microsoft. Per altre informazioni su questo approccio, vedere Filtri di sicurezza per limitare i risultati in Azure AI Search.

Modello per il supporto nativo delle autorizzazioni ACL simili a POSIX e del controllo degli accessi basato sui ruoli (RBAC) (anteprima)

Il supporto nativo si basa sugli utenti e gruppi di Microsoft Entra associati ai documenti che si vogliono indicizzare e interrogare.

i contenitori di Azure Data Lake Storage (ADLS) Gen2 supportano gli elenchi di controllo di accesso nel contenitore e nei file. Per ADLS Gen2, la preservazione dello scope RBAC a livello documento è supportata in modo nativo quando si utilizza un indicizzatore ADLS Gen2 o un'origine di conoscenza BLOB (supporta ADLS Gen2) e un'API di anteprima per ingestire contenuti. Per i BLOB di Azure che usano l'indicizzatore BLOB di Azure o la fonte delle informazioni, l'ambito del controllo degli accessi in base al ruolo è a livello di contenitore.

Per i contenuti protetti da ACL, preferire l'accesso di gruppo rispetto all'accesso per singolo utente per semplificare la gestione. Il modello include i componenti seguenti:

• Iniziare con documenti o file con assegnazioni ACL.
• Abilitare i filtri di autorizzazione nell'indice.
• Aggiungere un filtro di autorizzazione a un campo stringa in un indice.
• Carica l'indice con documenti sorgente che hanno ACL (elenchi di controllo di accesso) associati.
• Eseguire una query sull'indice aggiungendo x-ms-query-source-authorization nell'intestazione della richiesta.

L'app client riceve le autorizzazioni di lettura per l'indice tramite il ruolo Lettore dati indice di ricerca o Collaboratore ai dati dell'indice di ricerca . L'accesso in fase di query è determinato dai metadati di autorizzazione utente o gruppo nel contenuto indicizzato. Le query che includono un filtro di autorizzazione passano un token utente o di gruppo come x-ms-query-source-authorization nell'intestazione della richiesta. Quando si usano filtri di autorizzazione in fase di query, Azure AI Search verifica la presenza di due elementi:

• Prima di tutto, verifica l'autorizzazione search index data reader che consente all'applicazione client di accedere all'indice.

• In secondo luogo, dato il token aggiuntivo nella richiesta, verifica la presenza di autorizzazioni utente o di gruppo per i documenti restituiti nei risultati della ricerca, esclusi quelli che non corrispondono.

Per ottenere i metadati delle autorizzazioni nell'indice, usare l'API del modello push, eseguire il push di tutti i documenti JSON nell'indice di ricerca, in cui il payload include un campo stringa che fornisce ACL simili a POSIX per ogni documento. La differenza importante tra questo approccio e la limitazione per motivi di sicurezza consiste nel fatto che i metadati del filtro delle autorizzazioni nell'indice e nella query vengono riconosciuti come autenticazione Microsoft Entra ID, mentre la soluzione alternativa di limitazione per motivi di sicurezza è un semplice confronto tra stringhe. È anche possibile usare Graph SDK per recuperare le identità.

È anche possibile usare le API del modello pull (indicizzatore) se l'origine dati è Azure Data Lake Storage (ADLS) Gen2 e il codice chiama un'API di anteprima per l'indicizzazione.

Recuperare i metadati delle autorizzazioni ACL durante il processo di inserimento dati (anteprima)

La modalità di recupero delle autorizzazioni ACL varia a seconda che si stia eseguendo il push di un payload di documenti o usando l'indicizzatore ADLS Gen2.

Iniziare con un'API di anteprima che fornisce la funzionalità:

• REST API 2026-05-01-preview
• pacchetto prerelease di Azure SDK per Python. Controlla il changelog della versione di anteprima più recente che supporta l'acquisizione degli ambiti ACL e RBAC.
• Pacchetto prerelease di Azure SDK per .NET. Controlla il changelog della versione di anteprima più recente che supporta l'acquisizione degli ambiti ACL e RBAC.
• Pacchetto prerelease di Azure SDK per Java. Controlla il changelog della versione di anteprima più recente che supporta l'acquisizione degli ambiti ACL e RBAC.

Per l'approccio del modello push:

1. Verificare che lo schema dell'indice sia stato creato con un SDK di anteprima o versione preliminare e che lo schema disponga di filtri di autorizzazione.
2. È consigliabile usare Microsoft Graph SDK per ottenere identità di gruppo o utente.
3. Usare l'API Index Documents o equivalente Azure SDK per eseguire il push dei documenti e i metadati delle autorizzazioni associati nell'indice di ricerca.

Per l'approccio dell'indicizzatore ADLS Gen2 del modello pull o la fonte delle informazioni BLOB (ADLS Gen2):

1. Verificare che i file nella directory siano protetti usando il modello di controllo di accesso di ADLS Gen2.
2. Usare Indexers - Create (API REST), Knowledge Sources - Create (API REST) o un'API Azure SDK equivalente per creare l'indicizzatore, l'indice e l'origine dati.

Se il set di competenze suddivide i documenti in blocchi, ad esempio con la competenza Suddivisione del testo per la vettorializzazione integrata, i campi dei metadati delle autorizzazioni passano dai mapping dei campi dell'indicizzatore alle proiezioni dell'indice. Vedi Scegliere dove compilare i campi ACL.

Modello per SharePoint in Microsoft 365 per l'acquisizione delle autorizzazioni ACL di base (anteprima)

Per il contenuto indicizzato SharePoint, Azure AI Search può archiviare le autorizzazioni di origine come metadati e usarle per filtrare i risultati delle query. È possibile accedere a questa funzionalità in anteprima tramite il SharePoint in Microsoft 365 indicizzatore e l'API 2026-05-01-preview REST o un pacchetto SDK di anteprima equivalente.

Per i requisiti di autorizzazione, le relazioni di gruppo supportate, la sincronizzazione delle autorizzazioni e le limitazioni, vedere Usare un indicizzatore SharePoint per inserire i metadati delle autorizzazioni.

Se il set di competenze suddivide i documenti (ad esempio, con la competenza Suddivisione del testo per la vettorializzazione integrata), i campi ACL vengono spostati dalle mappature dei campi dell'indicizzatore alle proiezioni dell'indice. Vedi Scegliere dove compilare i campi ACL.

Modello di etichette di riservatezza di Microsoft Purview (anteprima)

Quando si abilita l'acquisizione delle etichette, Azure AI Search estrae i metadati di sensibilità dalle origini dati supportate. Queste origini dati includono Archiviazione BLOB di Azure, Azure Data Lake Storage Gen2 (ADLS Gen2), SharePoint in Microsoft 365 e Microsoft OneLake. Le etichette estratte vengono archiviate nell'indice insieme al contenuto del documento.

In fase di query, Azure AI Search controlla l'etichetta di riservatezza di ogni documento, il token di Microsoft Entra dell'utente e i criteri purview dell'organizzazione per determinare l'accesso. Il sistema restituisce documenti solo se l'identità dell'utente e le autorizzazioni basate sulle etichette consentono l'accesso in base ai criteri Purview configurati.

Questo modello include i componenti seguenti:

• Configurare l'indice, l'origine dati e l'indicizzatore (a scopo di pianificazione) usando l'API REST 2026-05-01-preview o un SDK corrispondente che supporta l'inserimento di etichette Purview.
• Abilitare un'identità gestita assegnata dal sistema nel servizio di ricerca. Le identità gestite assegnate dall'utente non sono supportate per l'estrazione delle etichette di Purview; l'identità del servizio deve disporre delle autorizzazioni con privilegi elevati di Purview. Chiedere quindi all'amministratore globale del tenant o all'amministratore del ruolo con privilegi di concedere l'accesso necessario per consentire al servizio di ricerca di eseguire l'autenticazione con Microsoft Purview ed estrarre i metadati dell'etichetta.
• Applicare etichette di riservatezza ai documenti prima dell'indicizzazione in modo che il sistema possa riconoscerli e conservarli durante l'inserimento.
• In fase di query collegare un token di Microsoft Entra valido tramite l'intestazione x-ms-query-source-authorization a ogni richiesta di query. Azure AI Search valuta il token e i metadati dell'etichetta associati per applicare il controllo degli accessi in base all'etichetta.

L'applicazione forzata delle etichette di riservatezza di Purview è limitata agli scenari con tenant singolo e richiede l'autenticazione RBAC. Durante l'anteprima, è supportato solo tramite l'API REST e Azure SDK. Il completamento automatico e le API Suggest non sono attualmente disponibili per gli indici con Purview abilitato.

Dove vengono visualizzate le etichette di riservatezza

Prima che il sistema possa applicare etichette in fase di query o restituirle nelle risposte di recupero, è necessario prima sincronizzare i metadati dell'etichetta nell'indice. Entrambi i percorsi di utilizzo descritti in questa sezione dipendono da questo passaggio di sincronizzazione. È possibile sincronizzare le etichette configurando un indicizzatore di Azure AI Search direttamente rispetto a un'origine dati supportata oppure abilitando l'opzione di acquisizione equivalente quando si crea un'origine della conoscenza. In entrambi i casi, l'ambiente deve soddisfare i prerequisiti di configurazione per la sincronizzazione dei metadati delle etichette di riservatezza (identità gestita, controllo degli accessi in base al ruolo (RBAC) nel servizio di ricerca e le autorizzazioni necessarie in Microsoft Purview e per l'origine dati). Per configurare completamente l'indicizzatore, vedere Usare gli indicizzatori di Azure AI Search per acquisire le etichette di riservatezza di Microsoft Purview. Per l'ingestione basata sull'origine dati, impostare ingestionPermissionOptions in modo da includere sensitivityLabel durante la creazione dell'origine dati.

Dopo aver sincronizzato le etichette, due percorsi di query usano gli stessi metadati delle etichette indicizzate. Scegliere il percorso che corrisponde al modo in cui l'applicazione chiama Azure AI Search:

• API Direct query (/docs/search): allegare il token Microsoft Entra dell'utente in x-ms-query-source-authorization. Gli amministratori possono anche inviare richieste di accesso in lettura con privilegi elevati per indagini verificabili. Per la configurazione e gli esempi, consultare Applicazione in fase di query delle etichette di sensibilità di Microsoft Purview.

• Fonti di conoscenza e recupero agentico (MCP): imposta ingestionPermissionOptions per includere sensitivityLabel nella fonte di conoscenza. L'azione di recupero e lo strumento MCP knowledge_base_retrieve restituiscono valori a livello di riferimento sensitivityLabelInfo e a livello di risposta metadata.responseSensitivityLabelInfo che i client possono utilizzare per la visualizzazione di banner e l'applicazione delle politiche. Per la configurazione, consultare Creazione di una fonte di conoscenza e Verifica dei metadati delle etichette di riservatezza nelle risposte di recupero.

Se la fonte di conoscenza rimanda a un indice suddiviso in blocchi, ad esempio uno creato tramite vettorializzazione integrata o una skill personalizzata di suddivisione del testo, il set di skill deve inoltre assegnare l'etichetta di sensibilità a ciascuna riga del blocco. Senza questa proiezione, i riferimenti a livello di blocco non vengono filtrati.

Per altre informazioni, vedere Usare gli indicizzatori di Azure AI Search per acquisire le etichette di riservatezza di Microsoft Purview.

Applicare le autorizzazioni a livello di documento in fase di query

L'applicazione delle query basata su token è una funzionalità trasversale che si applica agli ambiti ACL e RBAC di tipo POSIX, alle etichette di sensibilità di Microsoft Purview e ai modelli ACL di SharePoint in Microsoft 365. Usando l'esecuzione di query native basate su token, Azure AI Search convalida il token di Microsoft Entra del chiamante in ogni richiesta e taglia i set di risultati solo ai documenti che il chiamante è autorizzato a leggere in base agli ACL del documento, purché i metadati ACL del documento vengano sincronizzati con l'indice.

Quando si collega il token dell'utente a una richiesta di query tramite l'intestazione x-ms-query-source-authorization, Azure AI Search:

1. Estrae i claim dell'utente, del gruppo e dell'ambito dal token.
2. Confronta tali claim con i metadati dei permessi archiviati insieme ai documenti indicizzati (voci ACL, ambiti RBAC, assegnazioni di etichette Purview o ACL di SharePoint).
3. Restituisce solo documenti i cui metadati di autorizzazione sincronizzati concedono l'accesso al chiamante.

L'applicazione in fase di query confronta le attestazioni Microsoft Entra del richiedente con i metadati relativi alle autorizzazioni già memorizzati nell'indice. Le modifiche alle autorizzazioni nel sistema di origine (Microsoft Entra appartenenza a gruppi, ACL DI ADLS Gen2, assegnazioni di etichette Purview o SharePoint ACL) vengono riflesse solo nei risultati della ricerca dopo che i metadati vengono sincronizzati con l'indice tramite il meccanismo specifico dell'origine, ad esempio un'esecuzione successiva dell'indicizzatore, un aggiornamento push-API o un aggiornamento guidato da Purview. Per SharePoint, le modifiche ACL sugli elementi con autorizzazioni univoche vengono prelevate in modo incrementale in ogni esecuzione dell'indicizzatore a partire dall'API REST 2026-05-01-preview, mentre le modifiche ereditate dagli ambiti padre (sito, libreria, elenco o cartella) richiedono un aggiornamento esplicito. Per altre informazioni, vedere Sincronizzare le autorizzazioni tra il contenuto indicizzato e quello di origine.

Per i passaggi per l'implementazione end-to-end delle query, vedere Applicazione di ACL e RBAC in fase di query in Azure AI Search.

Vantaggi del controllo di accesso a livello di documento

Il controllo di accesso a livello di documento nativo in Azure AI Search offre vantaggi concreti rispetto al filtro lato applicazione:

• Elimina il codice personalizzato per le autorizzazioni: Non è necessario implementare la risoluzione annidata dei gruppi, l'attraversamento di ACL multilivello o il filtraggio dopo la query nella tua applicazione. Azure AI Search gestisce il confronto e il filtro durante l'esecuzione della query.
• Allineato ai controlli di conformità esistenti: Il riutilizzo dei metadati delle autorizzazioni di Microsoft Entra, Microsoft Purview e SharePoint contribuisce a mantenere i risultati della ricerca allineati al sistema di identità di origine. Esaminare il modello di sincronizzazione delle autorizzazioni per ogni origine per comprendere le limitazioni.
• Rispetta le autorizzazioni delle risorse dopo ogni sincronizzazione ACL: per gli approcci basati su token (ACL, ambiti RBAC, etichette Purview, ACL di SharePoint), l'applicazione delle autorizzazioni in fase di query utilizza i metadati relativi alle autorizzazioni che il meccanismo di sincronizzazione specifico per la fonte (esecuzione dell'indicizzatore, aggiornamento tramite API push o aggiornamento di Purview) ha già scritto nell'indice.
• Migliora le prestazioni rispetto alla rifinitura dei risultati dopo la query: Il filtraggio all'interno della pipeline di ricerca è più veloce che caricare nell'applicazione set di risultati più ampi per poi rifinirli lì, soprattutto con volumi di query elevati.
• Riutilizza l'infrastruttura di identità esistente: Microsoft Entra e le identità di SharePoint rimangono il riferimento autorevole per le decisioni relative all'accesso, riducendo così la duplicazione delle identità e il sovraccarico operativo legato alla gestione di un archivio delle autorizzazioni parallelo.

Esercitazioni ed esempi

Esplorare il controllo di accesso a livello di documento in Azure AI Search con altri articoli ed esempi.

• Esercitazione: Indicizzare i metadati delle autorizzazioni di ADLS Gen2 usando un indicizzatore
• azure-search-rest-samples/acl
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API
• azure-search-python-samples/Quickstart-Document-Permissions-Pull-API
• App demo: inserimento e rispetto delle etichette di riservatezza

Contenuto correlato

• Come indicizzare le autorizzazioni a livello di documento usando l'API push
• Come indicizzare le autorizzazioni a livello di documento usando l'indicizzatore ADLS Gen2
• Come indicizzare le autorizzazioni a livello di documento usando il SharePoint nell'indicizzatore Microsoft 365
• Come indicizzare le etichette di riservatezza usando gli indicizzatori
• Come interrogare un indice con etichette di riservatezza abilitate
• Come eseguire una query usando autorizzazioni basate su token Microsoft Entra