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

아티클
11/09/2024

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

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

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

필수 조건

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

AI 검색 리소스 만들기

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

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

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

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

dotnet add package Azure.Identity

다음 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용 Azure ID 클라이언트 라이브러리를 설치합니다.

npm install --save @azure/identity

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

pip install azure-identity

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

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용 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용 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 CLI 또는 Azure PowerShell과 같은 도구를 사용하여 Azure로 인증합니다.
리소스에 대한 환경 변수를 설정합니다.

로컬 개발을 위한 역할

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

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

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

Azure CLI에 로그인합니다.
```
az login
```

개인 ID를 확인합니다.

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

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

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

PowerShell을 사용하여 로그인합니다.
```
Connect-AzAccount
```

개인 ID를 확인합니다.

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

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

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

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

로컬 개발을 위한 인증

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

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

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

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입니다.

다음을 통해 공유

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

필수 조건

AI 검색 리소스 만들기

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

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

로컬 개발

로컬 개발을 위한 역할

로컬 개발을 위한 인증

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

프로덕션 워크로드

프로덕션 워크로드의 역할

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

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

피드백

추가 리소스

다음을 통해 공유

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

필수 조건

AI 검색 리소스 만들기

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

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

로컬 개발

로컬 개발을 위한 역할

로컬 개발을 위한 인증

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

프로덕션 워크로드

프로덕션 워크로드의 역할

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

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

관련 콘텐츠

피드백

추가 리소스