Applicazione in fase di query delle etichette di riservatezza di Microsoft Purview in Azure AI Search

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 e conformità dell'informazione 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 la fase di interrogazione. Applica filtri di accesso basati sui criteri purview per restituire solo i risultati a cui l'utente richiedente è autorizzato ad accedere.

Questo articolo illustra il funzionamento dell'applicazione delle etichette di riservatezza in fase di query e come eseguire query di ricerca sicure.

Prerequisiti

• Completare tutti i passaggi in Usare gli indicizzatori di Azure AI Search per integrare le etichette di riservatezza di Microsoft Purview.

• 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.

• Autenticare le query usando il controllo degli accessi in base al ruolo di Azure (RBAC), 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 le API di suggestioni non sono supportate per gli indici abilitati a Purview.

• Se la valutazione dell'etichetta ha esito negativo (ad esempio, le API Purview sono temporaneamente non disponibili), il servizio restituisce 5xx e non restituisce un set di risultati parziale o non filtrato.

• 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.

Funzionamento dell'applicazione delle etichette di riservatezza al momento della query

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

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.
• L'identità dell'utente tramite token, fornita nell'intestazione x-ms-query-source-authorization .

Entrambi sono necessari per autorizzare la visibilità basata sull'etichetta.

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. Le autorizzazioni valide di Microsoft Purview dell'utente, come definite dai criteri delle etichette di Microsoft Entra ID e Purview.

Se l'utente non è autorizzato per l'etichetta di sensibilità di un documento con i permessi 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 utilizza la sessione di accesso corrente di interfaccia della riga di comando di Azure, quindi è possibile utilizzare il contesto sui documenti sui quali sono state assegnate autorizzazioni 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 acquisire token tramite Microsoft Entra ID usando una libreria di autenticazione supportata, ad esempio Libreria di Autenticazione Microsoft (MSAL).

Negli scenari OBO il token deve essere richiesto 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 che sono state pre-autorizzate per l'applicazione alla risorsa specificata.

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

Esempio di query

Di seguito è riportato un esempio di richiesta di query utilizzando l'applicazione delle etichette di riservatezza di Microsoft Purview. Il token dell'applicazione viene passato come bearer token nell'intestazione Authorization. Il token utente viene passato 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"
}

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.

Impostazione dei test end-to-end

Per aiutarvi a convalidare la configurazione dell'etichetta di riservatezza in Azure AI Search, ecco un esempio di configurazione di riferimento.

Questo repository dimostra:

• Come configurare la sincronizzazione e la gestione delle etichette di riservatezza in Azure AI Search
• Come testare gli scenari di inserimento e applicazione in fase di query per i documenti con etichette di riservatezza
• Come estrarre il nome dell'etichetta e includerlo come parte delle citazioni utilizzate nelle applicazioni o nei sistemi RAG.