ID를 사용하여 Azure AI 검색에 앱 연결

애플리케이션 코드에서 인증 및 권한 부여를 위해 Microsoft Entra ID와 역할을 사용하는 Azure AI 검색에 대한 키 없는 연결을 설정할 수 있습니다. 대부분의 Azure 서비스에 대한 애플리케이션 요청은 키 또는 키 없는 연결을 통해 인증되어야 합니다. 개발자는 키를 안전하지 않은 위치에 노출하지 않도록 끊임없이 노력해야 합니다. 키에 접근할 수 있는 사람은 누구나 서비스에 인증할 수 있습니다. 키 없는 인증은 키(또는 연결 문자열)를 저장할 필요가 없기 때문에 계정 키보다 향상된 관리 및 보안 이점을 제공합니다.

이 문서에서는 애플리케이션 코드에서 사용하는 DefaultAzureCredential 방법을 설명합니다.

코드에서 키 없는 연결을 구현하려면 다음 단계를 수행합니다.

검색 서비스에서 역할 기반 액세스 사용
필요에 따라 환경 변수를 설정하십시오.
Azure ID 라이브러리 자격 증명 유형을 사용하여 Azure AI 검색 클라이언트 개체를 만듭니다.

필수 조건

Azure AI Search는 모든 지역이지만 청구 가능한 계층(기본 이상)이어야 합니다.
검색 서비스에 역할 기반 액세스가 활성화되었습니다.
Azure AI Search의 역할 할당 ID에 다음 역할을 할당합니다.
- 로컬 개발을 위한 Search Service 기여자 및 검색 인덱스 데이터 기여자(모든 권한)
- 프로덕션 읽기 전용 쿼리에 대한 인덱스 데이터 판독기 검색
단계별 지침은 개발을 위한 역할 할당을 참조하세요.

Azure Identity 클라이언트 라이브러리를 설치하십시오.

키 없는 방식을 사용하려면 Azure ID 클라이언트 라이브러리를 사용하여 AI 검색 사용 코드를 업데이트합니다.

.NET용 Azure ID 클라이언트 라이브러리 및 Azure Search 문서 클라이언트 라이브러리를 설치합니다.

dotnet add package Azure.Identity
dotnet add package Azure.Search.Documents

다음 POM 파일을 사용하여 Java용 Azure ID 클라이언트 라이브러리 및 Azure Search 문서 클라이언트 라이브러리 를 설치합니다.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.15.1</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-search-documents</artifactId>
            <version>11.7.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

JavaScript용 Azure ID 클라이언트 라이브러리 및 Azure Search 문서 클라이언트 라이브러리를 설치합니다.

npm install --save @azure/identity @azure/search-documents

Python용 Azure ID 클라이언트 라이브러리 및 Azure Search 문서 클라이언트 라이브러리를 설치합니다.

pip install azure-identity azure-search-documents

DefaultAzureCredential을 사용하도록 소스 코드 업데이트

Azure ID 라이브러리의 DefaultAzureCredential을 사용하면 로컬 개발 환경과 Azure 클라우드에서 동일한 코드를 실행할 수 있습니다. 토큰 캐싱을 활용하려면 단일 자격 증명을 만들고 필요에 따라 자격 증명 인스턴스를 다시 사용합니다.

.NET용 DefaultAzureCredential에 대한 자세한 내용은 .NET용 Azure ID 클라이언트 라이브러리를 참조하세요.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;
using System;
using static System.Environment;

string endpoint = GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT");
string indexName = "my-search-index";

DefaultAzureCredential credential = new();
SearchClient searchClient = new(new Uri(endpoint), indexName, credential);
SearchIndexClient searchIndexClient = new(endpoint, credential);

참조:SearchClient, SearchIndexClient, DefaultAzureCredential

Java용 DefaultAzureCredential에 대한 자세한 내용은 Java용 Azure ID 클라이언트 라이브러리를 참조하세요.

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.search.documents.SearchAsyncClient;
import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.indexes.SearchIndexAsyncClient;
import com.azure.search.documents.indexes.SearchIndexClientBuilder;

String ENDPOINT = System.getenv("AZURE_SEARCH_ENDPOINT");
String INDEX_NAME = "my-index";

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

// Sync SearchClient
SearchClient searchClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildClient();

// Sync IndexClient
SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildClient();

// Async SearchClient
SearchAsyncClient searchAsyncClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildAsyncClient();

// Async IndexClient
SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildAsyncClient();

참조:SearchClient, SearchIndexClient, DefaultAzureCredential

JavaScript용 DefaultAzureCredential에 대한 자세한 내용은 JavaScript용 Azure ID 클라이언트 라이브러리를 참조하세요.

import { DefaultAzureCredential } from "@azure/identity";
import {
  SearchClient,
  SearchIndexClient
} from "@azure/search-documents";

const AZURE_SEARCH_ENDPOINT = process.env.AZURE_SEARCH_ENDPOINT;
const index = "my-index";
const credential = new DefaultAzureCredential();

// To query and manipulate documents
const searchClient = new SearchClient(
  AZURE_SEARCH_ENDPOINT,
  index,
  credential
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient(
  AZURE_SEARCH_ENDPOINT, 
  credential
);

참조:SearchClient, SearchIndexClient, DefaultAzureCredential

Python용 DefaultAzureCredential에 대한 자세한 내용은 Python용 Azure ID 클라이언트 라이브러리를 참조하세요.

import os
from azure.search.documents import SearchClient
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Azure Public Cloud
audience = "https://search.azure.com"
authority = AzureAuthorityHosts.AZURE_PUBLIC_CLOUD

service_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
credential = DefaultAzureCredential(authority=authority)

search_client = SearchClient(
    endpoint=service_endpoint, 
    index_name=index_name, 
    credential=credential, 
    audience=audience)

search_index_client = SearchIndexClient(
    endpoint=service_endpoint, 
    credential=credential, 
    audience=audience)

참조:SearchClient, SearchIndexClient, DefaultAzureCredential

연결 확인

클라이언트를 설정한 후 간단한 작업을 실행하여 연결을 확인합니다. 다음 예제에서는 검색 서비스의 인덱스를 나열합니다.

// List indexes to verify connection
var indexes = searchIndexClient.GetIndexNames();
foreach (var name in indexes)
{
    Console.WriteLine(name);
}

// List indexes to verify connection
searchIndexClient.listIndexNames().forEach(System.out::println);

// List indexes to verify connection
for await (const name of indexClient.listIndexesNames()) {
  console.log(name);
}

# List indexes to verify connection
for index in search_index_client.list_index_names():
    print(index)

연결에 성공하면 인덱스의 이름이 인쇄됩니다(또는 인덱스가 없는 경우 빈 목록). 인증 오류가 발생하는 경우 역할 기반 액세스가 활성화되어 있고 ID에 필요한 역할 할당이 있는지 확인합니다.

기본 기관은 Azure 퍼블릭 클라우드입니다. 소버린 또는 특수 클라우드에 대한 사용자 지정 audience 값은 다음과 같습니다.

Azure Government을 위한 https://search.azure.us
https://search.azure.cn 21Vianet에서 운영하는 Azure의 경우
https://search.microsoftazure.de(Azure 독일의 경우)

로컬 개발

역할을 사용한 로컬 개발에는 다음 단계가 포함됩니다.

특정 리소스에 대한 RBAC 역할에 개인 ID를 할당합니다.
Azure CLI 또는 Azure PowerShell과 같은 도구를 사용하여 Azure에 인증합니다.
리소스에 대한 환경 변수를 설정합니다.

로컬 개발을 위한 역할

로컬 개발자로서 Azure ID가 데이터 평면 작업을 완전히 제어해야 합니다. 제안된 역할은 다음과 같습니다.

서비스 기여자 검색, 개체 만들기 및 관리
인덱스 데이터 기여자 검색, 인덱스 로드 및 쿼리

다음 도구 중 하나를 사용하여 개인 ID를 찾습니다. 해당 ID를 <identity-id> 값으로 사용합니다.

자리 표시자 <role-name>, <identity-id>, <subscription-id>, 및 <resource-group-name>를 다음 명령에서 실제 값으로 바꿉니다.

Azure CLI에 로그인합니다.
```
az login
```
인증을 위한 브라우저 창이 열립니다. 로그인에 성공하면 터미널에 구독 정보가 표시됩니다.
개인 ID를 확인합니다.
```
az ad signed-in-user show \
    --query id -o tsv
```
이 명령은 사용자 개체 ID(GUID)를 반환합니다. 다음 단계를 위해 이 값을 저장하십시오.
리소스 그룹에 대한 역할 기반 액세스 제어(RBAC) 역할을 해당 ID에 할당하십시오.
```
az role assignment create \
    --role "<role-name>" \
    --assignee "<identity-id>" \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"
```
성공적인 할당은 역할 할당 세부 정보가 포함된 JSON 개체를 반환합니다.

자리 표시자 <role-name>, <identity-id>, <subscription-id>, <resource-group-name>를 다음 명령의 실제 값으로 바꾸십시오.

PowerShell을 사용하여 로그인합니다.
```
Connect-AzAccount
```
인증을 위한 브라우저 창이 열립니다. 로그인에 성공하면 터미널에 계정 및 구독 정보가 표시됩니다.
개인 ID를 확인합니다.
```
(Get-AzContext).Account.ExtendedProperties.HomeAccountId.Split('.')[0]
```
이 명령은 사용자 개체 ID(GUID)를 반환합니다. 다음 단계를 위해 이 값을 저장하십시오.
리소스 그룹에 대한 역할 기반 액세스 제어(RBAC) 역할을 해당 ID에 할당하십시오.
```
New-AzRoleAssignment -ObjectId "<identity-id>" -RoleDefinitionName "<role-name>" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"
```
성공적인 할당은 다음을 비롯한 세부 정보가 포함된 역할 할당 개체를 반환합니다 RoleAssignmentId.

로컬 개발을 위한 인증

로컬 개발 환경의 도구를 사용하여 Azure ID에 인증합니다. 인증되면 소스 코드의 DefaultAzureCredential 인스턴스가 본인의 ID를 찾아 인증 용도로 사용합니다.

로컬 개발 중 인증을 위한 도구를 선택합니다.

로컬 개발을 위한 환경 변수 구성

Azure AI 검색에 연결하려면 코드에서 리소스 엔드포인트를 알아야 합니다.

Azure AI 검색 엔드포인트에 대해 AZURE_SEARCH_ENDPOINT라는 환경 변수를 만듭니다. 이 URL은 일반적으로 https://<YOUR-RESOURCE-NAME>.search.windows.net/ 형식을 갖습니다.

프로덕션 워크로드

프로덕션 워크로드 배포에는 다음 단계가 포함됩니다.

최소 권한 원칙을 준수하는 RBAC 역할을 선택합니다.
특정 리소스의 프로덕션 ID에 RBAC 역할을 할당합니다.
리소스에 대한 환경 변수를 설정합니다.

프로덕션 워크로드의 역할

프로덕션 리소스를 만들려면 사용자 지정 관리 ID를 만든 다음 해당 ID를 올바른 역할을 사용하여 리소스에 할당해야 합니다.

프로덕션 애플리케이션에는 다음 역할이 제안됩니다.

역할 이름	아이디
검색 인덱스 데이터 리더	1407120a-92aa-4202-b7e9-c0e197c71c8f

프로덕션 워크로드에 대한 인증

다음 Azure AI 검색 Bicep 템플릿을 사용하여 리소스를 만들고 identityId에 대한 인증을 설정합니다. Bicep는 역할 ID를 필요로 합니다. 이 Bicep 코드 조각에 표시된 name은 Azure 역할이 아닙니다. 이는 Bicep 배포에만 해당됩니다.

// main.bicep
param environment string = 'production'
param roleGuid string = ''

module aiSearchRoleUser 'core/security/role.bicep' = {
    scope: aiSearchResourceGroup
    name: 'aiSearch-role-user'
    params: {
        principalId: (environment == 'development') ? principalId : userAssignedManagedIdentity.properties.principalId 
        principalType: (environment == 'development') ? 'User' : 'ServicePrincipal'
        roleDefinitionId: roleGuid
    }
}

main.bicep 파일은 다음 제네릭 Bicep 코드를 호출하여 역할을 만듭니다. 사용자용 역할과 프로덕션용 역할 등 여러 RBAC 역할을 만들 수 있는 옵션이 있습니다. 이를 통해 동일한 Bicep 배포 내에서 개발 및 프로덕션 환경을 모두 사용하도록 설정할 수 있습니다.

// core/security/role.bicep
metadata description = 'Creates a role assignment for an identity.'
param principalId string // passed in from main.bicep

@allowed([
    'Device'
    'ForeignGroup'
    'Group'
    'ServicePrincipal'
    'User'
])
param principalType string = 'ServicePrincipal'
param roleDefinitionId string // Role ID

resource role 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    name: guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)
    properties: {
        principalId: principalId
        principalType: principalType
        roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    }
}

프로덕션 워크로드에 대한 환경 변수 구성

Azure AI 검색에 연결하려면 코드에서 리소스 엔드포인트와 관리 ID의 ID를 알아야 합니다.

배포되고 키 없는 Azure AI 검색 리소스에 대한 환경 변수를 만듭니다.

AZURE_SEARCH_ENDPOINT: 이 URL은 Azure AI 검색 리소스에 대한 액세스 지점입니다. 이 URL은 일반적으로 https://<YOUR-RESOURCE-NAME>.search.windows.net/ 형식을 갖습니다.
AZURE_CLIENT_ID: 인증할 ID입니다.

일반적인 오류 해결 방법

오류	원인	해결 방법
`AuthenticationFailedException`	자격 증명이 없거나 잘못되었습니다.	`az login`(CLI) 또는 `Connect-AzAccount`(PowerShell)로 로그인되어 있는지 확인합니다. Azure 계정에 구독에 대한 액세스 권한이 있는지 확인합니다.
`403 Forbidden`	ID에 필요한 역할이 없습니다.	적절한 역할을 할당합니다(쿼리에 대한 인덱스 데이터 판독기 검색, 인덱싱을 위한 인덱스 데이터 기여자 검색). 역할 할당이 전파되는 데 최대 10분이 걸릴 수 있습니다.
`401 Unauthorized`	검색 서비스에서 RBAC를 사용할 수 없음	설정키> 역할 기반 액세스 제어 아래의 Azure Portal에서역할 기반 액세스를 사용하도록 >.
`ResourceNotFoundException`	잘못된 엔드포인트 또는 인덱스 이름	환경 변수가 `AZURE_SEARCH_ENDPOINT` 검색 서비스 URL(형식: `https://<service-name>.search.windows.net`)과 일치하는지 확인합니다.
`CredentialUnavailableException`	유효한 자격 증명을 찾을 수 없음	`DefaultAzureCredential` 는 여러 인증 방법을 시도합니다. 하나 이상의 구성되었는지 확인합니다(Azure CLI, Visual Studio, 환경 변수).

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-01-23

다음을 통해 공유

ID를 사용하여 Azure AI 검색에 앱 연결

필수 조건

Azure Identity 클라이언트 라이브러리를 설치하십시오.

DefaultAzureCredential을 사용하도록 소스 코드 업데이트

연결 확인

로컬 개발

로컬 개발을 위한 역할

로컬 개발을 위한 인증

로컬 개발을 위한 환경 변수 구성

프로덕션 워크로드

프로덕션 워크로드의 역할

프로덕션 워크로드에 대한 인증

프로덕션 워크로드에 대한 환경 변수 구성

일반적인 오류 해결 방법

관련 콘텐츠

피드백

추가 리소스