키 인증을 사용하여 Azure AI Search에 연결
Azure AI Search는 검색 서비스에 연결할 때 사용할 수 있는 키 기반 인증을 제공합니다. API 키는 임의로 생성된 52개의 숫자와 문자로 구성된 고유한 문자열입니다. 요청과 API 키가 모두 유효한 경우 검색 서비스 엔드포인트에 대한 요청이 수락됩니다.
참고 항목
Azure AI Search에서 "핵심" 용어가 사용되는 방식에 대한 빠른 참고 사항입니다. 이 문서에서 설명하는 "API 키"는 요청을 인증하는 데 사용되는 GUID를 나타냅니다. 별도의 용어인 "문서 키"는 검색 인덱스에서 문서를 고유하게 식별하는 데 사용되는 인덱스화된 콘텐츠의 고유한 문자열을 나타냅니다.
API 키 형식
요청을 인증하는 데 사용되는 두 종류의 키가 있습니다.
| Type | 권한 수준 | 최대 | 만든 방법 |
|---|---|---|---|
| 관리자 | 모든 콘텐츠 작업에 대한 모든 권한(읽기-쓰기) | 2 1 | 포털에서 기본 및 보조 키라고 하는 두 개의 관리자 키는 서비스를 만들 때 생성되고 요청 시 개별적으로 다시 생성할 수 있습니다. |
| 쿼리 | 검색 인덱스의 문서 컬렉션으로 범위가 지정된 읽기 전용 액세스 | 50 | 하나의 쿼리 키가 서비스와 함께 생성됩니다. 검색 서비스 관리자가 필요에 따라 더 많이 만들 수 있습니다. |
1 두 개이면 서비스에 대해 액세스를 지속하는 데 하나의 키를 사용하는 동안 다른 키를 롤오버할 수 있습니다.
시각적으로는 관리자 키 및 쿼리 키 간의 구분이 없습니다. 두 키는 임의로 생성된 52개의 영숫자 문자로 구성된 문자열입니다. 애플리케이션에서 지정된 키의 형식을 잃어버린 경우 포털에서 키 값을 확인할 수 있습니다.
연결에 API 키 사용
API 키는 인덱스 만들기 또는 액세스 또는 Search REST API에 표시되는 기타 요청과 같은 데이터 평면(콘텐츠) 요청에 사용됩니다. 서비스를 만들 때 API 키는 데이터 평면 작업을 위한 유일한 인증 메커니즘이지만, 코드에서 하드 코딩된 키를 사용할 수 없는 경우 키 인증을 Azure 역할로 바꾸거나 보완할 수 있습니다.
API 키는 검색 서비스에 대한 클라이언트 요청에 지정됩니다. 요청에 유효한 API 키를 전달하는 것은 요청이 권한 있는 클라이언트에서 온 것으로 간주됩니다. 개체를 만들기, 수정 또는 삭제하는 경우 관리 API 키가 필요합니다. 그렇지 않으면 쿼리 키는 일반적으로 쿼리를 실행하는 클라이언트 애플리케이션에 배포됩니다.
REST API 호출에 대한 요청 헤더 또는 Azure SDK의 azure.search.documents 클라이언트 라이브러리를 호출하는 코드에서 API 키를 지정할 수 있습니다. Azure Portal을 사용하여 작업을 수행하는 경우 역할 할당에 따라 액세스 수준이 결정됩니다.
원본 파일에서 하드 코딩된 키를 사용하는 모범 사례는 다음과 같습니다.
데이터 공개가 위험하지 않고(예: 샘플 데이터를 사용하는 경우) 방화벽 뒤에서 작업하는 경우에만 API 키를 사용합니다. API 키 노출은 데이터와 검색 서비스의 무단 사용에 모두 위험합니다.
게시하기 전에 항상 코드, 샘플 및 학습 자료를 검사 유효한 API 키를 숨기지 않도록 합니다.
프로덕션 워크로드의 경우 Microsoft Entra ID 및 역할 기반 액세스로 전환합니다. 또는 API 키를 계속 사용하려면 API 키에 액세스할 수 있는 사용자를 항상 모니터링하고 정기적으로 API 키를 다시 생성해야 합니다.
Azure Portal에서 API 키를 사용하는 방법:
- 키 인증이 기본 제공됩니다. 기본적으로 포털은 먼저 API 키를 시도합니다. 그러나 API 키를 사용 중지하고 역할 할당을 설정하면 포털에서 대신 역할 할당을 사용합니다.
API 키를 보거나 관리할 수 있는 권한
API 키 보기 및 관리 권한은 역할 할당을 통해 전달됩니다. 소유자,
- 소유자
- 기여자
- Search 서비스 기여자
- 관리자 및 공동 관리자(클래식)
다음 역할은 API 키에 대한 액세스 권한이 없습니다.
- 판독기
- 검색 인덱스 데이터 기여자
- 검색 인덱스 데이터 읽기 권한자
기존 키 찾기
Azure Portal에서 또는 PowerShell, Azure CLI나 REST API를 통해 API 키를 보고 관리할 수 있습니다.
Azure Portal에 로그인하고 검색 서비스를 찾습니다.
설정에서 키를 선택하여 관리자 및 쿼리 키를 봅니다.
쿼리 키 만들기
쿼리 키는 문서 컬렉션을 대상으로 하는 작업의 인덱스 내 문서에 대한 읽기 전용 액세스에 사용됩니다. 검색, 필터 및 제안 쿼리는 쿼리 키를 사용하는 모든 작업입니다. 인덱스 정의나 인덱서 상태와 같은 시스템 데이터 또는 개체 정의를 반환하는 모든 읽기 전용 작업에는 관리자 키가 필요합니다.
클라이언트 앱의 액세스 및 작업을 제한하는 것은 서비스의 검색 자산을 보호하는 데 필수적입니다. 클라이언트 앱에서 시작하는 모든 쿼리에 대해 항상 관리자 키 대신 쿼리 키를 사용하세요.
Azure Portal에 로그인하고 검색 서비스를 찾습니다.
설정에서 키를 선택하여 API 키를 봅니다.
쿼리 키 관리에서 서비스에 대해 이미 만들어진 쿼리 키를 사용하거나 새 쿼리 키를 만듭니다. 기본 쿼리 키에는 이름이 지정되지 않지만 관리 용이성을 위해 생성된 다른 쿼리 키에 이름을 지정할 수 있습니다.
관리자 키 다시 생성
두 개의 관리자 키는 비즈니스 연속성에 대한 보조 키를 사용하는 동안 기본 키를 회전할 수 있도록 각 서비스에 대해 생성됩니다.
설정에서 키를 선택한 다음 보조 키를 복사합니다.
모든 애플리케이션의 경우 보조 키를 사용하도록 API 키 설정을 업데이트합니다.
기본 키를 다시 생성합니다.
새 기본 키를 사용하도록 모든 애플리케이션을 업데이트합니다.
실수로 두 키를 동시에 다시 생성하면 해당 키를 사용하는 모든 클라이언트 요청이 HTTP 403 금지됨 오류와 함께 실패합니다. 그러나 콘텐츠는 삭제되지 않으며 영구적으로 잠기지 않습니다.
포털을 통해 또는 프로그래밍 방식으로 서비스에 계속 액세스할 수 있습니다. 관리 기능은 서비스 API 키가 아닌 구독 ID를 통해 작동하므로 가용 API 키가 없는 경우에도 계속 이용할 수 있습니다.
포털 또는 관리 계층을 통해 새 키를 만든 후 요청에 해당 키를 제공하면 콘텐츠(인덱스, 인덱서, 데이터 원본, 동의어 맵)에 대한 액세스가 복원됩니다.
API 키 보안
역할 할당을 사용하여 API 키에 대한 액세스를 제한합니다.
고객 관리형 키 암호화를 사용하여 API 키를 암호화하는 것은 불가능합니다. 검색 서비스 자체 내의 중요한 데이터(예: 데이터 원본 개체 정의의 인덱스 콘텐츠 또는 연결 문자열)만 CMK로 암호화할 수 있습니다.
Azure Portal의 검색 서비스 페이지로 이동합니다.
왼쪽 탐색 창에서 액세스 제어(IAM), 역할 할당 탭을 차례로 선택합니다.
역할 필터에서 키를 보거나 관리할 권한이 있는 역할(소유자, 기여자, 검색 서비스 기여자)을 선택합니다. 이러한 역할에 할당된 결과 보안 주체는 검색 서비스에 대한 주요 권한을 가집니다.
예방 조치로 클래식 관리자 탭을 확인하여 관리자와 공동 관리자에게 액세스 권한이 있는지 확인합니다.