키 없이 Azure AI 검색 사용

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

키 없는 연결은 다음 단계를 통해 사용하도록 설정됩니다.

• 인증을 구성합니다.
• 필요에 따라 환경 변수를 설정합니다.
• Azure ID 라이브러리 자격 증명 유형을 사용하여 Azure AI 검색 클라이언트 개체를 만듭니다.

필수 조건

로컬 개발 및 프로덕션 워크로드 모두에 대해 다음 단계를 완료해야 합니다.

• AI 검색 리소스 만들기
• 검색 서비스에서 역할 기반 액세스 사용
• Azure ID 클라이언트 라이브러리 설치

AI 검색 리소스 만들기

이 문서를 계속 진행하기 전에 작업할 Azure AI 검색 리소스가 필요합니다. 리소스가 없으면 지금 리소스를 만듭니다. 리소스에 대해 RBAC(역할 기반 액세스 제어)를 사용하도록 설정합니다.

Azure ID 클라이언트 라이브러리 설치

키 없는 연결이 없는 상태에서 로컬로 작업하기 전에 AI 검색 지원 코드를 Azure ID 클라이언트 라이브러리로 업데이트합니다.

.NET

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

dotnet add package Azure.Identity

Java

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

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.10.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

JavaScript

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

npm install --save @azure/identity

Python

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

pip install azure-identity

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

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

.NET

.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);

Java

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();

JavaScript

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
);

Python

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.windows.net"
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=index_name, 
    credential=credential, 
    audience=audience)

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

로컬 개발

키 없는 연결이 없는 상태의 로컬 개발에는 다음 단계가 포함됩니다.

• 특정 리소스에 대한 RBAC 역할로 개인 ID를 할당합니다.
• 도구를 사용하여 Azure에 인증합니다.
• 리소스에 대한 환경 변수를 설정합니다.

로컬 개발을 위한 역할

로컬 개발자로서 Azure ID는 서비스를 완전히 제어해야 합니다. 이 컨트롤은 RBAC 역할과 함께 제공됩니다. 개발 중에 리소스를 관리하기 위해 권장되는 역할은 다음과 같습니다.

• Search 서비스 참가자
• 검색 인덱스 데이터 기여자
• 검색 인덱스 데이터 읽기 권한자

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

Azure CLI

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

   az login
   

2. 개인 ID를 확인합니다.

   az ad signed-in-user show \
       --query id -o tsv
   

3. 리소스 그룹의 ID에 RBAC(역할 기반 액세스 제어) 역할을 할당합니다.

   az role assignment create \
       --role "<role-name>" \
       --assignee "<identity-id>" \
       --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"
   

Azure PowerShell

1. PowerShell을 사용하여 로그인합니다.

   Connect-AzAccount
   

2. 개인 ID를 확인합니다.

   (Get-AzContext).Account.ExtendedProperties.HomeAccountId.Split('.')[0]
   

3. 리소스 그룹의 ID에 RBAC(역할 기반 액세스 제어) 역할을 할당합니다.

   New-AzRoleAssignment -ObjectId "<identity-id>" -RoleDefinitionName "<role-name>" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"
   

Azure Portal

1. 여기에 있는 단계를 사용합니다. Azure Portal에서 사용자 개체 ID를 찾습니다.

2. Azure Portal에서 역할 할당 추가 페이지 열기에 있는 단계를 사용합니다.

해당하는 경우 <identity-id>, <subscription-id> 및 <resource-group-name>을 실제 값으로 바꿉니다.

로컬 개발을 위한 인증

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

.NET

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

Java

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

JavaScript

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

Python

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

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

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

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

프로덕션 워크로드

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

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

프로덕션 워크로드의 역할

프로덕션 리소스를 만들려면 사용자 지정 관리 ID를 만든 다음 해당 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입니다.

관련 콘텐츠

• 키 없는 연결 개발자 가이드
• Azure 기본 제공 역할
• 환경 변수 설정