Подключение приложения к Поиск с использованием ИИ Azure с помощью идентификаций

В коде приложения можно настроить подключение без ключа к Поиск с использованием ИИ Azure, использующее Microsoft Entra ID и роли для проверки подлинности и авторизации. Запросы приложений к большинству служб Azure должны проходить проверку подлинности с помощью ключей или бессерверных подключений. Разработчики должны уделять внимание тому, чтобы не раскрыть ключи в незащищенном расположении. Любой, кто получает доступ к ключу, может пройти проверку подлинности в службе. Аутентификация без использования ключей обеспечивает улучшенные возможности управления и безопасности по сравнению с ключом доступа к учетной записи, так как для хранения ключа (или строки подключения) нет необходимости.

В этой статье объясняется, как использовать DefaultAzureCredential в коде приложения.

Чтобы реализовать бессерверные подключения в коде, выполните следующие действия.

• Включение доступа на основе ролей в службе поиска
• При необходимости задайте переменные среды.
• Используйте тип учетных данных библиотеки удостоверений Azure для создания объекта клиента Поиск с использованием ИИ Azure.

Предпосылки

• Поиск с использованием ИИ Azure, любой регион, но он должен быть платным (базовым или более высоким).

• Доступ на основе ролей включен в службе поиска.

• Назначения ролей в Поиск с использованием ИИ Azure. Назначьте эти роли вашей учетной записи.

  • Участник службы поиска и участник данных индекса поиска для локальной разработки (полный доступ)
  • Модуль чтения данных индекса поиска для рабочих запросов на только чтение

  Пошаговые инструкции см. в разделе "Назначение ролей для разработки".

Установка клиентской библиотеки удостоверений Azure

Чтобы использовать безключевой подход, обновите код с поддержкой поиска, включенного ИИ, с помощью клиентской библиотеки удостоверений Azure.

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

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

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

pip install azure-identity azure-search-documents

Обновление исходного кода для использования DefaultAzureCredential

Библиотека идентификации Azure DefaultAzureCredential позволяет выполнять один и тот же код как в локальной среде разработки, так и в облаке Azure. Создайте единые учетные данные и повторно используйте экземпляр этих данных по мере необходимости, чтобы воспользоваться преимуществами кеширования токенов.

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

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

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

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)

Проверка подключения

После настройки клиента проверьте подключение, выполнив простую операцию. В следующем примере перечислены индексы в службе поиска:

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

Успешное подключение выводит имена индексов (или пустой список, если индексы отсутствуют). Если вы сталкиваетесь с ошибкой аутентификации, убедитесь, что доступ на основе ролей активирован, а идентификация имеет необходимые назначения ролей.

Авторитет по умолчанию — это общедоступное облако Azure. К пользовательским audience значениям для национальных или специализированных облаков относятся:

• https://search.azure.us для Azure для государственных организаций
• https://search.azure.cn для Azure, управляемого 21Vianet
• https://search.microsoftazure.de для Azure для Германии

Локальная разработка

Локальная разработка с помощью ролей включает следующие действия.

• Назначьте личную учетную запись ролям RBAC на конкретном ресурсе.
• Используйте средство, например Azure CLI или Azure PowerShell для проверки подлинности с помощью Azure.
• Установите переменные среды для ресурса.

Роли для локальной разработки

Как локальный разработчик, ваше Azure удостоверение нуждается в полном контроле над операциями плоскости данных. Ниже приведены предлагаемые роли:

• Участник службы поиска, создание объектов и управление ими
• Участник данных индекса поиска: загрузка, запрос индекса и извлечение из базы знаний

Найдите свое личное удостоверение с помощью одного из следующих средств. Используйте это удостоверение в качестве значения <identity-id>.

Проверка подлинности для локальной разработки

Используйте средство в локальной среде разработки для аутентификации с удостоверением Azure. После того как вы прошли проверку подлинности, экземпляр DefaultAzureCredential в вашем исходном коде находит и использует ваше удостоверение для целей аутентификации.

Выберите средство для проверки подлинности во время локальной разработки.

Настройка переменных среды для локальной разработки

Чтобы подключиться к Поиск с использованием ИИ Azure, коду необходимо знать конечную точку ресурса.

Создайте переменную среды с именем AZURE_SEARCH_ENDPOINT для конечной точки Поиск с использованием ИИ Azure. Этот URL-адрес обычно имеет формат https://<YOUR-RESOURCE-NAME>.search.windows.net/.

Нагрузки в производственной среде

Развертывание рабочих нагрузок включает следующие действия.

• Выберите роли RBAC, которые соответствуют принципу наименьших привилегий.
• Назначьте роли RBAC для производственной учётной записи на конкретном ресурсе.
• Настройте переменные среды для ресурса.

Роли для производственных рабочих нагрузок

Чтобы создать производственные ресурсы, необходимо создать управляемое удостоверение, назначенное пользователем, а затем назначить это удостоверение ресурсам с правильными ролями.

Для рабочего приложения предлагается следующая роль:

Проверка подлинности для рабочих нагрузок в производственной среде

Используйте следующий шаблон Поиск с использованием ИИ Azure Bicep для создания ресурса и задания проверки подлинности для identityId. Bicep нуждается в идентификаторе роли. Фрагмент кода name, показанный в этом фрагменте Bicep, не является ролью 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, коду нужно указать конечную точку ресурса и идентификатор управляемой идентичности.

Создайте переменные среды для развернутого и бессерверного ресурса Поиск с использованием ИИ Azure:

• AZURE_SEARCH_ENDPOINT. Этот URL-адрес является точкой доступа для ресурса Поиск с использованием ИИ Azure. Этот URL-адрес обычно имеет формат https://<YOUR-RESOURCE-NAME>.search.windows.net/.
• AZURE_CLIENT_ID: это удостоверение для проверки подлинности как.

Устранение распространенных ошибок

Связанный контент

• Руководство разработчика по безключевым подключениям
• Встроенные роли Azure
• Настройка переменных среды