Azure AI 검색에서 역할 기반 액세스 제어 사용 또는 사용 안 함

아티클
01/18/2025

Azure AI Search는 모든 컨트롤 플레인 및 데이터 평면 작업에 대해 키 없는 인증과 키 기반 인증 을 모두 지원합니다. Azure RBAC(역할 기반 액세스 제어)를 통해 모든 컨트롤 플레인 및 데이터 평면 작업에 대해 Microsoft Entra ID 인증 및 권한 부여를 사용할 수 있습니다.

Important

검색 서비스를 만들 때 키 기반 인증이 기본값이지만 가장 안전한 옵션은 아닙니다. 이 문서에 설명된 대로 역할 기반 액세스로 바꾸는 것이 좋습니다.

Azure AI Search에 대한 권한 있는 데이터 평면 액세스에 대한 역할을 할당하려면 먼저 검색 서비스에서 역할 기반 액세스 제어를 사용하도록 설정해야 합니다. 서비스 관리(컨트롤 플레인)에 대한 역할이 기본 제공되며 사용하거나 사용하지 않도록 설정할 수 없습니다.

참고 항목

데이터 평면은 인덱싱 또는 쿼리와 같은 검색 서비스 엔드포인트에 대한 작업 또는 Search Service REST API 또는 동등한 Azure SDK 클라이언트 라이브러리에 지정된 다른 작업을 나타냅니다. 컨트롤 플레 인은 검색 서비스 만들기 또는 구성과 같은 Azure 리소스 관리를 나타냅니다.

필수 조건

무료를 포함하여 모든 계층의 모든 지역의 검색 서비스입니다.
소유자, 사용자 액세스 관리자 또는 Microsoft.Authorization/roleAssignments/write 권한이 있는 사용자 지정 역할입니다.

데이터 평면 작업에 대한 역할 기반 액세스 사용

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

데이터 평면에 역할을 사용하도록 설정하면 변경 내용이 즉시 적용되지만 역할을 할당하기 전에 몇 초 정도 기다립니다.

권한이 없는 요청에 대한 기본 오류 모드는 http401WithBearerChallenge입니다. 또는 실패 모드를 http403(으)로 설정할 수 있습니다.

Azure Portal에 로그인하고 검색 서비스로 이동합니다.
설정을 선택한 다음 왼쪽 탐색 창에서 키를 선택합니다.

역할 기반 컨트롤을 선택합니다. 현재 키를 사용하고 있고 클라이언트를 역할 기반 액세스 제어로 전환하는 데 시간이 필요한 경우에만 둘 다 선택합니다.

옵션	설명
API 키(기본값)	권한 부여를 위해 요청 헤더에 API 키가 필요합니다.
역할 기반 액세스 제어(권장)	작업을 완료하려면 역할 할당의 멤버 자격이 필요합니다. 요청의 인증 헤더도 필요합니다.
모두	요청은 API 키 또는 역할 기반 액세스 제어를 사용하면 유효하지만 동일한 요청에 둘 다 제공하는 경우 API 키가 사용됩니다.

관리자로서 역할 전용 접근 방식을 선택하는 경우 사용자 계정에 데이터 평면 역할을 할당하여 Azure Portal에서 데이터 평면 작업에 대한 전체 관리 액세스를 복원합니다. 역할에는 Search Service 기여자, 검색 인덱스 데이터 기여자 및 검색 인덱스 데이터 읽기 권한자 등이 있습니다. 동등한 액세스 권한을 원하는 경우 처음 두 역할이 필요합니다.

간혹 역할 할당이 적용되는 데 5~10분이 걸릴 수 있습니다. 이 경우 데이터 평면 작업에 사용되는 Azure Portal 페이지에 다음 메시지가 표시됩니다.

역할만 지원하려면 다음 스크립트를 실행합니다.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

또는 다음 스크립트를 실행하여 키와 역할을 모두 지원합니다.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --aad-auth-failure-mode http401WithBearerChallenge `
  --auth-options aadOrApiKey

자세한 내용은 Azure CLI를 사용하여 Azure AI 검색 서비스 관리를 참조하세요.

이 명령을 실행하여 인증 유형을 역할로만 설정합니다.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

또는 다음 명령을 실행하여 키와 역할을 모두 지원합니다.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -AuthOption AadOrApiKey

자세한 내용은 PowerShell을 사용하여 Azure AI 검색 서비스 관리를 참조하세요.

역할 기반 액세스 제어를 위해 서비스를 구성하려면 관리 REST API 서비스 만들기 또는 업데이트를 사용합니다.

관리 REST API 호출 일체는 Microsoft Entra ID를 통해 인증됩니다. 인증된 요청을 설정하는 데 도움이 필요하면 REST를 사용하여 Azure AI 검색 관리를 참조하세요.

현재 구성을 검토할 수 있도록 서비스 설정을 가져옵니다.

GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01

PATCH를 사용하여 서비스 구성을 업데이트합니다. 다음 수정을 통해 키와 역할 기반 액세스를 모두 사용할 수 있습니다. 역할 전용 구성을 원하는 경우 API 키 사용 안 함을 참조하세요.

“속성”에서 “authOptions”를 “aadOrApiKey”로 설정합니다. “authOptions”를 설정하려면 “disableLocalAuth” 속성이 false여야 합니다.

필요에 따라 “aadAuthFailureMode”를 설정하여 인증 실패 시 403 대신 401이 반환되는지 여부를 지정합니다. 유효한 값은 “http401WithBearerChallenge” 또는 “http403”입니다.
```
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
{
    "properties": {
        "disableLocalAuth": false,
        "authOptions": {
            "aadOrApiKey": {
                "aadAuthFailureMode": "http401WithBearerChallenge"
            }
        }
    }
}
```

역할 기반 액세스 제어 사용 안 함

데이터 평면 작업에 대한 역할 기반 액세스 제어를 사용하지 않도록 설정하고 대신 키 기반 인증을 사용할 수 있습니다. 예를 들어 권한 문제를 배제하기 위해 테스트 워크플로의 일부로 이 작업을 수행할 수 있습니다.

Azure Portal에서 역할 기반 액세스 제어를 사용하지 않도록 설정하려면 다음을 수행합니다.

Azure Portal에 로그인하고 검색 서비스 페이지를 엽니다.
설정을 선택한 다음 왼쪽 탐색 창에서 키를 선택합니다.
API 키를 선택합니다.

API 키 인증 사용 안 함

기본 제공 역할 및 Microsoft Entra 인증만 사용하는 경우 키 액세스 또는 로컬 인증을 서비스에서 사용하지 않도록 설정할 수 있습니다. API 키를 사용하지 않도록 설정하면 검색 서비스가 헤더에서 API 키를 전달하는 모든 데이터 관련 요청을 거부합니다.

관리자 API 키는 사용하지 않도록 설정할 수 있지만 삭제할 수는 없습니다. 쿼리 API 키는 삭제할 수 있습니다.

보안 기능을 사용하지 않도록 설정하려면 소유자 또는 기여자 권한이 필요합니다.

Azure Portal에서 검색 서비스로 이동합니다.
왼쪽 탐색 창에서 키를 선택합니다.
역할 기반 액세스 제어를 선택합니다.

변경 내용은 즉시 적용되지만 테스트하기 전에 몇 초 정도 기다립니다. 소유자, 서비스 관리자 또는 공동 관리자의 구성원으로 역할을 할당할 수 있는 권한이 있다고 가정하면 포털 기능을 사용하여 역할 기반 액세스를 테스트할 수 있습니다.

키 기반 인증을 사용하지 않도록 설정하려면 -disableLocalAuth를 true로 설정합니다. 이는 이전 섹션에 제시된 "역할만 사용" 스크립트와 동일한 구문입니다.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

키 인증을 다시 사용하도록 설정하려면 -disableLocalAuth를 false로 설정합니다. Search Service는 요청 시 자동으로 API 키 수락을 다시 시작합니다(지정된 것으로 가정).

자세한 내용은 Azure CLI를 사용하여 Azure AI 검색 서비스 관리를 참조하세요.

키 기반 인증을 사용하지 않도록 설정하려면 DisableLocalAuth를 true로 설정합니다. 이는 이전 섹션에 제시된 "역할만 사용" 스크립트와 동일한 구문입니다.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

키 인증을 다시 사용하도록 설정하려면 DisableLocalAuth를 false로 설정합니다. Search Service는 요청 시 자동으로 API 키 수락을 다시 시작합니다(지정된 것으로 가정).

자세한 내용은 PowerShell을 사용하여 Azure AI 검색 서비스 관리를 참조하세요.

키 기반 인증을 사용하지 않도록 설정하려면 "disableLocalAuth"를 true로 설정합니다.

현재 구성을 검토할 수 있도록 서비스 설정을 가져옵니다.

GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01

PATCH를 사용하여 서비스 구성을 업데이트합니다. 다음 수정은 "authOptions"를 null로 설정합니다.

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
{
    "properties": {
        "disableLocalAuth": true
    }
}

키 인증을 다시 사용하도록 설정하려면 “disableLocalAuth”를 false로 설정합니다. Search Service는 요청 시 자동으로 API 키 수락을 다시 시작합니다(지정된 것으로 가정).

다음 단계

검색 서비스에 액세스하기 위한 역할 설정

다음을 통해 공유