Applicazione di ACL e RBAC in fase di esecuzione della query in Azure AI Search (anteprima)

Il controllo di accesso in fase di query (anteprima) garantisce che gli utenti recuperino solo i risultati della ricerca autorizzati ad accedere, in base all'identità, alle appartenenze ai gruppi, ai ruoli o agli attributi. Questa funzionalità è essenziale per la ricerca aziendale sicura e i flussi di lavoro basati sulla conformità.

L'accesso autorizzato dipende dai metadati delle autorizzazioni inseriti durante l'indicizzazione. Per le origini dati dell'indicizzatore con modelli di accesso predefiniti, ad esempio Azure Data Lake Storage (ADLS) Gen2 e SharePoint in Microsoft 365, un indicizzatore può eseguire automaticamente il pull dei metadati delle autorizzazioni per ogni documento. Per altre origini dati, è necessario assemblare manualmente il payload del documento e il payload deve includere sia il contenuto che i metadati delle autorizzazioni associati. Usare quindi le API push per caricare l'indice.

Questo articolo illustra come configurare le query che usano i metadati delle autorizzazioni per filtrare i risultati.

Prerequisiti

• I metadati delle autorizzazioni devono essere inclusi nei filterable campi stringa. Non si userà il filtro nelle query, ma il motore di ricerca compila internamente un filtro per escludere contenuto non autorizzato.

• I metadati di autorizzazione devono essere costituiti da autorizzazioni in stile POSIX, che identificano il livello di accesso e il gruppo o l'ID utente, oppure dall'ID risorsa del contenitore in ADLS Gen2 se si utilizza l'ambito RBAC (controllo degli accessi basato sui ruoli).

• Per l'imposizione basata su ACL con inserimento personalizzato, archiviare userIds e groupIds come ID oggetto (GUID) Microsoft Entra nei campi filtrabili. Al momento della query, il servizio confronta le identità presenti in x-ms-query-source-authorization con gli ID memorizzati. Per informazioni dettagliate sullo schema, vedere Indicizzazione degli elenchi di controllo di accesso ai documenti usando le API REST push (anteprima).

• A seconda dell'origine dati:

  • Per le origini dati ADLS Gen2, è necessario aver configurato elenchi di controllo di accesso (ACL) e/o controllo degli accessi in base ai ruoli di Azure a livello di contenitore.
  • Per le origini dati BLOB di Azure, le assegnazioni di ruolo devono trovarsi nel contenitore. È possibile usare un indicizzatore predefinito, un'origine delle informazioni o api push per indicizzare i metadati delle autorizzazioni nell'indice.
  • Per le origini dati di SharePoint, è necessario configurare gli elenchi di controllo di accesso (ACL). È possibile usare un indicizzatore SharePoint integrato e configurarlo con le funzionalità di inserimento ACL. È anche possibile usare un'origine dati di SharePoint indicizzata e configurarla per applicare le autorizzazioni a livello di documento. Le autorizzazioni basate sui gruppi, inclusi i gruppi di Microsoft 365, sono supportate quando vengono acquisite come ID oggetto di Entra. L'espansione del gruppo avviene in fase di query tramite Microsoft Graph.

• Usare l'API REST nella versione più recente o un pacchetto di anteprima di un Azure SDK per eseguire query sull'indice o sulla fonte di conoscenza. Questa versione dell'API supporta query interne che filtrano i risultati non autorizzati.

Limitazioni

• Se la valutazione ACL ha esito negativo(ad esempio, l'API Graph non è disponibile), il servizio restituisce 5xx e not restituisce un set di risultati parzialmente filtrato.

• L'aggiornamento delle ACL dipende dal metodo di acquisizione. Per evitare decisioni di autorizzazione non aggiornate, pianificare il modo in cui ogni origine propaga le modifiche delle autorizzazioni all'indice:

  • Un indicizzatore pianificato SharePoint aggiorna le modifiche delle autorizzazioni a livello di elemento in ogni esecuzione. Le modifiche apportate a un ambito padre (sito, raccolta, elenco o cartella) ereditate dagli elementi figlio richiedono una risincronizzazione.
  • Un indicizzatore ADLS Gen2 richiede una risincronizzazione per aggiornare gli elenchi di controllo di accesso.
  • L'indicizzazione personalizzata o push richiede di eseguire nuovamente l'indicizzazione dei documenti interessati.

• La visibilità dei documenti richiede entrambi:

  • Il ruolo RBAC dell'applicazione chiamante (intestazione dell'autorizzazione).
  • Identità utente veicolata da x-ms-query-source-authorization.

• Le query iniziali basate su ACL potrebbero riscontrare una latenza superiore rispetto alle richieste successive, a causa del sovraccarico di memorizzazione nella cache e risoluzione delle autorizzazioni.

• Per i contenuti SharePoint indicizzati, un gruppo di Microsoft Entra annidato in un gruppo di SharePoint non viene espanso. La risoluzione transitiva dei gruppi di Microsoft Entra non supporta questa relazione mista. Vedere Relazioni di gruppo supportate.

Limiti di immissione delle liste di controllo degli accessi (ACL) per origine dati

I limiti di immissione dell'elenco di controllo di accesso definiscono il numero di record di autorizzazione distinti che possono essere associati a un file, a una cartella o a un elemento all'interno di un'origine dati connessa. Ogni immissione rappresenta l'identità di un utente o di un gruppo, insieme ai diritti di accesso assegnati all’identità (ad esempio, Lettura, Scrittura o Esecuzione).

Il numero massimo di voci ACL supportate dalla funzionalità di Azure AI Search varia a seconda del tipo di origine dati:

Azure Data Lake Storage Gen2 (ADLS Gen2): ogni file o directory può avere fino a 32 autorizzazioni per le voci ACL. In questo contesto, un'entry indica una singola entità (utente o gruppo) con un set specifico di autorizzazioni. Esempio: l’assegnazione dell'accesso in lettura a “Tutti” e dell'accesso in esecuzione agli “Utenti di Azure” equivarrebbe a due immissioni dell’elenco di controllo di accesso.

SharePoint in Microsoft 365: l'origine dati di SharePoint nella ricerca supporta fino a 1.000 voci di autorizzazione per ogni file. Ogni voce rappresenta un'assegnazione univoca di utenti o gruppi nell'elenco di autorizzazioni dell'elemento. Ciò è distinto dai limiti complessivi degli ambiti di autorizzazione univoci per ogni elenco o raccolta, che determina il numero di elementi che possono avere autorizzazioni univoche.

Questi limiti determinano in che modo Azure AI Search possono rispettare le autorizzazioni a livello di elemento durante l'indicizzazione o il filtro dei risultati della ricerca. Se un elemento supera questi limiti di immissione ACL, le autorizzazioni oltre il limite potrebbero non essere applicate in fase di query.

Funzionamento dell'esecuzione durante il tempo di query

Questa sezione elenca l'ordine delle operazioni di imposizione degli ACL durante l'esecuzione della query. Le operazioni variano a seconda che si usi l'ambito di controllo degli accessi basato sui ruoli (RBAC) di Azure o i gruppi o gli ID utente di Microsoft Entra ID.

1. Input delle autorizzazioni utente

L'applicazione dell'utente finale include un token di accesso di query come parte della richiesta di ricerca, e tale token di accesso è tipicamente l'identità dell'utente. La tabella seguente elenca l'origine delle autorizzazioni utente supportate da Azure AI Search per l'imposizione dell'elenco di controllo di accesso:

2. Costruzione di filtri di sicurezza

Internamente, Azure AI Search costruisce in modo dinamico i filtri di sicurezza in base alle autorizzazioni utente fornite. Questi filtri di sicurezza vengono aggiunti automaticamente a tutti i filtri che potrebbero essere inclusi nella query se l'indice ha l'opzione di filtro delle autorizzazioni abilitata.

Per Azure RBAC, le autorizzazioni sono elenchi di stringhe di ID delle risorse. Nell'origine dati deve essere presente un'assegnazione di ruolo di Azure (lettore dei dati del BLOB di archiviazione) che concede l'accesso al token dell'entità di sicurezza nell'intestazione dell'autorizzazione. Il filtro esclude i documenti se non è presente alcuna assegnazione di ruolo per l'entità dietro il token di accesso nella richiesta.

3. Filtro dei risultati

Il filtro di sicurezza abbina efficacemente gli userIds, i groupIds e il rbacScope dalla richiesta ad ogni elenco ACL di ciascun documento nell'indice di ricerca per limitare i risultati restituiti a quelli a cui l'utente ha accesso. È importante notare che ogni filtro viene applicato in modo indipendente e un documento viene considerato autorizzato se un filtro ha esito positivo. Ad esempio, se un utente ha accesso a un documento tramite userIds ma non tramite groupIds, il documento viene comunque considerato valido e restituito all'utente.

gruppi di SharePoint in fase di esecuzione della query

A partire dall'API REST 2026-05-01-preview, Azure AI Search può rispettare le appartenenze ai gruppi di siti di SharePoint, ad esempio Proprietari, Membri, Visitatori e gruppi di siti personalizzati, in fase di esecuzione della query. Per abilitare questo scenario, l'indice deve includere:

• Proprietà sharePointConnectorAppRegistration che fa riferimento alle credenziali di identità federate dell'applicazione Microsoft Entra usata per chiamare SharePoint per conto dell'utente.
• Campo contrassegnato con l'attributo sharepointSiteUrl: true che archivia l'URL del sito SharePoint per ogni elemento indicizzato (in genere denominato SharePointSiteUrl e popolato dal campo di origine metadata_spo_site_url).

Al momento della query, Azure AI Search usa l'applicazione registrata e l'URL del sito per ogni documento candidato per determinare l'appartenenza ai gruppi di SharePoint dell'utente che effettua la richiesta per tale sito. I gruppi risolti vengono confrontati con i valori preceduti dal prefisso spg: memorizzati nel campo del filtro delle autorizzazioni groupIds. Il prefisso spg: distingue i gruppi di siti di SharePoint dagli ID oggetto dei gruppi di Microsoft Entra, che vengono memorizzati senza prefisso.

Per informazioni dettagliate e limitazioni di configurazione, vedere Configurare il supporto dei gruppi di SharePoint.

Se SharePoint filtro delle autorizzazioni restituisce risultati mancanti o imprevisti, vedere Risolvere i problemi relativi al filtro delle autorizzazioni SharePoint.

Esempio: Query con applicazione dei gruppi del sito SharePoint

La richiesta è identica alla query standard imposta da ACL. Il servizio di ricerca utilizza il sharePointConnectorAppRegistration dell'indice per determinare l'appartenenza ai gruppi di SharePoint per conto del chiamante. Includi GroupIds nella clausola select per visualizzare i valori con prefisso spg: nella risposta.

POST {{endpoint}}/indexes/{index}/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: {{query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,SharePointSiteUrl,GroupIds",
    "orderby": "name asc"
}

Esempio di query

Ecco un esempio di richiesta di query dal codice sample. Il token della query è un token di accesso Microsoft Entra per l'utente che effettua la query.

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: {{query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

Autorizzazioni elevate per l'analisi dei risultati non corretti (anteprima)

Il debug delle query che includono i metadati delle autorizzazioni può essere problematico perché i risultati della ricerca sono specifici di ogni utente. In qualità di sviluppatore o amministratore, potrebbero essere necessarie autorizzazioni elevate per restituire risultati indipendentemente dai metadati delle autorizzazioni, in modo da poter analizzare i problemi relativi alle query che restituiscono contenuto non autorizzato.

Per indagare, è necessario essere in grado di:

• Visualizzare il set di documenti che l'utente finale è in grado di visualizzare in base alle autorizzazioni dell'utente.

• Visualizzare tutti i documenti nell'indice per esaminare il motivo per cui alcuni potrebbero non essere visibili all'utente finale.

È possibile eseguire queste attività aggiungendo un'intestazione personalizzata, x-ms-enable-elevated-read: true, a una query.

Autorizzazioni per le richieste di lettura con privilegi elevati

È necessario disporre delle autorizzazioni di Collaboratore ai dati dell'indice di ricerca o di un ruolo personalizzato che include l'autorizzazione Elevate Read.

Le query sono un'operazione del piano dati, pertanto il ruolo personalizzato può essere costituito solo da autorizzazioni del piano dati atomico. Per un ruolo personalizzato, aggiungere l'autorizzazione Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read.

Aggiungere un'intestazione con privilegi elevati di lettura a una query

Dopo aver configurato le autorizzazioni, è possibile eseguire la query. L'esempio seguente è una richiesta di query su un indice di ricerca.

POST {endpoint}/indexes('{indexName}')/search.post.search?api-version=2026-08-01-preview
Authorization: Bearer {AUTH_TOKEN}
x-ms-query-source-authorization: {TOKEN}
x-ms-enable-elevated-read: true

{
    "search": "prototype tests",
    "select": "filename, author, date",
    "count": true
}

Modifica importante del comportamento delle funzionalità ACL in versioni api di anteprima specifiche

Prima della versione 2025-11-01-preview dell'API REST, le versioni di anteprima precedenti 2025-05-01-preview e 2025-08-01-preview restituivano tutti i documenti quando si utilizzava una chiave API del servizio o ruoli di Entra autorizzati, anche se non era stato fornito alcun token utente. Le applicazioni che non hanno convalidato la presenza di un token utente potrebbero esporre inavvertitamente i risultati agli utenti finali se non sono state implementate correttamente o seguendo le procedure consigliate.

A partire da novembre 2025, questo comportamento è cambiato:

• I filtri di autorizzazione ACL ora si applicano anche quando si usano solo le chiavi API del servizio o l'autenticazione Entra in tutte le versioni che supportano ACL.
• Se il token utente viene omesso, il contenuto protetto da ACL non viene restituito.
• Per visualizzare tutti i documenti per la risoluzione dei problemi, è necessario includere in modo esplicito l'intestazione con privilegi elevati di lettura quando si usa la versione 2026-05-01-preview dell'API REST o versioni successive.

Questo aggiornamento consente di proteggere il contenuto quando le applicazioni non applicano le procedure consigliate per la convalida dei token.

Contenuti correlati

• Esercitazione: Indicizzare i metadati delle autorizzazioni da ADLS Gen2 ed eseguire query con risultati filtrati con autorizzazioni (anteprima)
• Indicizzazione degli elenchi di controllo di accesso ai documenti (ACL) tramite le API REST push (anteprima)
• Usare un indicizzatore ADLS Gen2 per inserire i metadati delle autorizzazioni e filtrare i risultati della ricerca in base ai diritti di accesso utente (anteprima)
• Utilizzare un indicizzatore di blob o una fonte di conoscenza per acquisire i metadati degli ambiti RBAC
• Usare un indicizzatore SharePoint per inserire i metadati delle autorizzazioni e filtrare i risultati della ricerca in base ai diritti di accesso utente (anteprima)