SharePoint 인덱서를 사용하여 권한 메타데이터를 수집하고 사용자 액세스 권한(미리 보기)에 따라 검색 결과를 필터링합니다.

SharePoint 권한 메타데이터 수집(미리 보기)은 Azure AI 검색 인덱서를 사용하여 ACL(액세스 제어 목록)과 같은 권한 메타데이터를 Microsoft 365 SharePoint 다른 콘텐츠와 함께 유지합니다. 인덱서는 인덱싱된 각 문서에 대한 권한을 메타데이터로 저장합니다. 쿼리 시 사용자는 액세스 권한이 있는 문서만 받습니다.

필수 구성 요소

• 모든 지역의 청구 가능 계층(기본 이상)에서 Azure AI 검색.

• Microsoft 365의 사이트, 라이브러리, 폴더 및 파일에서 구성된 권한이 있는 SharePoint.

• 이 문서에 설명된 ACL 관련 요구 사항을 적용하여 SharePoint 인덱서 설명서의 모든 구성 단계를 완료합니다.

• 시나리오에 적합한 Microsoft Entra 애플리케이션 권한 및 자격 증명을 구성합니다. ACL별 사용 권한 시나리오를 참조하세요. ACL 수집에는 애플리케이션 권한이 필요합니다. 위임된 권한은 지원되지 않습니다. 애플리케이션 및 위임된 결정에 대해서는 사용 권한 설정 선택을 참조하세요.

• REST API 버전 2026-08-01-preview 또는 동등한 미리 보기 SDK 패키지.

제한

• 증분 ACL 업데이트에는 2026-05-01-preview REST API 이상이 필요합니다. 이전 미리 보기 API 버전에서 시스템은 각 항목의 첫 번째 수집에서만 ACL을 캡처합니다. 나중에 사용 권한을 변경하려면 명시적 다시 인덱싱이 필요합니다. 마이그레이션 단계는 인덱싱된 콘텐츠와 원본 콘텐츠 간에 사용 권한 동기화를 참조하세요.

• 부모 범위의 권한 변경 사항은 이후 인덱서 실행 시 자동으로 반영되지 않습니다. 새로 고침 옵션은 인덱싱된 콘텐츠와 원본 콘텐츠 간에 사용 권한 동기화를 참조하세요.

• Azure 포털은 이 기능을 지원하지 않습니다.

• 이 미리 보기에서는 다음 기능이 지원되지 않습니다.

  • SharePoint 정보 관리 정책 사용자 액세스에 적용할 수 있습니다. 시스템은 쿼리 시 이러한 정책을 평가, 수집 또는 적용하지 않습니다.

  • "모든 사용자" 또는 "조직의 사용자"로 범위가 지정된 공유 가능한 링크입니다. "특정 사용자"로 범위가 지정된 링크만 지원됩니다.

  • SharePoint 그룹(예: 소유자, 구성원 및 방문자 그룹)은 2026-05-01-preview REST API부터 지원됩니다. SharePoint 그룹 지원 구성 참조하세요. 이전 미리 보기 API 버전에서는 Microsoft Entra 그룹으로 확인되는 SharePoint 그룹만 지원됩니다.

• 다음 인덱서 기능은 SharePoint에서 가져온 인덱싱된 문서에서의 사용 권한 상속을 지원하지 않습니다. 기술 세트 또는 인덱서에서 이러한 기능을 사용하는 경우 문서 수준 권한은 인덱싱된 콘텐츠에 포함되지 않습니다.

  • 사용자 지정 Web API 기술

  • 에이전트 검색에서 이미지 서비스(미리 보기)에 필요한 자산 저장소를 포함한 지식 저장소입니다. 따라서 SharePoint ACL을 수집하는 지식 소스에서는 이미지 제공 기능이 지원되지 않습니다.

  • 인덱서 보강 캐시

  • 디버그 세션

SharePoint 권한 모델 지원

이 미리 보기는 문서, 목록 항목 및 최신 ASPX 사이트 페이지에 대한 기본 ACL을 지원합니다.

지원되는 그룹 관계

Microsoft Entra 그룹 전이성은 Microsoft Entra 내에 적용됩니다. SharePoint 그룹의 멤버인 Microsoft Entra 그룹을 확장하지 않습니다.

계층적 사용 권한을 평가하는 방법

SharePoint 사용 권한은 상속이 끊어지지 않는 한 사이트 → 라이브러리 → 폴더 → 파일의 계층 구조를 상속합니다.

수집 중에 인덱서는 각 수준에서 사용자 및 그룹 식별자(ID)를 수집하고 각 파일에 대한 유효 ACL을 계산합니다.

ACL 시나리오별 사용 권한

ACL 수집에 필요한 Microsoft Entra 애플리케이션 권한 및 자격 증명 유형은 인덱싱하는 항목 유형 및 그룹 유형에 따라 달라집니다. 앱 등록에서 모든 사용 권한은 API 권한> 아래에 추가되고 페더레이션 자격 증명은 인증서 및 비밀>페더레이션 자격 증명 아래에 추가됩니다. 단계별 지침 및 스크린샷은 9월 3일: Microsoft Entra 애플리케이션 등록 만들기 및 관리 ID를 사용하여 등록된 애플리케이션 구성을 참조하세요.

페더레이션 자격 증명은 클라이언트 암호 대신 신뢰할 수 있는 관리 ID를 사용하여 앱을 인증합니다. 동일한 페더레이션 자격 증명은 SharePoint 사이트 그룹의 수집(인덱서) 및 쿼리 시간 평가를 모두 포함합니다. 설정 단계는 관리 ID를 사용하여 등록된 애플리케이션 구성을 참조하세요.

ACL 수집을 사용하도록 설정하기 전에

등록된 Microsoft Entra 애플리케이션에서 다음 단계를 완료합니다.

1. 인덱싱하려는 항목(문서 라이브러리 파일, 목록 항목, ASPX 사이트 페이지) 및 SharePoint 사이트 그룹을 적용해야 하는지 여부에 따라 이전 표의 시나리오를 식별합니다.
2. Microsoft Entra 관리 센터 앱 등록을 열고 API 권한> 권한 추가로 이동합니다.
3. 시나리오에 대해 나열된 Microsoft Graph 권한을 추가합니다. 관리자 동의를 부여합니다.
4. 시나리오에 SharePoint 권한도 필요한 경우 권한 추가를 다시 선택하고 SharePoint API를 선택하고 Sites.FullControl.All(또는 Sites.Selected)를 추가합니다. 관리자 동의를 부여합니다.
5. 자격 증명을 구성합니다.
   • Microsoft Graph 전용 시나리오에서는 클라이언트 암호(인증서 및 비밀>클라이언트 비밀) 또는 연합 자격 증명을 사용할 수 있습니다.
   • SharePoint 권한이 포함된 시나리오에서는 Certificates & secrets>Federated credentials 아래에 페더레이션 자격 증명을 추가합니다. 관리 ID를 사용하여 등록된 애플리케이션 구성을 참조하세요.
6. 인덱싱하려는 콘텐츠와 권한을 읽을 수 있도록 대상 SharePoint 사이트에 대한 애플리케이션 액세스 권한을 부여합니다(특히 범위가 지정된 액세스에 Sites.Selected 사용하는 경우 중요).

올바른 Microsoft Entra 식별자 찾기

각 식별자는 Azure 포털의 다른 위치에 표시되고 특정 구성 필드에 매핑됩니다. 페더레이션 자격 증명으로 SharePoint ACL 수집을 구성할 때 이 섹션을 참조로 사용합니다. 이러한 식별자는 SharePoint 그룹 지원 구성 및 데이터 원본 연결 문자열에서 참조됩니다.

페더레이션 자격 증명 애플리케이션 ID

데이터 원본 연결 문자열의 FederatedCredentialApplicationId 및 인덱스 정의의 federatedCredentialId에는 수집 앱의 ID가 아니라 관리형 ID 자체의 애플리케이션(클라이언트) ID를 사용하세요.

시스템 할당 관리 ID:

1. Azure AI 검색 서비스로 이동합니다.
2. 보안 + 네트워킹>ID를 선택합니다.
3. 시스템 할당 탭에서 개체(보안 주체) ID를 확인합니다.
4. Microsoft Entra ID>관리>엔터프라이즈 애플리케이션로 이동합니다.
5. 검색 서비스 이름을 입력해 검색하거나 개체(보안 주체) ID를 검색 상자에 붙여 넣습니다.
6. 결과를 선택하고 속성을 엽니다. 여기에 표시된 federatedCredentialId를 복사합니다. 이 값은 데이터 원본의 FederatedCredentialApplicationId 및 인덱스의 에 해당합니다.

사용자 할당 관리 ID:

1. 사용자 할당 관리 ID 리소스로 이동합니다.
2. 설정>속성을 선택합니다.
3. 데이터 원본의 FederatedCredentialApplicationId 값이자 인덱스의 값인 federatedCredentialId를 복사하세요.

ACL 수집 및 쿼리 시간 적용에 대한 검색 서비스 구성

이러한 단계는 ACL 수집에 대한 검색 서비스를 구성하고 쿼리 시 ACL을 적용하도록 설정합니다.

ACL 필드를 채울 위치 선택

ACL 메타데이터 필드를 매핑하는 위치는 인덱서가 원본 항목당 하나의 문서를 쓰는지 또는 원본 항목당 여러 청크를 쓰는지에 따라 달라집니다.

청크로 분할되는 모든 경우에 각 청크에는 ACL 필드가 포함되어야 합니다. 사용 권한 필터는 문서별로 적용되므로 누락된 ACL 필드 청크를 올바른 호출자에게 반환할 수 없습니다.

1. 데이터 원본 구성

이 섹션은 기본 4단계: 데이터 원본 만들기 안내에 추가되는 내용입니다. SharePoint 문서에서 indexerPermissionOptions의 및 userIds 인덱싱을 가능하게 하려면 groupIds을(를) 설정합니다.

{
  "name": "my-sharepoint-acl-datasource",
  "type": "sharepoint",
  "indexerPermissionOptions": ["userIds", "groupIds"],
  "credentials": {
    "connectionString": "<connection-string>;"
  },
  "container": {
    "name": "<library-name>",
    "query": "<optional-folder-path>"
  }
}

2. 인덱스 정의에 사용 권한 필드 추가

인덱스 스키마 정의에 필드를 추가하여 ACL을 저장하고 쿼리 시간 필터링을 지원합니다.

{
  "fields": [
    { "name": "UserIds",  "type": "Collection(Edm.String)", "permissionFilter": "userIds",  "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

개발 중에만 값을 확인하기 위해 retrievable 특성을 true로 설정합니다. 인덱스 다시 작성 요구 사항 없이 검색 가능한 항목을 true에서 false로 변경할 수 있습니다.

3. 기술 집합에서 인덱스 프로젝션 구성(해당하는 경우)

청킹이 활성화되면 projectionMode이(가) skipIndexingParentDocuments일 때 부모 문서는 인덱스에 기록되지 않습니다. 를 통해 indexProjections.selectors[].mappings각 청크에 ACL 메타데이터를 전달합니다.

인덱서가 통합 벡터화를 사용하도록 설정할 때 텍스트 분할 기술과 같은 데이터 청크가 있는 기술 집합을 사용하는 경우 인덱스 프로젝션을 사용하여 각 청크에 ACL 속성을 매핑해야 합니다. 다음 예제의 줄은 // 설명 주석이며 유효한 JSON이 아닙니다. 요청을 제출하기 전에 제거합니다.

PUT https://{service}.search.windows.net/skillsets/{skillset}?api-version=2026-08-01-preview
{
  "name": "my-skillset",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
      "name": "#split",
      "context": "/document",
      "inputs": [{ "name": "text", "source": "/document/content" }],
      "outputs": [{ "name": "textItems", "targetName": "chunks" }]
    }
    // ... (other skills such as embeddings, entity recognition, etc.)
  ],
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "chunks-index",
        "parentKeyFieldName": "parentId",          // must exist in target index
        "sourceContext": "/document/chunks/*",     // match your split output path
        "mappings": [
          { "name": "chunkId",           "source": "/document/chunks/*/id" },     // if you create an id per chunk
          { "name": "content",           "source": "/document/chunks/*/text" },   // chunk text
          { "name": "parentId",          "source": "/document/id" },              // parent doc id
          { "name": "UserIds",  "source": "/document/metadata_user_ids" },
          { "name": "GroupIds",  "source": "/document/metadata_group_ids" },
          { "name": "SharePointSiteUrl", "source": "/document/metadata_spo_site_url" } // include when the index has sharePointConnectorAppRegistration (SharePoint groups support)
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

UserIds, GroupIds 및 SharePointSiteUrl 매핑은 SharePoint 인덱서(/document/metadata_*)에서 내보낸 원본 수준 메타데이터를 읽고 각 청크에 값을 씁니다.

4. ACL에 대한 인덱서 필드 매핑 구성

인덱서가 원본 항목당 하나의 문서를 쓰거나(청크 분할 없음) 청크 인덱스와 함께 별도의 부모 인덱스를 유지 관리하는 경우 인덱서 필드 매핑을 사용합니다. 기술 세트에서 문서를 projectionMode: skipIndexingParentDocuments 단일 대상 인덱스로 청크 분할하는 경우, 여기에 표시된 필드 매핑 대신 청크 인덱스에는 이전 단계의 indexProjections.mappings가 적용됩니다.

필요한 indexer 구성 외에도 SharePoint에서 원시 메타데이터 ACL 필드를 가져와 인덱스 필드에 매핑합니다.

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",  "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" }
  ]
}

5. 인덱서 실행

ACL 메타데이터는 인덱서가 실행될 때 수집됩니다. 인덱서( 6단계: 인덱서 만들기 참조)를 만들거나 업데이트한 후 인덱서가 콘텐츠와 함께 ACL을 수집하도록 실행을 트리거합니다.

POST https://[service name].search.windows.net/indexers/[indexer-name]/run?api-version=2026-08-01-preview
api-key: [admin key]

이미 항목을 인덱싱한 기존 인덱서에 ACL 수집을 사용하도록 설정한 경우, 해당 항목의 ACL을 백필하려면 /resync와 함께 options: ["permissions"]를 호출하거나, 특정 항목을 다시 추출하려면 /resetdocs를 호출합니다.

6. ACL 수집 확인

ACL 값이 올바르게 채워져 있는지 확인하려면 다음을 수행합니다.

1. 인덱스 정의에서 retrievable 및 true의 UserIds를 GroupIds로 일시적으로 설정하세요. 변경 retrievable 시 인덱스 다시 작성이 필요하지 않습니다.
2. 권한 상승 읽기 쿼리를 실행하여 UserIds와 GroupIds를 선택하고, 컬렉션이 비어 있지 않은지 확인합니다. 청크 분할 시나리오의 경우 모든 청크가 두 필드를 모두 전달하는지 확인합니다.
3. 확인 후 retrievablefalse로 돌아갑니다.

SharePoint 그룹 지원 구성

2026-05-01-preview REST API부터 SharePoint 인덱서는 SharePoint 사이트 그룹 멤버 자격(소유자, 구성원, 방문자 및 사용자 지정 사이트 그룹)을 수집할 수 있습니다. 쿼리 시 이러한 그룹을 반영합니다. SharePoint 그룹 ID는 Microsoft Entra 그룹 개체 ID와 구분하기 위해 metadata_group_ids 접두사를 사용하여 spg: 필드에 내보내집니다.

이 연습은 독립적으로 진행할 수 있습니다. 인덱스와 인덱서 필드 매핑을 구성하고 SharePoint 사이트 그룹 적용을 사용하여 인덱스를 쿼리하려면 다음 단계를 순서대로 완료하세요.

다음 구성 요소는 함께 작동하여 SharePoint 사이트 그룹 확인 기능을 가능하게 합니다.

1. 사전 요구 사항

• SharePoint 인덱서가 ACL 수집에 대해 이미 구성되어 있습니다. ACL에 대한 인덱서 필드 매핑 구성을 참조하세요.
• 페더레이션된 ID 자격 증명을 사용한 Microsoft Entra 앱 등록 관리 ID를 사용하여 등록된 애플리케이션 구성을 참조하세요.
• REST API 2026-05-01-preview 이상.

2. 인덱스 구성

전체 인덱스 구조가 한곳에 있도록 sharePointConnectorAppRegistration 및 SharePointSiteUrl 권한 필터 필드와 함께 UserIds 구성과 GroupIds 필드를 추가합니다. permissionFilterOption: "enabled"를 유지합니다.

PUT https://{service}.search.windows.net/indexes/{index}?api-version=2026-08-01-preview
{
  "name": "my-sharepoint-acl-index",
  "sharePointConnectorAppRegistration": {
      "applicationId": "<ingestion-app-client-id>",
      "federatedCredentialId": "<managed-identity-application-id>",
     "tenantId": "<sharepoint-tenant-id>"
  },
  "fields": [
    { "name": "UserIds",           "type": "Collection(Edm.String)", "permissionFilter": "userIds",  "filterable": true, "retrievable": false },
    { "name": "GroupIds",          "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "SharePointSiteUrl", "type": "Edm.String", "sharepointSiteUrl": true, "filterable": false, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

3. 인덱서 필드 매핑 구성

SharePoint 메타데이터 필드를 결합된 단일 매핑 블록의 인덱스 필드에 매핑합니다. 처음 두 매핑은 표준 ACL 수집에 사용되는 것과 동일합니다. 세 번째 매핑은 SharePoint 그룹 확인을 활성화합니다.

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",             "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids",            "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_spo_site_url",  "targetFieldName": "SharePointSiteUrl" }
  ]
}

기술 세트가 문서를 청크로 분할하는 경우(예: 통합 벡터화를 위한 Text Split 기술을 사용하는 경우) 대신 SharePointSiteUrl을 통해 indexProjections.mappings를 각 청크에 프로젝션하세요. ACL 필드를 채울 위치 선택을 참조하세요.

4. 인덱스 쿼리

클라이언트 쪽 변경이 필요하지 않습니다. 동일한 x-ms-query-source-authorization 토큰은 Microsoft Entra 및 SharePoint 사이트 그룹 적용을 활성화합니다. 검색 서비스는 인덱스에서 sharePointConnectorAppRegistration를 사용하여 서버 측에서 SharePoint 그룹 멤버 자격을 확인합니다.

요청 형식은 일반 쿼리 예제 및 SharePoint 관련 SharePoint 사이트 그룹 적용 예제를 참조하세요.

5. 확인

SharePoint 그룹 ID가 인덱스에 반영되었는지 확인하려면 을(를) 선택하는 GroupIds를 실행하고, 응답에서 spg:로 시작하는 값을 찾습니다.

인덱싱된 콘텐츠와 원본 콘텐츠 간에 사용 권한 동기화

2026-05-01-preview REST API부터는 고유한 권한이 있는 항목의 ACL 변경 내용이 인덱서가 성공적으로 실행될 때마다 감지되고 새로 고쳐집니다. 인덱서는 SharePoint 변경 토큰을 사용하여 콘텐츠 변경 내용을 선택하는 것과 같은 방식으로 역할 할당 추가 및 제거를 증분 방식으로 선택합니다.

일부 시나리오에서는 여전히 명시적 새로 고침이 필요합니다.

특정 문서 다시 설정

특정 문서를 다시 설정하여 콘텐츠 및 ACL을 완전히 다시 수집할 수 있습니다.

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{
  "documentKeys": ["doc123", "doc456"]
}

전체 데이터 원본에서 ACL 다시 동기화

초기 수집 후에 전체 데이터 집합 ACL 콘텐츠를 다시 동기화 할 수 있습니다. 완전히 성공하려면 완료 후 인덱서 실행이 필요합니다.

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{
  "options": ["permissions"]
}

데이터 및 ACL을 인덱싱한 후 인덱스를 쿼리할 수 있습니다.

Troubleshooting

ACL 메타데이터가 인덱싱된 후 누락되거나 예기치 않거나 실패한 쿼리 시간 결과는 SharePoint 권한 필터링 문제 해결을 참조하세요.

관련 콘텐츠

• Azure AI 검색(미리 보기)에서 SharePoint 콘텐츠를 인덱싱하기
• 쿼리 시간 ACL 적용