Applicazione delle etichette di riservatezza di Microsoft Purview al momento dell'esecuzione della query in Azure AI Search (anteprima)

In fase di query, Azure AI Search può applicare criteri di etichetta di riservatezza definiti in Microsoft Purview. Questi criteri includono la valutazione dei diritti di EXTRACT utilizzo associati a ogni documento, assicurando che gli utenti possano recuperare solo i documenti a cui è consentito l'accesso.

Questa funzionalità estende il controllo di accesso a livello di documento per allinearsi ai requisiti di protezione delle informazioni e conformità dell'organizzazione gestiti in Microsoft Purview.

Quando l'indicizzazione delle etichette di riservatezza di Purview è abilitata, Azure AI Search controlla i metadati delle etichette di ogni documento durante l'esecuzione della query. Applica filtri di accesso basati sui criteri purview per restituire solo i risultati a cui l'utente richiedente è autorizzato ad accedere.

Questo articolo spiega come funziona l'applicazione delle etichette di sensibilità durante le query e come eseguire in modo sicuro le query di ricerca.

Prerequisiti

• Completare tutti i passaggi in Usare gli indicizzatori di Azure AI Search per inserire le etichette di sensibilità di Microsoft Purview.

• Verificare che il servizio Azure AI Search abbia l'identità gestita assegnata dal sistema (non un'identità gestita assegnata dall'utente) abilitata e che contenga le Content.SuperUser assegnazioni di ruolo e UnifiedPolicy.Tenant.Read . L'applicazione in fase di query dipende dai metadati delle etichette che l'indicizzatore può estrarre solo quando l'identità assegnata dal sistema è configurata correttamente. Vedere Passaggio 1 nell'articolo relativo alla configurazione dell'indicizzatore.

• Sia il servizio Azure AI Search che l'utente che esegue la query devono trovarsi nello stesso tenant Microsoft Entra.

• API REST versione 2025-11-01-preview o un pacchetto SDK di anteprima equivalente per eseguire query sull'indice. La funzionalità di lettura con privilegi elevati e la registrazione degli audit di Purview richiedono la versione 2026-05-01-preview o successive.

• Autenticare le query usando il controllo degli accessi in base ai ruoli di Azure (RBAC) e non le chiavi API. Quando le etichette di riservatezza di Purview sono abilitate, l'accesso alla chiave API è limitato al recupero dello schema dell'indice.

Limitazioni

• Gli account guest e le query tra tenant non sono supportati.

• Il completamento automatico e API di suggerimento non sono supportate per indici con funzionalità Purview.

• Se la valutazione dell'etichetta non riesce, il servizio restituisce un codice di errore HTTP specifico anziché un set di risultati parziale o non filtrato. Per l'elenco completo dei codici di errore e delle cause, vedere Risolvere gli errori di query.

• Il sistema valuta le etichette solo quando esistono al momento dell'ultima esecuzione dell'indicizzatore. Le modifiche recenti delle etichette potrebbero non essere riflesse fino alla successiva reindicizzazione pianificata.

Come funziona l'applicazione delle etichette di riservatezza in fase di query

Quando si esegue una query su un indice che include le etichette di riservatezza di Microsoft Purview, Azure AI Search controlla le politiche associate di Microsoft Purview prima di restituire i risultati. In questo modo, la query restituisce solo i documenti a cui il token utente è autorizzato ad accedere.

1. Input di identità utente e ruolo dell'applicazione

In fase di query, Azure AI Search convalida entrambi:

• Ruolo RBAC dell'applicazione chiamante, fornito nell'intestazione Authorization. Il ruolo minimo richiesto è Search Index Data Reader. Per ulteriori dettagli, consultare la guida al controllo degli accessi in base al ruolo di Azure AI Search.
• L'identità dell'utente tramite token, fornita nell'intestazione x-ms-query-source-authorization .

Entrambi sono necessari per autorizzare la visibilità delle etichette.

2. Valutazione delle etichette di riservatezza

Quando viene ricevuta una richiesta di query, Azure AI Search valuta:

1. Campo sensitivityLabel in ogni documento indicizzato (estratto da Microsoft Purview durante l'inserimento).
2. Autorizzazioni Purview in vigore per l'utente, come definito da Microsoft Entra ID e dai criteri di etichettatura di Purview.

Se l'utente non è autorizzato per l'etichetta di riservatezza di un documento con autorizzazioni EXTRACT, tale documento viene escluso dai risultati della query.

3. Filtro dei risultati sicuro

Azure AI Search applica il filtro di sicurezza dopo tutti i filtri definiti dall'utente e i passaggi di assegnazione dei punteggi.
Un documento è incluso nel set di risultati finale solo se:

• L'applicazione chiamante ha un'assegnazione di ruolo valida (tramite RBAC) e
• Il token di identità utente rappresentato da x-ms-query-source-authorization è valido e può visualizzare il contenuto con l'etichetta di riservatezza del documento.

Se una delle due condizioni ha esito negativo, il documento viene omesso dai risultati.

Acquisire un token di accesso utente

Per eseguire query Azure AI Search usando il contesto utente, è necessario acquisire un token di accesso che rappresenta l'utente connesso. L'approccio usato dipende dal fatto che si stia testando localmente con il proprio token, se si ha accesso al documento di origine o implementando il flusso dell'applicazione che richiede il passaggio del token dell'utente finale.

Per scenari di test

Per i test locali, è possibile recuperare un token di accesso utente usando interfaccia della riga di comando di Azure:

$token = az account get-access-token `
  --resource https://search.azure.com `
  --query accessToken `
  --output tsv

Questo approccio usa la sessione di accesso dell'interfaccia della riga di comando di Azure corrente, quindi è possibile usare il contesto sui documenti si hanno autorizzazioni EXTRACT assegnate tramite etichette di riservatezza. Questo metodo è destinato solo agli scenari di sviluppo e convalida.

Acquisizione di token per scenari OBO

Le applicazioni che implementano il flusso OBO (On-behalf-of) devono ottenere token tramite Microsoft Entra ID utilizzando una libreria di autenticazione supportata, ad esempio Libreria di Autenticazione Microsoft (MSAL).

Negli scenari OBO richiedere il token per l'API downstream chiamata dall'applicazione. Ad esempio, quando si chiama Azure AI Search, l'URI della risorsa è https://search.azure.com/.default.

L'ambito .default richiede tutte le autorizzazioni delegate preconsentate dall'applicazione per la risorsa specificata.

Le autorizzazioni delle etichette di riservatezza, tra cui EXTRACT, non sono rappresentate come ambiti OAuth. Il servizio downstream, ad esempio Azure AI Search, valuta queste autorizzazioni in fase di esecuzione in base all'identità utente nel token e ai criteri di etichetta di riservatezza applicati.

Esempio di query

Ecco un esempio di richiesta di query che usa l'applicazione delle etichette di riservatezza di Microsoft Purview.

Passare il token dell'applicazione come token di connessione nell'intestazione Authorization. Passa il token dell'utente come valore non elaborato del token nell'intestazione x-ms-query-source-authorization, senza il prefisso Bearer.

POST  {{endpoint}}/indexes/sensitivity-docs/docs/search?api-version=2025-11-01-preview
Authorization: Bearer {{app-query-token}}
x-ms-query-source-authorization: {{user-query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "title,summary,sensitivityLabel",
    "orderby": "title asc"
}

Lettura approfondita per indagini amministrative (anteprima)

La funzione "Lettura avanzata" consente a uno sviluppatore autorizzato di restituire documenti contrassegnati che l'utente richiedente normalmente non vede, generando al contempo una voce nel registro di controllo di Microsoft Purview per ogni documento restituito dalla richiesta. Usarlo per verifiche di conformità, eDiscovery, risposta agli eventi imprevisti e altre indagini amministrative in cui è necessario un record di accesso controllabile.

La lettura con privilegi elevati è disponibile negli indici abilitati per Purview nella versione 2026-05-01-preview dell'API REST e nelle versioni successive.

Come funziona la lettura elevata

1. L'applicazione chiamante imposta l'intestazione x-ms-enable-elevated-read: true nella richiesta di ricerca.

2. Azure AI Search ignora il controllo di accesso basato su etichetta per documento e restituisce documenti corrispondenti, indipendentemente dalle autorizzazioni EXTRACT dell'utente richiedente per ogni etichetta.

3. Per ogni documento presente nella risposta, Azure AI Search genera una voce nel registro di audit di Microsoft Purview per conto del tenant richiedente. Una singola richiesta di ricerca che restituisce N documenti genera N voci di audit.

4. I record di audit vengono caricati su Purview in modo asincrono dopo che è stata restituita la risposta alla ricerca.

Assegnazione di ruolo obbligatoria

L'utente sviluppatore che effettua la chiamata deve disporre del ruolo Contributore dei dati dell'indice di ricerca nell'ambito del servizio di ricerca o dell'indice. Il lettore di dati dell'indice di ricerca non è sufficiente. L'operazione di lettura fallisce con 403 Forbidden se il ruolo non è stato assegnato. Per altre informazioni sui ruoli di Azure AI Search, vedere Connect to Azure AI Search using roles.

Quando l'intestazione x-ms-enable-elevated-read è impostata su true, l'intestazione x-ms-query-source-authorization non può essere usata.

Esempio di lettura con privilegi elevati

POST  {{endpoint}}/indexes/sensitivity-docs/docs/search?api-version=2026-05-01-preview
Authorization: Bearer {{contributor-token}}
x-ms-enable-elevated-read: true
Content-Type: application/json

{
    "search": "*",
    "select": "title,summary,sensitivityLabel",
    "orderby": "title asc"
}

Campi di controllo inviati a Microsoft Purview

Ogni record di audit segue lo schema API delle attività di gestione di Office 365 e include i seguenti campi.

Riduzione delle prestazioni

Se Azure AI Search non riesce a raggiungere Microsoft Purview durante l'elaborazione di una query, ad esempio durante un'interruzione temporanea di Purview, ignora la valutazione delle etichette per tale richiesta. Il comportamento dipende dal fatto che la richiesta includa un token di identità utente:

• Richieste di lettura elevate (x-ms-enable-elevated-read: true): la richiesta ha esito negativo con 5xx. Azure AI Search non restituisce documenti etichettati senza essere prima in grado di generare log di controllo.

• Richieste standard con etichetta obbligatoria (con x-ms-query-source-authorization): La richiesta non va a buon fine con 5xx. Azure AI Search non restituisce risultati parziali o non filtrati quando non è in grado di valutare i criteri di etichetta.

• Chiamate senza x-ms-query-source-authorization emesse da un'applicazione con almeno il ruolo Lettore dei dati dell'indice di ricerca : La richiesta va a buon fine e restituisce solo i documenti che non presentano un'etichetta di riservatezza. I documenti etichettati vengono omessi dalla risposta.

Questa modalità degradata è destinata esclusivamente ai flussi di lavoro non visibili all'utente che accettano esplicitamente solo risultati privi di etichetta. Non basarsi su di esso per le esperienze di ricerca degli utenti finali.

Per l'elenco completo dei codici di errore restituiti durante la valutazione dell'etichetta di riservatezza in fase di query, vedere Risolvere gli errori di query.

Trovare i log di controllo delle operazioni di lettura con privilegi elevati in Microsoft Purview

Azure AI Search carica le voci di audit nel registro di controllo di Microsoft Purview del tenant chiamante. Per esaminare l'elevata attività di lettura:

1. Nel Portale di Microsoft Purview selezionare Solutions>Audit.

2. Selezionare Audit Search e quindi filtrare in base all'intervallo di date, all'utente o al tipo di record Azure AI Search.

3. Aprire una voce per visualizzare i campi dello schema standard e i campi personalizzati Azure AI Search, tra cui SensitivityLabelName, DocumentDataSourceType e DocumentDataSourceId.

Per indicazioni dettagliate sull'esecuzione di ricerche di controllo, sul comportamento di conservazione e sui ruoli Purview necessari, vedere Search the audit log in the Portale di Microsoft Purview.

Gestione delle etichette di riservatezza in Azure AI Search

Quando Azure AI Search indicizza il contenuto del documento con etichette di riservatezza provenienti da origini come SharePoint, Azure BLOB e altri, archivia sia il contenuto che i metadati dell'etichetta. La query di ricerca restituisce contenuto indicizzato insieme al GUID che identifica l'etichetta di riservatezza applicata al documento, solo se l'utente ha accesso ai dati EXTRACT per il documento assegnato tramite la definizione dell'etichetta di riservatezza. Questo GUID identifica in modo univoco l'etichetta, ma non include proprietà leggibili, ad esempio il nome dell'etichetta o le autorizzazioni associate.

Si noti che il GUID da solo non è sufficiente per gli scenari che includono l'interfaccia utente perché le etichette di riservatezza spesso includono altri controlli dei criteri applicati da Microsoft Purview Information Protection, ad esempio: autorizzazioni di stampa o screenshot e restrizioni di acquisizione dello schermo. Azure AI Search non offre queste funzionalità.

Per visualizzare i nomi delle etichette e/o applicare restrizioni specifiche dell'interfaccia utente, l'applicazione deve chiamare l'endpoint Microsoft Purview Information Protection per recuperare i metadati completi dell'etichetta e le autorizzazioni associate.

È possibile usare il GUID restituito da Azure AI Search per risolvere le proprietà dell'etichetta e chiamare le API Purview Labels per recuperare il nome dell'etichetta, la descrizione e le impostazioni dei criteri.

Risolvere gli errori di query

Quando la valutazione dell'etichetta di riservatezza in fase di query ha esito negativo, Azure AI Search restituisce un codice di errore HTTP specifico che identifica la causa. Il servizio non restituisce mai un set di risultati parziale o non filtrato. Se non è possibile valutare i criteri di etichetta, la query ha esito negativo anziché esporre contenuto non etichettato o non autorizzato.

400 Richiesta non valida

Un errore 400 indica un problema con la configurazione dell'indice o le intestazioni della richiesta. Correggere la configurazione prima di riprovare.

401 - Non autorizzato

Un errore 401 indica un problema con il token di autorizzazione o le autorizzazioni purview dell'applicazione.

502 Gateway non valido

Un errore 502 indica un errore di connettività tra Azure AI Search e Microsoft Purview. Questi errori sono in genere temporanei.

Timeout del gateway 504

Un errore 504 indica che Microsoft Purview non ha risposto entro il tempo consentito.

Configurazione dei test end-to-end

Per aiutare a convalidare la configurazione dell'etichetta di riservatezza in Azure AI Search, vedere l'impostazione end-to-end di riferimento.

Questo repository mostra come:

• Configurare la sincronizzazione e il rispetto delle etichette di riservatezza in Azure AI Search
• Testare gli scenari di inserimento e applicazione in fase di query per i documenti con etichette di riservatezza
• Estrarre il nome dell'etichetta ed esporlo come parte delle citazioni usate nelle applicazioni o negli agenti RAG.