Microsoft Entra ID를 사용하여 검색 앱에 대한 액세스 권한을 부여합니다.

  • 아티클

Azure AI 검색에 빌드된 검색 애플리케이션은 이제 인증된 액세스 및 권한 있는 액세스를 위해 Microsoft ID 플랫폼을 사용할 수 있습니다. Azure에서 ID 공급자는 Microsoft Entra ID입니다. Microsoft Entra ID를 사용하는 주요 이점은 자격 증명 및 API 키를 더 이상 코드에 저장할 필요가 없다는 것입니다. Microsoft Entra는 애플리케이션을 실행하는 보안 주체(사용자, 그룹 또는 서비스)를 인증합니다. 인증이 성공하면 Microsoft Entra ID는 애플리케이션에 액세스 토큰을 반환하고, 애플리케이션은 액세스 토큰을 사용하여 Azure AI 검색에 대한 요청에 권한을 부여할 수 있습니다.

이 문서에서는 Microsoft Entra ID에 대해 클라이언트를 구성하는 방법을 보여줍니다.

  • 인증을 위해 애플리케이션에 대한 관리 ID를 만듭니다. 다른 형식의 보안 주체 개체를 사용할 수 있지만 이 문서에서는 자격 증명을 관리할 필요가 없으므로 관리 ID를 사용합니다.

  • 권한 부여를 위해 쿼리를 실행하거나 인덱싱 작업을 관리할 수 있는 권한을 부여하는 관리 ID에 Azure 역할을 할당합니다.

  • TokenCredential()을 호출하도록 클라이언트 코드를 업데이트합니다. 예를 들어 Azure.Identity로 Microsoft Entra ID를 통해 인증하도록 새 SearchClient(엔드포인트, 새 DefaultAzureCredential())를 시작할 수 있습니다.

데이터 평면에 대한 역할 기반 액세스 구성

적용 대상: 검색 인덱스 데이터 기여자, 검색 인덱스 데이터 판독기, Search Service 기여자

이 단계에서는 OAuth2 액세스 토큰을 제공하는 데이터 요청에서 권한 부여 헤더를 인식하도록 검색 서비스를 구성합니다.

  1. Azure Portal에 로그인하고 Search Service 페이지를 엽니다.

  2. 왼쪽 탐색 창에서 키를 선택합니다.

    인증 옵션이 있는 키 페이지의 스크린샷.

  3. API 액세스 제어 옵션을 선택합니다. 유연성을 원하거나 앱을 마이그레이션해야 하는 경우 둘 다 사용하는 것이 좋습니다.

    옵션 설명
    API 키 (기본값) 권한 부여를 위해 요청 헤더에 관리자 또는 쿼리 API 키가 필요합니다. 역할이 사용되지 않습니다.
    역할 기반 액세스 제어 다음 단계에서 설명하는 작업을 완료하려면 역할 할당의 멤버 자격이 필요합니다. 각 요청에는 인증 헤더가 필요합니다.
    모두 요청은 API 키 또는 역할 기반 액세스 제어를 사용하여 유효합니다.

변경 내용은 즉시 적용되지만 테스트하기 전에 몇 초 정도 기다립니다.

검색 서비스 작업 및 콘텐츠에 대한 모든 네트워크 호출은 선택한 옵션인 API 키, 전달자 토큰 또는 둘 다를 선택하는 경우 둘 중 하나를 준수합니다.

포털에서 역할 기반 액세스 제어를 사용하도록 설정하면 권한 부여가 실패할 경우 실패 모드는 “http401WithBearerChallenge”가 됩니다.

관리 ID 만들기

이 단계에서는 클라이언트 애플리케이션에 대한 관리 ID를 만듭니다.

  1. Azure Portal에 로그인합니다.

  2. 관리 ID를 검색합니다.

  3. 만들기를 실행합니다.

  4. 관리 ID에 이름을 지정하고 지역을 선택합니다. 그런 다음 만들기를 선택합니다.

    관리 ID 만들기 마법사의 스크린샷.

관리 ID에 역할 할당

다음으로 검색 서비스에 대한 클라이언트의 관리 ID 액세스 권한을 부여해야 합니다. Azure AI 검색에는 다양한 기본 제공 역할이 있습니다. 사용자 지정 역할을 만들 수도 있습니다.

최소 권한을 부여하는 것이 모범 사례입니다. 애플리케이션에서 쿼리만 처리해야 하는 경우 검색 인덱스 데이터 읽기 권한자 역할을 할당해야 합니다. 또는 클라이언트에 검색 인덱스에 대한 읽기 및 쓰기 권한이 모두 필요한 경우 검색 인덱스 데이터 기여자 역할을 사용해야 합니다.

  1. Azure Portal에 로그인합니다.

  2. 검색 서비스로 이동합니다.

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

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

    역할 할당 추가 메뉴가 열려 있는 액세스 제어(IAM) 페이지의 스크린샷.

  5. 적용 가능한 역할을 선택합니다.

    • 소유자

    • 기여자

    • 판독기

    • Search 서비스 참가자

    • 검색 인덱스 데이터 기여자

    • 검색 인덱스 데이터 읽기 권한자

      참고 항목

      소유자, 기여자, 읽기 권한자 및 Search Service 기여자는 컨트롤 플레인 역할이며 검색 인덱스 내의 데이터에 대한 액세스 권한을 제공하지 않습니다. 데이터 액세스의 경우 검색 인덱스 데이터 기여자 또는 검색 인덱스 데이터 읽기 권한자 역할을 선택합니다. 각 역할의 범위와 목적에 대한 자세한 내용은 검색에 사용되는 기본 제공 역할을 참조하세요.

  6. 구성원 탭에서 검색 서비스에 대한 액세스 권한을 부여할 관리 ID를 선택합니다.

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

애플리케이션에서 검색 서비스, 개체 및 콘텐츠에 대한 포괄적인 액세스가 필요한 경우 검색 서비스 기여자 및 검색 인덱스 데이터 기여자와 같은 여러 역할을 할당할 수 있습니다.

PowerShell을 사용하여 역할을 할당할 수도 있습니다.

클라이언트에서 Microsoft Entra 인증 설정

검색 서비스에 관리 ID 및 역할 할당이 있으면 애플리케이션에 코드를 추가하여 보안 주체를 인증하고 OAuth 2.0 토큰을 획득할 준비가 된 것입니다.

역할 기반 액세스 제어에 다음 클라이언트 라이브러리를 사용합니다.

참고 항목

Microsoft Entra ID에서 사용되는 OAuth 2.0 코드 권한 부여 흐름에 대한 자세한 내용은 OAuth 2.0 코드 권한 부여 흐름을 사용하여 Microsoft Entra 웹 애플리케이션에 대한 액세스 권한 부여를 참조하세요.

다음 지침은 코드 변경 내용을 보여 주는 기존 C# 샘플을 참조합니다.

  1. 시작점으로 빠른 시작: Azure SDK를 사용하여 전체 텍스트 검색에서 C# 섹션의 소스 코드 를 복제합니다.

    샘플은 현재 키 기반 인증 및 AzureKeyCredential을 사용하여 SearchClient 및 SearchIndexClient를 만들지만 약간만 변경하면 역할 기반 인증으로 전환할 수 있습니다.

  2. Azure.Search.Documents NuGet 패키지를 버전 11.4 이상으로 업데이트합니다.

  3. Azure.Identity 라이브러리를 가져와서 다른 인증 기술에 액세스합니다.

  4. Program.cs의 Main() 시작 부분에서 AzureKeyCredential을 사용하는 대신 아래 코드 조각에서처럼 DefaultAzureCredential을 사용합니다.

    // Create a SearchIndexClient to send create/delete index commands
SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
// Create a SearchClient to load and query documents
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());

로컬 테스트

사용자가 할당한 관리 ID는 Azure 환경에서만 작동합니다. 이 코드를 로컬에서 실행하면 DefaultAzureCredential은 사용자 인증 정보를 사용한 인증으로 대체됩니다. 코드를 로컬에서 실행하려는 경우 검색 서비스에 대한 필수 액세스 권한을 스스로 부여해야 합니다.

  1. 빠른 시작 샘플에서 모든 작업을 실행하기 위한 역할 할당이 계정에 있는지 확인합니다. 인덱스를 만들고 쿼리하려면 "인덱스 데이터 읽기 권한자 쿼리" 및 "인덱스 데이터 기여자 쿼리"를 사용합니다.

  2. 도구>옵션>Azure 서비스 인증으로 이동하여 Azure 로그온 계정을 선택합니다.

이제 권한 부여를 위해 역할 기반 액세스 제어를 사용하여 로컬 시스템의 Visual Studio에서 프로젝트를 실행할 수 있습니다.

참고 항목

Azure.Identity 설명서에는 DefaultAzureCredential 및 .NET용 Azure SDK에서 Microsoft Entra 인증을 사용하는 방법에 대한 자세한 내용이 있습니다. DefaultAzureCredential은 합리적인 기본 동작으로 일반적인 시나리오를 처리하여 SDK 시작을 간소화하기 위한 것입니다. 더 많은 제어를 원하거나 자신의 시나리오가 기본 설정에서 제공되지 않는 개발자는 다른 자격 증명 형식을 사용해야 합니다.

참고 항목