Azure AI 검색의 쿼리 시 ACL 및 RBAC 강제 적용(미리 보기)

쿼리 시간 액세스 제어(미리 보기)는 사용자가 ID, 그룹 멤버 자격, 역할 또는 특성에 따라 액세스 권한이 부여된 검색 결과만 검색하도록 합니다. 이 기능은 보안 엔터프라이즈 검색 및 규정 준수 기반 워크플로에 필수적입니다.

권한 있는 액세스는 인덱싱 중에 수집되는 권한 메타데이터에 따라 달라집니다. ADLS(Azure Data Lake Storage) Gen2 및 Microsoft 365 SharePoint 같은 기본 제공 액세스 모델이 있는 인덱서 데이터 원본의 경우 인덱서는 각 문서에 대한 권한 메타데이터를 자동으로 끌어올 수 있습니다. 다른 데이터 원본의 경우 문서 페이로드를 직접 어셈블해야 하며 페이로드에는 콘텐츠와 연결된 권한 메타데이터가 모두 포함되어야 합니다. 그런 다음 푸시 API 를 사용하여 인덱스를 로드합니다.

이 문서에서는 권한 메타데이터를 사용하여 결과를 필터링하는 쿼리를 설정하는 방법을 설명합니다.

필수 구성 요소

• 사용 권한 메타데이터는 filterable 문자열 필드에 있어야 합니다. 쿼리에서는 필터를 사용하지 않지만 검색 엔진은 내부적으로 필터를 빌드하여 권한이 없는 콘텐츠를 제외합니다.

• 권한 메타데이터는 액세스 수준과 그룹 또는 사용자 ID를 식별하는 POSIX 스타일 권한 또는 RBAC 범위를 사용하는 경우 ADLS Gen2에 있는 컨테이너의 리소스 ID로 구성되어야 합니다.

• 사용자 지정 수집에서 ACL 기반 적용을 위해, userIds 및 groupIds를 필터링 가능한 필드에 Microsoft Entra 개체 ID(GUID)로 저장합니다. 쿼리 시 서비스는 x-ms-query-source-authorization의 ID를 저장된 ID와 대조합니다. 스키마 세부 정보는 푸시 REST API(미리 보기)를 사용하여 ACL(문서 액세스 제어 목록) 인덱싱을 참조하세요.

• 데이터 원본에 따라:

  • ADLS Gen2 데이터 원본의 경우, 컨테이너 수준에서 ACL(액세스 제어 목록) 및/또는 Azure RBAC(역할 기반 액세스 제어) 역할을 구성해야 합니다.
  • Azure Blob 데이터 원본의 경우 컨테이너에 역할 할당이 있어야 합니다. 기본 제공 인덱서, 기술 자료 또는 푸시 API를 사용하여 인덱스의 권한 메타데이터를 인덱싱할 수 있습니다.
  • SharePoint 데이터 원본의 경우 ACL(액세스 제어 목록)을 구성해야 합니다. built-in SharePoint 인덱서를 사용하고 ACL 수집 기능 사용하여 구성할 수 있습니다. 인덱싱된 SharePoint 기술 원본을 사용하여 문서 수준 권한을 적용하도록 구성할 수도 있습니다. Microsoft 365 그룹를 포함한 그룹 기반 권한은 Entra 개체 ID로 수집되는 경우 지원됩니다. 그룹 확장은 Microsoft Graph 통해 쿼리 시간에 발생합니다.

• latest preview REST API 또는 Azure SDK 미리 보기 패키지를 사용하여 인덱스 또는 기술 자료를 쿼리합니다. 이 API 버전은 권한이 없는 결과를 필터링하는 내부 쿼리를 지원합니다.

제한

• ACL 평가가 실패하면(예: Graph API 사용할 수 없음) 서비스는 5xx 반환하고 부분적으로 필터링된 결과 집합을 반환하지 않습니다.

• ACL의 최신성은 수집 방법에 따라 달라집니다. 부실 권한 부여 결정을 방지하려면 각 원본이 권한 변경 내용을 인덱스에 전파하는 방법을 계획합니다.

  • 예약된 SharePoint 인덱서는 각 실행에서 항목 수준 권한 변경 내용을 새로 고칩니다. 자식 항목에서 상속된 부모 범위(사이트, 라이브러리, 목록 또는 폴더)를 변경하려면 다시 동기화가 필요합니다.
  • ADLS Gen2 인덱서는 ACL을 새로 고치려면 다시 동기화해야 합니다.
  • 사용자 지정 또는 푸시 수집을 사용하려면 영향을 받는 문서를 다시 수집해야 합니다.

• 문서 표시 유형에는 다음이 모두 필요합니다.

  • 호출 애플리케이션의 RBAC 역할(권한 부여 헤더)입니다.
  • x-ms-query-source-authorization에 포함된 사용자 ID 정보입니다.

• 초기 ACL 기반 쿼리는 캐싱 및 권한 확인 오버헤드로 인해 후속 요청에 비해 대기 시간이 더 높을 수 있습니다.

• 인덱싱된 SharePoint 콘텐츠의 경우 SharePoint 그룹 내에 중첩된 Microsoft Entra 그룹은 확장되지 않습니다. Microsoft Entra의 전이적 그룹 확인은 이러한 혼합 관계를 지원하지 않습니다. 지원되는 그룹 관계를 참조하세요.

데이터 원본당 ACL 항목 제한

ACL(액세스 제어 목록) 항목 제한은 연결된 데이터 원본 내의 파일, 폴더 또는 항목과 연결할 수 있는 고유 권한 레코드 수를 정의합니다. 각 항목은 단일 사용자 또는 그룹 ID와 해당 ID에 부여된 액세스 권한(예: 읽기, 쓰기 또는 실행)을 나타냅니다.

Azure AI 검색 기능에서 지원하는 최대 ACL 항목 수는 데이터 원본 형식에 따라 달라집니다.

Azure Data Lake Storage Gen2(ADLS Gen2): 각 파일 또는 디렉터리에는 최대 32개의 ACL 항목 사용 권한 포함할 수 있습니다. 이 컨텍스트에서 항목은 특정 권한 집합을 가진 단일 주체(사용자 또는 그룹)를 의미합니다. 예: "모든 사용자" 읽기 액세스 및 "Azure 사용자" 실행 액세스를 할당하면 두 개의 ACL 항목으로 계산됩니다.

Microsoft 365 SharePoint: 검색의 SharePoint 데이터 원본은 파일당 최대 1,000개의 권한 항목을 지원합니다. 각 항목은 항목의 사용 권한 목록에 있는 고유한 사용자 또는 그룹 할당을 나타냅니다. 이는 고유한 사용 권한을 가질 수 있는 항목 수를 제어하는 목록 또는 라이브러리당 전체 고유 권한 범위 제한 과 다릅니다.

이러한 제한은 검색 결과를 인덱싱하거나 필터링할 때 Azure AI 검색 항목 수준 권한을 어떻게 세분화하여 적용할 수 있는지를 결정합니다. 항목이 이러한 ACL 항목 제한을 초과하는 경우 쿼리 시 제한을 초과하는 권한이 적용되지 않을 수 있습니다.

쿼리 시간 적용의 작동 방식

이 섹션에서는 쿼리 시 ACL 적용에 대한 작업 순서를 나열합니다. 작업은 Azure RBAC 범위 또는 Microsoft Entra ID 그룹 또는 사용자 ID를 사용하는지에 따라 달라집니다.

1. 사용자 권한 입력

최종 사용자 애플리케이션은 검색 쿼리 요청의 일부로 쿼리 액세스 토큰을 포함하며, 액세스 토큰은 일반적으로 사용자의 ID입니다. 다음 표에서는 ACL 적용을 위해 Azure AI 검색 지원하는 사용자 권한의 원본을 나열합니다.

2. 보안 필터 생성

내부적으로 Azure AI 검색 제공된 사용자 권한에 따라 보안 필터를 동적으로 생성합니다. 이러한 보안 필터는 인덱스에 사용 권한 필터 옵션이 설정된 경우 쿼리와 함께 들어올 수 있는 모든 필터에 자동으로 추가됩니다.

Azure RBAC의 경우 사용 권한은 리소스 ID 문자열의 목록입니다. 권한 부여 헤더의 보안 주체 토큰에 대한 액세스 권한을 부여하는 데이터 원본에 Azure 역할 할당(Storage Blob 데이터 판독기)이 있어야 합니다. 액세스 토큰과 관련된 보안 주체에 대한 역할 할당이 요청에 없는 경우, 필터는 문서를 제외합니다.

3. 결과 필터링

보안 필터는 요청의 userIds, groupIds, rbacScope를 검색 인덱스 내 모든 문서의 각 ACL 목록과 효율적으로 비교하여 사용자가 접근할 수 있는 결과로 반환되도록 결과를 제한합니다. 각 필터는 독립적으로 적용되며 필터가 성공하면 문서가 권한 있는 것으로 간주됩니다. 예를 들어 사용자가 userIds를 통해 문서에 액세스할 수 있지만 groupIds를 통해 액세스할 수 없는 경우 문서는 여전히 유효한 것으로 간주되어 사용자에게 반환됩니다.

쿼리 시 SharePoint 그룹

2026-05-01-preview REST API부터 Azure AI 검색 쿼리 시 소유자, 구성원, 방문자 및 사용자 지정 사이트 그룹과 같은 SharePoint 사이트 그룹 멤버 자격을 적용할 수 있습니다. 이 시나리오를 사용하려면 인덱스가 다음을 포함해야 합니다.

• 사용자를 대신하여 SharePoint 호출하는 데 사용되는 Microsoft Entra 애플리케이션의 페더레이션 ID 자격 증명을 참조하는 sharePointConnectorAppRegistration 속성입니다.
• 인덱싱된 각 항목의 SharePoint 사이트 URL을 저장하는 sharepointSiteUrl: true 특성으로 표시된 필드입니다(일반적으로 SharePointSiteUrl 이름이 지정되고 metadata_spo_site_url 원본 필드에서 채워집니다).

쿼리 시 Azure AI 검색 각 후보 문서의 등록된 애플리케이션 및 사이트 URL을 사용하여 해당 사이트에서 호출하는 사용자의 SharePoint 그룹 멤버 자격을 확인합니다. 확인된 그룹은 spg: 권한 필터 필드에 저장된 groupIds로 시작하는 값과 대조됩니다. spg: 접두사는 SharePoint 사이트 그룹을 접두사 없이 저장되는 Microsoft Entra 그룹 개체 ID와 구분합니다.

구성 세부 정보 및 제한 사항은 SharePoint 그룹 지원 구성 참조하세요.

SharePoint 권한 필터링이 누락되거나 예기치 않은 결과를 반환하는 경우 SharePoint 권한 필터링 문제 해결을 참조하세요.

예: SharePoint 사이트 그룹 강제 적용 쿼리

요청은 표준 ACL 적용 쿼리와 동일합니다. 검색 서비스는 인덱스의 sharePointConnectorAppRegistration 사용하여 호출자를 대신하여 SharePoint 그룹 멤버 자격을 확인합니다. 응답에서 GroupIds 접두사가 붙은 값을 보려면 select를 spg: 절에 포함하세요.

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"
}

쿼리 예제

다음은 sample 코드 쿼리 요청의 예입니다. 쿼리 토큰은 쿼리 사용자에 대한 Microsoft Entra 액세스 토큰입니다.

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"
}

잘못된 결과를 조사하기 위한 상승된 권한(미리 보기)

권한 메타데이터를 포함하는 쿼리를 디버깅하는 것은 검색 결과가 각 사용자에 한정되기 때문에 문제가 될 수 있습니다. 개발자 또는 관리자는 권한 메타데이터에 관계없이 결과를 반환하기 위해 권한 상승된 권한이 필요할 수 있으므로 권한이 없는 콘텐츠를 반환하는 쿼리와 관련된 문제를 조사할 수 있습니다.

조사하려면 다음을 수행할 수 있어야 합니다.

• 최종 사용자가 해당 사용자의 권한에 따라 볼 수 있는 문서 집합을 봅니다.

• 인덱스 내의 모든 문서를 확인하여 최종 사용자에게 표시되지 않는 이유를 조사합니다.

사용자 지정 헤더 x-ms-enable-elevated-read: true를 쿼리에 추가하여 이러한 작업을 수행할 수 있습니다.

관리자 권한의 읽기 요청에 대한 권한

검색 인덱스 데이터 기여자 권한 또는 읽기 권한 상승 권한을 포함하는 사용자 지정 역할이 있어야 합니다.

쿼리는 데이터 평면 작업이므로 사용자 지정 역할은 원자성 데이터 평면 권한으로만 구성됩니다. 사용자 지정 역할의 경우 Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read 권한을 추가합니다.

쿼리에 고급 읽기 헤더 추가

사용 권한을 설정한 후 쿼리를 실행할 수 있습니다. 다음 예제는 검색 인덱스를 위한 쿼리 요청입니다.

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
}

특정 미리 보기 API 버전에서 중요한 ACL 기능 동작 변경

REST API 버전 2025-11-01-preview이전에는 사용자 토큰이 제공되지 않았더라도 서비스 API 키 또는 권한 있는 Entra 역할을 사용할 때 이전 미리 보기 버전 2025-05-01-preview2025-08-01-preview 과 모든 문서를 반환했습니다. 사용자 토큰의 존재 여부를 확인하지 않은 애플리케이션은 올바르게 구현되지 않거나 모범 사례를 따르는 경우 실수로 최종 사용자에게 결과를 노출할 수 있습니다.

2025년 11월부터 이 동작이 변경되었습니다.

• ACL 권한 필터는 이제 ACL을 지원하는 모든 버전에서 서비스 API 키 또는 Entra 인증만 사용하는 경우에도 적용됩니다.
• 사용자 토큰을 생략하면 ACL로 보호된 콘텐츠가 반환되지 않습니다.
• 문제 해결을 위해 모든 문서를 보려면 REST API 버전 2026-05-01-preview 이상을 사용할 때 관리자 권한 헤더를 명시적으로 포함해야 합니다.

이 업데이트는 애플리케이션이 토큰 유효성 검사에 대한 모범 사례를 적용하지 않는 경우 콘텐츠를 보호하는 데 도움이 됩니다.

관련 콘텐츠

• 자습서: ADLS Gen2의 권한 메타데이터 인덱싱 및 권한 필터링된 결과를 사용하여 쿼리(미리 보기)
• 푸시 REST API(미리 보기)를 사용하여 문서 ACL(액세스 제어 목록) 인덱싱
• ADLS Gen2 인덱서를 사용하여 권한 메타데이터를 수집하고 사용자 액세스 권한(미리 보기)에 따라 검색 결과를 필터링합니다.
• Blob 인덱서 또는 지식 소스를 사용하여 RBAC 범위 메타데이터를 수집합니다
• SharePoint 인덱서를 사용하여 권한 메타데이터를 수집하고 사용자 액세스 권한(미리 보기)에 따라 검색 결과를 필터링합니다.