Foundry IQ (Azure AI 검색)에서 SharePoint 권한 필터링 문제 해결

Note

Foundry IQ (Azure AI 검색)는 관리 검색을 위해 고급 수준의 지식 원본 및 지식 베이스 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.

인덱싱된 SharePoint 콘텐츠에 대한 쿼리 시간 권한 필터링이 누락되거나 예기치 않은 결과를 반환하거나 권한 필터링된 쿼리가 실패하는 경우 이 문서를 사용합니다.

사전 요구 사항

  • Microsoft 365의 SharePoint 인덱서가 ACL 수집이 구성된 상태로 채워 넣은 인덱스.
  • 쿼리 시간 ACL 및 RBAC 적용에 설명된 대로 구성된 쿼리 시간 권한 필터링입니다.
  • SharePoint 권한 필터링을 위한 REST API 버전 2026-10-01
  • 인덱스 정의, 생성 또는 명시적 인덱서 상태 및 테스트 사용자에 대한 SharePoint 권한에 액세스합니다.
  • 필터링된 결과와 필터링되지 않은 결과를 비교해야 하는 경우 Search Index Data Contributor 또는 이에 상응하는 상위 읽기 권한이 필요합니다.

문제 해결 의사 결정 트리를 따릅니다.

이러한 검사를 순서대로 완료합니다. 관찰된 결과가 수정이 필요한 구성 또는 사용 권한을 식별하는 경우 중지합니다.

1. 쿼리 시 오류가 발생하는지 확인

이 문서에서는 SharePoint 콘텐츠 및 ACL 메타데이터가 인덱싱된 후의 권한 필터링에 대해 설명합니다.

인덱싱된 권한 메타데이터가 존재하고 쿼리할 때 증상이 발생하는 경우에만 여기에서 계속합니다.

2. 세 가지 ID 식별

각 역할을 맡는 신원을 기록합니다. 한 식별자를 다른 식별자로 대체하지 마세요.

Identity Purpose 확인할 위치
사용자 조회 중 위임된 사용자 토큰은 x-ms-query-source-authorization 사용자가 검색할 수 있는 보호된 문서를 결정합니다. 애플리케이션 인증 흐름 및 쿼리 요청.
SharePoint 커넥터 앱 등록 인덱스의 sharePointConnectorAppRegistration를 통해 Foundry IQ(Azure AI 검색)는 쿼리하는 사용자의 SharePoint 사이트 그룹 멤버 자격을 확인할 수 있습니다. SharePoint 그룹 구성 지원에 설명된 인덱스 정의 및 앱 등록입니다.
Foundry IQ 요청 신원 헤더의 Microsoft Entra 전달자 토큰 Authorization 또는 헤더의 api-key API 키는 Foundry IQ 서비스에 대한 요청을 인증합니다. ID에는 인덱스 쿼리 권한이 있어야 합니다. 쿼리 클라이언트 및 Foundry IQ 데이터 평면 역할 할당을 확인합니다.

3. 권한 필터 구성 확인

인덱스, 인덱서 및 생성된 개체를 소유자 아티클과 비교합니다.

  1. 인덱스가 permissionFilterOption로 설정되어 있는지 확인합니다 enabled.
  2. UserIds 및 GroupIds에 올바른 permissionFilter 값이 있는지 확인하세요.
  3. SharePoint 사이트 그룹의 경우 인덱스에 sharePointConnectorAppRegistration 및 sharepointSiteUrl: true가 있는 SharePointSiteUrl 필드가 있는지 확인합니다.
  4. 인덱싱된 모든 문서 또는 청크가 해당 사용 권한 필드를 전달하는지 확인합니다. 스킬셋이 인덱스 프로젝션을 사용하는 경우 ACL 필드가 indexProjections.selectors[].mappings에 있는지 확인합니다.
  5. 인덱스에 필수 metadata_spo_item_path 필드가 있고 프로젝션된 청크가 원본 경로를 유지하는지 확인합니다. 자산/항목 ID 또는 사이트 URL은 이를 대체하지 않습니다.

값이 하나라도 없으면 ACL 수집 및 쿼리 시 적용을 위한 Foundry IQ 서비스 구성으로 돌아가세요.

메타데이터 및 수명 주기 증상의 경우 영향을 받는 원본 항목 및 인덱싱된 문서 또는 청크로 검사를 좁힐 수 있습니다.

증상 중점 확인 및 다음 작업
원본 경로가 없거나 항목과 일치하지 않습니다. metadata_spo_item_path를 원본 메타데이터와 비교합니다. 필요한 명명된 필드와 각 청크의 /document/metadata_spo_item_path 프로젝션을 확인합니다. 항목 키, 웹 URL 또는 사이트 URL은 대체 항목이 아닙니다. 매핑을 수정하고 영향을 받는 항목을 다시 처리합니다.
네이티브 사이트 그룹 액세스는 사이트마다 다릅니다. 각 항목의 metadata_spo_site_url을(를) sharepointSiteUrl: true로 표시된 필드와 비교합니다. 프로젝션이 일정한 사이트 URL이 아닌 원본 사이트를 유지하는지 확인합니다. 각 사이트에 대한 커넥터 동의 및 선택된 사이트 권한을 검토합니다.
목록, 페이지 또는 혼합 항목이 없거나 예기치 않은 키가 있음 allSiteLists, allSitePages 또는 allSiteContent를 사용하는 직접 구성된 인덱서의 경우 metadata_spo_site_asset_item_id 키 매핑과 인코딩을 확인합니다. 경로 또는 사이트 URL을 대신 사용하지 말고 커넥터의 키 지침을 사용합니다.
부모는 올바르지만 청크는 다릅니다. 생성된 또는 명시적 기술 세트의 프로젝션 및 실제 자식 레코드를 검사합니다. 각 청크에서 콘텐츠, 원본 경로, ACL 및 해당 사이트 컨텍스트를 확인합니다. 프로젝션 생성 키 또는 부모 ID에 대한 수동 매핑을 추가하지 마세요.
이전 레코드는 새로 고침, 이동, 이름 바꾸기 또는 삭제 후에도 남아 있습니다. 원본 선택 경로, 인덱서 경고 및 실패, 현재와 이전 문서 및 청크 키를 확인합니다. 콘텐츠 및 수명 주기 처리와 권한 새로 고침을 구분합니다. 사용되지 않는 레코드를 별도로 확인합니다.

누락, null, 형식이 잘못되었거나 수정할 수 없는 경로에 대해 인덱서 진단을 사용합니다. 필드 값만으로 특정 오류 또는 권한 부여 결과를 유추하지 마세요. 인덱싱된 지식 원본의 경우 generated-resource 검사도 완료합니다.

4. 쿼리 토큰을 안전하게 확인

로그하거나, 지원 요청에 붙여넣거나, 전체 액세스 토큰을 공유하지 마세요. 토큰 페이로드만 로컬로 디코딩하고 진단 출력을 캡처하기 전에 식별자를 삭제합니다.

  1. 테스트 사용자에 대해 현재 위임된 토큰이 요청에 포함되어 x-ms-query-source-authorization 있는지 확인합니다.
  2. 페이로드를 로컬로 디코딩하고 의도한 oid 테스트 사용자를 식별했는지 확인합니다. <test-user-object-id>와 같은 정제된 값을 기록합니다.
  3. 사용자를 다시 인증하고 토큰이 누락되었거나 만료된 경우 다시 시도합니다.

사용자 토큰을 생략하면 권한으로 보호되는 콘텐츠가 반환되지 않습니다. 헤더만으로는 Authorization 대체 x-ms-query-source-authorization되지 않습니다.

5. Microsoft Entra 권한 확인

  1. 인덱싱된 UserIds 또는 GroupIds에 예상되는 Microsoft Entra 개체 ID가 포함되어 있는지 확인합니다. 이 진단 비교에만 권한 상승 읽기 쿼리를 사용하세요.
  2. 테스트 사용자에게 직접 할당이 있거나 지원되는 5개의 중첩된 수준 내에서 할당된 그룹에 도달하는지 확인합니다.
  3. Microsoft Entra 그룹이 SharePoint 그룹 내에 중첩되어 있는 경우 중첩 깊이 및 SharePoint 그룹 구성을 확인하세요. 5개 수준보다 깊은 경로는 해당 경로를 통해 액세스 권한을 부여하지 않습니다. 지원되는 별도의 권한 부여는 계속 적용할 수 있습니다.

정확한 지원 경계는 지원되는 그룹 관계를 참조하세요.

6. SharePoint 사이트 그룹 사용 권한 확인

문서 ACL이 소유자, 구성원, 방문자 또는 사용자 지정 SharePoint 사이트 그룹에 의존하는 경우 이 단계를 완료합니다.

  1. 상승된 읽기 권한 쿼리를 사용하여 GroupIds에 예상된 spg:-접두사 그룹 ID가 포함되어 있고 SharePointSiteUrl가 소스 사이트를 식별하는지 확인합니다.
  2. 테스트 사용자가 해당 SharePoint 그룹의 직접 멤버인지 확인하거나 지원되는 Microsoft Entra 그룹 중첩 경로를 통해 해당 그룹의 멤버가 되는지 확인합니다.
  3. 인덱스가 sharePointConnectorAppRegistrationSharePoint 그룹 지원에 필요한 식별자 및 사용 권한을 사용하는지 확인합니다.

인덱싱된 필드가 비어 있거나 부실한 경우 쿼리를 다시 테스트하기 전에 수집을 수정하거나 SharePoint 권한을 동기화합니다.

중첩 그룹 결과가 누락된 경우 사이트 수준 10,000 보안 주체 제한도 검토합니다. 중첩 깊이 및 테스트 사용자의 그룹 수와는 별개입니다. 다시 인덱싱만으로는 이 쿼리 시간 임계값이 해결되지 않습니다.

멤버 자격 결과가 캐시되므로 사이트 그룹 구성에 대한 변경 내용이 다음 쿼리에 표시되지 않을 수 있습니다. 지원되는 직접 할당을 중첩된 그룹 경로와 비교하여 문제를 격리합니다. 지속되면 반복적으로 다시 인덱싱하는 대신 지원팀에 전달할 요청 상관관계 세부 정보를 수집합니다. 조사하는 동안 사용 권한 필터링을 사용하도록 설정합니다.

7. 쿼리 요청 확인

  1. SharePoint 권한 필터에는 REST API 버전 2026-10-01를 사용합니다.
  2. Authorization가 인덱스를 쿼리할 수 있는 보안 주체를 인증하는지 확인합니다.
  3. x-ms-query-source-authorization에 위임된 테스트 사용자 토큰이 포함되어 있는지 확인합니다.
  4. 권한 동작을 격리할 수 있도록 관련 없는 필터 또는 순위 변경 없이 동일한 쿼리를 다시 시도합니다.

일반 쿼리 예제를 요청 셰이프 소유자로 사용합니다. 저장된 요청 또는 로그에 전체 토큰을 포함하지 마세요.

권한 부여를 평가할 수 없는 경우 보호된 콘텐츠를 반환하거나 상향된 권한 또는 필터링되지 않은 액세스 권한으로 다시 시도하지 않고 오류를 처리합니다. 애플리케이션 및 푸시 파이프라인 책임에 대한 권한 부여 및 업데이트 오류 처리를 참조하세요.

8. 예상 결과와 실제 결과 비교

  1. 테스트 사용자가 액세스할 수 있는 문서 하나와 사용자가 SharePoint 액세스할 수 없는 문서 하나를 선택합니다.
  2. 권한 필터링된 쿼리를 테스트 사용자로 실행하고 문서 키 또는 기타 비보안 식별자만 기록합니다.
  3. 권한 상승 읽기 쿼리를 실행하고 저장된 UserIds, GroupIds, SharePointSiteUrl 값을 원본 권한과 비교합니다.
  4. 관리자 권한 읽기가 예상 문서를 반환하지만 사용자 쿼리가 반환하지 않는 경우 사용자 토큰, 저장된 ACL 값, 최신 상태 및 그룹 확인/해결 과정을 확인합니다. 관리자 권한 읽기도 이를 찾지 못하는 경우 콘텐츠 수집, 원본 선택 및 인덱싱된 키를 확인합니다.

조직 전체 공유 링크가 아닌 상속된 할당을 포함하여 지원되는 명시적 사용자 및 그룹 할당을 비교합니다. 조직 전체 링크 및 공유 링크 만료 강제 적용은 지원되지 않습니다. 링크를 만료해도 독립적인 명시적 권한 부여는 취소되지 않습니다. SharePoint 파일을 여는 것은 인덱싱된 콘텐츠를 검색하는 별도의 액세스 검사입니다.

원본 사용 권한이 변경된 후 동기화 시나리오 테이블 및 인덱서 실행 상태를 확인합니다. 쿼리로 인덱서가 시작되지 않으며 요청된 실행은 완료된 ACL 처리를 나타내지 않습니다.

  1. SharePoint에서 영향을 받는 항목이 사용 권한을 상속하는지 또는 고유한 권한이 있는지 확인합니다. 예를 들어 폴더의 사용 권한을 상속하는 파일은 해당 폴더의 할당을 따릅니다. 고유한 권한이 있는 파일은 자체 할당을 유지합니다.
  2. 관련 인덱서 실행이 완료되었는지 확인한 다음 인덱싱된 ACL을 항목의 원본 할당과 비교합니다. 청크 분할된 콘텐츠의 경우 영향을 받는 청크도 확인합니다.
  3. 시나리오 테이블에 따라 일반적인 증분 처리, 사용 권한 다시 동기화 또는 원본 항목 재처리를 선택합니다. 결과가 여전히 다른 경우 요청 상관 관계 세부 정보를 캡처하세요.

상승된 읽기는 조사를 위한 것입니다. 최종 사용자에게 무제한 결과를 반환하는 데 사용하지 마세요.

9. 요청 상관 관계 세부 정보 캡처

쿼리가 여전히 실패하는 경우 API 버전, UTC 타임스탬프, 삭제된 요청 본문, HTTP 상태, 응답 헤더 및 서비스에서 반환된 모든 요청 또는 상관 관계 ID를 캡처합니다. 인덱스 이름과 동일한 문서가 상위 권한으로 읽을 때도 나타나는지 여부를 포함합니다.

Microsoft 지원 진단을 공유하기 전에 액세스 토큰, API 키, 비밀, 사용자 이름 및 테넌트별 URL을 제거합니다.