Risolvere i problemi relativi al filtro delle autorizzazioni SharePoint in Azure AI Search (anteprima)

Usare questo articolo se il filtro delle autorizzazioni in fase di query per il contenuto indicizzato SharePoint restituisce risultati mancanti o imprevisti oppure se una query filtrata con autorizzazioni ha esito negativo.

Prerequisiti

• Indice popolato dal SharePoint in Microsoft 365 indicizzatore con inserimento ACL configurato.
• Filtraggio delle autorizzazioni al momento della query configurato come descritto in Applicazione di ACL e RBAC al momento della query.
• Versione 2026-08-01-preview dell'API REST o pacchetto SDK di anteprima equivalente quando si usano SharePoint gruppi di siti.
• Accesso alla definizione dell'indice, allo stato dell'indicizzatore generato o esplicito e alle autorizzazioni di SharePoint per un utente di test.
• Search Index Data Contributor o un'autorizzazione equivalente di lettura avanzata se è necessario confrontare i risultati filtrati e non filtrati.

Seguire l'albero delle decisioni per la risoluzione dei problemi

Completare questi controlli in ordine. Arrestare quando il risultato osservato identifica la configurazione o l'autorizzazione che richiede la correzione.

1. Confermare che il problema si verifichi durante l'esecuzione della query

Questo articolo illustra il filtro delle autorizzazioni dopo che il contenuto di SharePoint e i metadati ACL sono stati indicizzati.

• Se la creazione di un'origine dati o l'esecuzione di un indicizzatore segnala Invalid AAD tenant, seguire la procedura di correzione del tenant Microsoft Entra.
• Se è necessario correggere TenantId, l'autenticazione o la stringa di connessione dell'origine dati, vedere Configurare l'indicizzatore di SharePoint in Microsoft 365.
• Se UserIds, GroupIdso SharePointSiteUrl non sono presenti durante l'indicizzazione, usare la tabella di risoluzione dei problemi di inserimento ACL.

Procedere qui solo quando esistono metadati indicizzati delle autorizzazioni e il sintomo si verifica quando li si interroga.

2. Identificare le tre identità

Registra quale identità ricopre ciascun ruolo. Non sostituire un identificatore per un altro.

3. Controllare la configurazione del filtro delle autorizzazioni

Confronta l'indice, l'indicizzatore e gli oggetti generati con i rispettivi articoli proprietari.

1. Verificare che l'indice sia permissionFilterOption impostato su enabled.
2. Verificare che UserIds e GroupIds abbiano i valori permissionFilter corretti.
3. Per i gruppi di siti di SharePoint, confermare che l'indice contenga sharePointConnectorAppRegistration e un campo SharePointSiteUrl con sharepointSiteUrl: true.
4. Verificare che ogni documento o blocco indicizzato porti i campi di autorizzazione applicabili. Se il set di competenze usa proiezioni di indice, verificare che i campi ACL si trovino in indexProjections.mappings.

Se un valore è assente, tornare a Configurare il servizio di ricerca per l'inserimento ACL e l'imposizione in fase di query.

4. Controllare il token di query in modo sicuro

Non registrare mai, incollare in una richiesta di supporto o condividere un token di accesso completo. Decodifica solo il payload del token localmente e bonifica gli identificatori prima di acquisire l'output diagnostico.

1. Confermare che la richiesta includa x-ms-query-source-authorization con un token delegato attuale per l'utente di test.
2. Decodificare il payload in locale e confermare che oid identifichi l'utente di test previsto. Registrare un valore sanificato, <test-user-object-id>ad esempio .
3. Ripetere l'autenticazione dell'utente e riprovare se il token è mancante o scaduto.

Se il token utente viene omesso, il contenuto protetto dall'autorizzazione non viene restituito. L'intestazione Authorization da sola non sostituisce x-ms-query-source-authorization.

5. Controllare le autorizzazioni Microsoft Entra

1. Verificare che gli elementi indicizzati UserIds o GroupIds contengano l'ID oggetto Microsoft Entra previsto. Usare una query di lettura con autorizzazioni elevate solo per questo confronto diagnostico.
2. Confermare che l'utente di test ha un'assegnazione diretta o appartiene al gruppo Microsoft Entra assegnato tramite appartenenza transitiva a un gruppo Microsoft Entra.
3. Se il gruppo di Microsoft Entra è annidato in un gruppo di SharePoint, modificare l'assegnazione. Questa relazione mista non viene espansa e può causare risultati mancanti. Aggiungere l'utente direttamente al gruppo di SharePoint o concedere l'autorizzazione tramite un'assegnazione di gruppo Microsoft Entra supportata.

Per il limite di supporto esatto, vedere Relazioni di gruppo supportate.

6. Controllare le autorizzazioni del gruppo del sito di SharePoint

Completare questo passaggio quando l'ACL del documento dipende da un gruppo di siti proprietari, membri, visitatori o SharePoint personalizzato.

1. Usare una query con privilegi elevati per confermare che GroupIds contenga l'ID del gruppo con prefisso spg: previsto e che SharePointSiteUrl identifichi il sito di origine.
2. Verificare che l'utente di test sia un membro diretto di tale gruppo di SharePoint.
3. Verificare che l'sharePointConnectorAppRegistrationindice usi gli identificatori e le autorizzazioni richiesti dal supporto dei gruppi di SharePoint.

Se i campi indicizzati sono vuoti o non aggiornati, correggere l'inserimento o sincronizzare le autorizzazioni di SharePoint prima di ripetere la query.

7. Verificare la richiesta di interrogazione

1. Usare la versione 2026-08-01-preview dell'API REST o un pacchetto SDK in anteprima equivalente per i filtri delle autorizzazioni dei gruppi di siti di SharePoint.
2. Verificare che Authorization autentichi un principal che può interrogare l'indice.
3. Verificare che x-ms-query-source-authorization contenga il token dell'utente di test delegato.
4. Riprova la stessa query senza filtri non correlati né modifiche al ranking, così da poter isolare il comportamento delle autorizzazioni.

Usare l'esempio di query generale come riferimento per la forma della richiesta. Non includere token completi nelle richieste o nei log salvati.

8. Confrontare i risultati previsti e effettivi

1. Scegliere un documento a cui l'utente di test può accedere e un documento a cui l'utente non può accedere in SharePoint.
2. Esegui la query filtrata in base alle autorizzazioni utilizzando l’utente di test e registra solo le chiavi dei documenti o altri identificatori non riservati.
3. Eseguire una query di lettura con privilegi elevati e confrontare i valori archiviati UserIds, GroupIds e SharePointSiteUrl con le autorizzazioni di origine.
4. Se la lettura con privilegi elevati restituisce il documento previsto, ma la query dell'utente no, concentrati sul token utente e sulla risoluzione dei gruppi. Se anche la lettura con privilegi elevati non lo rileva, concentrarsi sull'acquisizione, sulle mappature e sulla sincronizzazione delle ACL.

La lettura con privilegi elevati serve per l'analisi. Non usarlo per restituire risultati senza restrizioni agli utenti finali.

9. Acquisire i dettagli di correlazione delle richieste

Se la query ha ancora esito negativo, acquisire la versione dell'API, il timestamp UTC, il corpo della richiesta sanificata, lo stato HTTP, le intestazioni di risposta e qualsiasi richiesta o ID di correlazione restituito dal servizio. Includere il nome dell'indice e se lo stesso documento viene visualizzato in lettura con privilegi elevati.

Rimuovere token di accesso, chiavi API, segreti, nomi utente e URL specifici del tenant prima di condividere la diagnostica con supporto tecnico Microsoft.

Contenuti correlati

• Applicazione dei controlli di ACL e RBAC al tempo di esecuzione delle query
• Usare un indicizzatore SharePoint per inserire i metadati delle autorizzazioni
• Configurare il SharePoint nell'indicizzatore Microsoft 365