역할을 사용하여 Azure AI 검색 연결

참고

Azure AI 검색 Azure 포털, REST API 및 Azure SDK 통해 사용할 수 있습니다. 또한 엔터프라이즈 콘텐츠를 Microsoft Foundry 포털의 에이전트에 대해 재사용 가능한 사용 권한 인식 기술 자료로 변환하는 관리되는 기술 계층인 Foundry IQ를 뒷받침합니다.

Azure AI 검색 Microsoft Entra ID 통해 role 기반 액세스 제어 지원합니다. 역할 기반 액세스는 선택 사항이지만 권장됩니다. 다른 대안으로서, 기본으로 제공되는 키 기반 인증이 있습니다.

보안 주체에 여러 역할을 할당하는 경우 사용 권한이 결합됩니다. 역할 할당은 모든 도구 및 클라이언트 라이브러리에 적용됩니다.

이 문서에서는 서비스 관리, 개발 및 읽기 전용 쿼리 및 검색 액세스를 위한 기본 제공 역할을 할당하는 방법을 설명합니다. 또한 사용자 지정 역할을 만들고 역할 할당을 테스트하는 단계도 제공합니다.

팁 (조언)

필수 구성 요소

기본 제공 역할

역할은 컨트롤 플레인 또는 데이터 평면에 영향을 주는 권한의 컬렉션입니다.

  • 컨트롤 플레인: 서비스 프로비저닝, 구성 및 관리를 위한 작업입니다. 컨트롤 플레인 작업에는 검색 서비스 만들기 또는 삭제, API 키 나열, 네트워크 및 인증 설정 관리가 포함됩니다. Azure Resource Manager REST API, Search Management REST API 및 해당 Azure SDK 클라이언트 라이브러리를 통해 사용할 수 있습니다.

  • 데이터 평면: 검색 서비스 엔드포인트에 대한 작업입니다. 데이터 평면 작업은 개체 관리 및 콘텐츠 액세스라는 두 가지 범주로 구분됩니다. Search Service REST API 및 동등한 Azure SDK 클라이언트 라이브러리를 통해 사용할 수 있습니다.

역할 설명

다음 기본 제공 역할은 Azure AI 검색 권한을 부여합니다. 컨트롤 플레인 역할은 항상 사용할 수 있지만 데이터 평면 역할은 검색 서비스에서 역할 기반 액세스를 사용하도록 설정해야 합니다. 더 광범위한 액세스를 위해 기본 제공 역할을 결합하거나 필요한 특정 권한으로 사용자 지정 역할을 만들 수 있습니다.

역할 평면 설명
소유자 제어
  • 제어 평면에 대한 전체 액세스 권한, 역할 할당 및 인증 설정 변경 기능 포함.
  • 구독 관리자는 기본적으로 이 역할을 갖습니다.
  • API 키를 관리할 수 있습니다.
  • 검색 개체를 만들거나, 문서를 로드하거나, 인덱스를 쿼리하거나, 기술 자료에서 검색할 수 없습니다.
기여자 제어
  • 소유자와 동일한 수준의 컨트롤 플레인 액세스를 가지지만 역할을 할당할 수는 없습니다.
판독기 제어
  • 읽기 전용 컨트롤 플레인 액세스입니다.
  • 서비스 메트릭 및 개체 정의를 볼 수 있습니다.
  • API 키를 보거나 관리하거나, 문서를 로드하거나, 인덱스를 쿼리하거나, 기술 자료에서 검색할 수 없습니다.
Search 서비스 기여자 컨트롤 & 데이터
  • 제어 평면에 대한 전체 액세스. 데이터 평면 액세스는 개체 관리로 제한됩니다.
  • 인덱스, 인덱서, 기술 세트, 기술 자료 및 기타 검색 개체를 만들 수 있습니다.
  • 기술 자료에서 문서를 로드하거나 인덱스를 쿼리하거나 검색할 수 없습니다.
  • 전체 사용 권한 목록은 Microsoft.Search/searchServices/* 참조하세요.
검색 인덱스 데이터 기여자 데이터
  • 읽기/쓰기 콘텐츠 액세스.
  • 문서를 로드하고, 인덱스를 쿼리하고, 기술 자료에서 검색할 수 있습니다.
  • 개체 정의를 수정하거나 관리 키를 검색할 수 없습니다.
검색 인덱스 데이터 읽기 권한자 데이터
  • 읽기 전용 콘텐츠 액세스입니다.
  • 인덱스를 쿼리하고 기술 자료에서 검색할 수 있습니다.
  • 문서를 로드하거나, 개체 정의를 수정하거나, 관리자 키를 검색할 수 없습니다.

중요합니다

  • 소유자, 기여자 및 Search Service 기여자는 데이터 평면에 대한 전체 읽기-쓰기 액세스를 제공하는 관리 키를 검색할 수 있습니다. 신뢰할 수 있는 사용자에게만 이러한 역할을 부여합니다.
  • 기본적으로 데이터 평면 역할은 검색 서비스의 모든 인덱스에 적용됩니다. 검색 인덱스 데이터 기여자 또는 검색 인덱스 데이터 판독기를 단일 인덱스로 범위 지정하려면 단일 인덱스 액세스 권한 부여를 참조하세요.

사용 권한 요약

다음 표를 사용하여 필요한 권한을 제공하는 역할을 빠르게 찾을 수 있습니다.

사용 권한 소유자/기여자 판독기 Search 서비스 참가자 검색 인덱스 데이터 기여자 검색 인덱스 데이터 읽기 권한자
Azure AI 검색 서비스 만들기 및 구성 ✅ ❌ ✅ ❌ ❌
Azure 포털에서 서비스에 액세스 ✅ ✅ ✅ ❌ ❌
서비스 속성, 메트릭 및 엔드포인트 보기 ✅ ✅ ✅ ❌ ❌
서비스의 모든 개체 나열 ✅ ✅ ✅ ❌ ❌
할당량 및 서비스 통계 액세스 ✅ ❌ ✅ ❌ ❌
키 보기, 복사 및 다시 생성 ✅ ❌ ✅ ❌ ❌
인증 옵션 설정 ✅ ❌ ✅ ❌ ❌
역할, 정책 및 정의 보기 ✅ ✅ ✅ ❌ ❌
네트워크 보안 및 프라이빗 연결 구성 ✅ ❌ ✅ ❌ ❌
검색 개체 만들기, 실행 및 관리 1 ❌ ❌ ✅ ❌ ❌
인덱싱을 위한 데이터 업로드 2 ❌ ❌ ❌ ✅ ❌
인덱스 쿼리 ❌ ❌ ❌ ✅ ✅
기술 자료에서 검색 ❌ ❌ ❌ ✅ ✅
높은 권한 읽기를 사용하여 권한 필터 무시 ❌ ❌ ❌ ✅ ❌

1 인덱스, 인덱서, 데이터 원본, 기술 세트, 별칭, 동의어 맵, 디버그 세션, 기술 자료 및 기술 원본을 포함합니다. 인덱서는 실행 및 다시 설정 작업도 지원합니다.

2 소유자 또는 참가자는 다른 클라이언트에서 문서를 업로드할 수 없더라도 데이터 가져오기 마법사 를 실행하여 인덱스를 만들고 로드할 수 있습니다. 마찬가지로 인덱서는 인덱스 별 역할 할당에 관계없이 검색 서비스의 인덱스에 쓸 수 있습니다. 두 경우 모두 검색 서비스(사용자가 아님)는 Microsoft.Search/searchServices/indexes/documents/* 권한을 사용하여 데이터 평면 작업을 수행합니다.

기본 제공 역할 할당

이 섹션에서는 다음에 대한 역할을 할당합니다.

서비스 관리를 위한 역할 할당

다음 역할을 사용하면 검색 서비스를 만들고 구성하고 관리할 수 있습니다. 이러한 역할은 계층적이므로 필요한 액세스 수준에 따라 역할을 선택합니다.

역할 아이디
소유자 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
기여자 b24988ac-6180-42a0-ab88-20f7382dd24c
판독기 acdd72a7-3385-48ef-bd42-f606fba81ae7

  1. Azure 포털 검색 서비스로 이동합니다.

  2. 왼쪽 창에서 액세스 제어(IAM)를 선택합니다.

  3. 추가>역할 할당 추가를 선택합니다.

    서비스 관리 역할을 할당하기 위한 액세스 제어(IAM) 페이지의 스크린샷.

  4. 소유자, 참가자 또는 읽기권한자 역할을 선택합니다.

  5. Members 탭에서 Microsoft Entra 사용자 또는 그룹 ID를 선택합니다. 다른 Azure 서비스에 대한 권한을 설정하는 경우 시스템 할당 또는 사용자 할당 관리 ID를 선택합니다.

  6. 검토 + 할당 탭에서 검토 + 할당을 선택하여 역할을 할당합니다.

개발을 위한 역할 할당

다음 역할을 사용하면 검색 개체를 만들고, 문서를 로드하고, 인덱스를 쿼리하고, 기술 자료에서 검색할 수 있습니다. 세 가지 역할을 모두 할당하여 개발 작업의 전체 범위를 다룹니다.

역할 아이디
Search 서비스 기여자 7ca78c08-252a-4471-8644-bb5ff32d4ba0
검색 인덱스 데이터 기여자 8ebe5a00-799e-43f5-93ac-243d3dce84a7
검색 인덱스 데이터 읽기 권한자 1407120a-92aa-4202-b7e9-c0e197c71c8f

  1. Azure 포털 검색 서비스로 이동합니다.

  2. 왼쪽 창에서 액세스 제어(IAM)를 선택합니다.

  3. 추가>역할 할당 추가를 선택합니다.

    개발 역할을 할당하기 위한 액세스 제어(IAM) 페이지의 스크린샷.

  4. Search Service 참가자를 선택합니다.

  5. Members 탭에서 Microsoft Entra 사용자 또는 그룹 ID를 선택합니다. 다른 Azure 서비스에 대한 권한을 설정하는 경우 시스템 할당 또는 사용자 할당 관리 ID를 선택합니다.

  6. 검토 + 할당 탭에서 검토 + 할당을 선택하여 역할을 할당합니다.

  7. 검색 인덱스 데이터 기여자 및 검색 인덱스 데이터 판독기를 할당하려면 다음 단계를 반복합니다.

읽기 전용 액세스에 대한 역할 할당

인덱스 및 기술 자료에 대한 읽기 액세스만 필요한 앱 및 프로세스에는 다음 역할을 사용합니다. 지원되는 작업에는 인덱스에 대한 검색, 조회, 자동 완성 및 제안이 포함되며, 기술 자료에 대한 검색이 포함됩니다.

역할 아이디
검색 인덱스 데이터 읽기 권한자 1407120a-92aa-4202-b7e9-c0e197c71c8f

  1. Azure 포털 검색 서비스로 이동합니다.

  2. 왼쪽 창에서 액세스 제어(IAM)를 선택합니다.

  3. 추가>역할 할당 추가를 선택합니다.

    읽기 전용 데이터 액세스 역할을 할당하기 위한 액세스 제어(IAM) 페이지의 스크린샷

  4. 검색 인덱스 데이터 판독기 역할을 선택합니다.

  5. Members 탭에서 Microsoft Entra 사용자 또는 그룹 ID를 선택합니다. 다른 Azure 서비스에 대한 권한을 설정하는 경우 시스템 할당 또는 사용자 할당 관리 ID를 선택합니다.

  6. 검토 + 할당 탭에서 검토 + 할당을 선택하여 역할을 할당합니다.

역할 할당 테스트

클라이언트를 사용하여 역할 할당을 테스트합니다. 역할은 누적된다는 것을 잊지 마세요. 리소스(검색 서비스) 수준에서 구독 또는 리소스 그룹 수준으로 범위가 지정된 상속된 역할을 삭제하거나 거부할 수 없습니다.

계속하기 전에 키 없는 연결에 대한 애플리케이션을 구성 하고 역할 할당을 준비합니다.

  1. Azure 포털 검색 서비스로 이동합니다.

  2. 왼쪽 창에서 검색 관리>인덱스를 선택하여 인덱스 관련 권한을 테스트합니다.

    • Search Service 참가자는 검색 개체를 만들고 수정하고 삭제할 수 있지만 문서를 로드하거나 쿼리를 실행할 수는 없습니다. 권한을 확인하려면 검색 인덱스를 만듭니다.

    • 검색 인덱스 데이터 기여자는 문서를 로드할 수 있습니다. Azure 포털의 Import data 마법사 외부에는 문서를 로드하는 옵션이 없지만 인덱서를 재설정하고 실행하여 문서 로드 권한을 확인할 수 있습니다.

    • 검색 인덱스 데이터 판독기는 인덱스를 쿼리할 수 있습니다. 권한을 확인하려면 검색 탐색기를 사용합니다. 쿼리를 보내고 결과를 볼 수 있지만 인덱스 정의를 보거나 인덱스를 만들 수는 없습니다.

단일 인덱스 액세스 권한 부여

어떤 시나리오에서는 인덱스 같은 단일 리소스에 대한 애플리케이션의 액세스를 제한하고자 할 수 있습니다.

현재 Azure 포털은 인덱스 수준에서 역할 할당을 지원하지 않습니다. Azure CLI, PowerShell 또는 REST API를 사용하여 단일 인덱스로 범위가 지정된 역할을 할당합니다.

인덱스별 범위 및 인덱서 작업

인덱스별 역할 할당은 사용자 또는 애플리케이션의 쿼리 또는 문서 업로드와 같은 직접 API 작업에만 적용됩니다. 인덱서는 서비스 수준 자격 증명으로 작동하기 때문에 인덱스별 권한에 의해 제한되지 않습니다.

Search Service 기여자 역할이 있는 사용자는 검색 서비스의 인덱스에 쓰는 인덱서를 만들 수 있으며, 해당 사용자에게 인덱스별 역할 할당이 없는 인덱스도 만들 수 있습니다.

인덱스 간의 엄격한 데이터 격리를 위해 다음 방법을 고려합니다.

  • 인덱스 수준 격리가 필요한 팀 또는 사용자에 대해 별도의 검색 서비스를 사용합니다.
  • 인덱서를 관리하는 관리자에게만 Search Service 참가자 를 할당합니다.
  • 보안 필터와 함께 문서 수준 액세스 제어 를 사용하여 공유 인덱스 내에서 쿼리 결과를 제한합니다.

사용자 지정 역할 만들기

기본 제공 역할이 적절한 사용 권한 조합을 제공하지 않는 경우 필요한 작업을 지원하는 사용자 지정 역할을 만들 수 있습니다.

다음 예제에서는 검색 인덱스 데이터 판독 기를 복제한 다음 이름으로 인덱스를 나열하는 기능을 추가합니다. 일반적으로 검색 서비스의 인덱스를 나열하는 것은 관리 권한으로 간주됩니다.

  1. Azure 포털 로그인하고 검색 서비스로 이동합니다.

  2. 왼쪽 창에서 액세스 제어(IAM)를 선택합니다.

  3. 역할 탭에서 검색 인덱스 데이터 판독자 또는 다른 역할을 찾은 다음, 줄임표(...)를 선택하고 복제를 선택합니다.

  4. Basics 탭에서 "인덱스 Data Explorer 검색"과 같은 사용자 지정 역할의 이름을 입력한 다음 Next 선택합니다.

  5. 사용 권한 탭에서 사용 권한 추가를 선택합니다.

  6. 권한 창에서 Microsoft Search 타일을 선택합니다.

  7. 맨 위에서 작업을 선택한 상태에서 다음 권한을 설정합니다.

    • Microsoft.Search/operations 아래에서 읽기: 사용 가능한 모든 작업 나열을 선택합니다.
    • Microsoft.Search/searchServices/indexes 아래에서 Read: Read Index 선택합니다.

  8. 위쪽의 데이타 작업로 전환하고 Microsoft.Search/searchServices/indexes/documents 아래에서 Read : 문서 읽기 선택합니다.

    JSON 정의는 다음 예제와 유사합니다.

    {
    "properties": {
        "roleName": "Search Index Data Explorer",
        "description": "List all indexes on the service and query them.",
        "assignableScopes": [
            "/subscriptions/<subscription>/resourceGroups/<resource-group>"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
    }
}

  9. 추가를 선택하여 창을 닫습니다.

  10. 검토 + 만들기를 선택하여 역할을 만듭니다.

    이제 역할에 사용자 및 그룹을 할당할 수 있습니다. 이러한 단계에 대한 자세한 내용은 Azure 포털 사용하여 사용자 지정 역할 Azure 만들기 또는 업데이트를 참조하세요.

조건부 액세스 정책 만들기

다단계 인증과 같은 조직 정책을 적용해야 하는 경우 Microsoft Entra 조건부 액세스 사용합니다.

Azure AI 검색 대한 조건부 액세스 정책을 만들려면 다음을 수행합니다.

  1. Azure 포털 로그인합니다.

  2. Microsoft Entra 조건부 액세스를 검색합니다.

  3. 개요 페이지에서 새 정책 만들기를 선택합니다.

  4. Cloud 앱 또는 작업 아래에서 정책을 설정하는 방법에 따라 클라우드 앱으로 Azure AI 검색 추가합니다.

  5. 정책의 나머지 매개 변수를 업데이트합니다. 예를 들어 정책이 적용되는 사용자 및 그룹을 지정합니다.

  6. 해당 정책을 저장합니다.

중요합니다

검색 서비스에 할당된 관리 ID가 있는 경우 특정 검색 서비스가 클라우드 앱으로 표시됩니다. 그러나 특정 검색 서비스를 선택하면 정책이 적용되지 않습니다. 대신 일반 Azure AI 검색 클라우드 앱을 선택하여 검색 서비스에 조건부 액세스 정책을 적용합니다.

Troubleshooting

인증에 역할 기반 액세스 제어를 사용하는 애플리케이션을 개발하는 경우 몇 가지 일반적인 문제가 발생할 수 있습니다.

  • 검색 서비스의 기본 구성은 키 기반 인증입니다. 이 설정을 둘 다 또는 역할 기반 액세스 제어로 변경하지 않으면 기본 권한에 관계없이 역할 기반 인증을 사용하는 모든 요청이 자동으로 거부됩니다.

  • 요청에 역할 기반 자격 증명과 함께 API 키가 포함된 경우 서비스는 키를 사용하여 인증합니다. 역할 기반 인증을 사용하려면 요청 헤더에서 API 키를 제거합니다.

  • 권한 부여 토큰이 관리 ID 에서 제공되고 최근에 적절한 권한을 할당한 경우 권한 할당이 적용되는 데 몇 시간이 걸릴 수 있습니다 .

  • 문서 수준 권한이 있는 쿼리가 예상된 결과를 반환하지 않는 경우 검색 인덱스 데이터 기여자를 사용하거나 관리자 권한으로 사용자 지정 역할을 만들어 조사할 수 있습니다.

다음 단계:

이 문서에서는 Azure AI 검색 제어 및 데이터 평면 작업에 역할을 할당하는 방법을 설명합니다. 애플리케이션 코드에 역할 기반 액세스를 추가하는 방법에 대한 포괄적인 지침은 다음과 같습니다.

아이덴티티를 사용하여 앱을 Azure AI 검색에 연결하세요

  • Last updated on