Łączenie aplikacji z Wyszukiwanie AI platformy Azure przy użyciu tożsamości

W kodzie aplikacji można skonfigurować bez klucza połączenie z Wyszukiwanie AI platformy Azure, które używa Microsoft Entra ID i ról na potrzeby uwierzytelniania i autoryzacji. Żądania aplikacji do większości usług Azure muszą być uwierzytelniane za pomocą kluczy lub połączeń bez kluczy. Deweloperzy muszą być sumienni, aby nigdy nie ujawniać kluczy w niezabezpieczonej lokalizacji. Każdy, kto uzyskuje dostęp do klucza, może uwierzytelnić się w usłudze. Uwierzytelnianie bezkluczowe oferuje ulepszone korzyści w zakresie zarządzania i zabezpieczeń, ponieważ nie ma potrzeby przechowywania klucza (ani ciągu połączenia).

W tym artykule wyjaśniono, jak używać DefaultAzureCredential w kodzie aplikacji.

Aby zaimplementować połączenia bez kluczy w kodzie, wykonaj następujące kroki:

• Włączanie dostępu opartego na rolach w usłudze wyszukiwania
• Ustaw zmienne środowiskowe zgodnie z potrzebami.
• Użyj typu poświadczeń z biblioteki tożsamości Azure, aby utworzyć obiekt klienta Wyszukiwanie AI platformy Azure.

Wymagania wstępne

• Wyszukiwanie AI platformy Azure, dowolny region, ale musi to być płatna warstwa (podstawowa lub wyższa).

• Dostęp oparty na rolach włączony w usłudze wyszukiwania.

• Przypisania ról w Wyszukiwanie AI platformy Azure. Przypisz te role do swojej tożsamości:

  • Współautor usługi wyszukiwania i współautor danych indeksu wyszukiwania na potrzeby programowania lokalnego (pełny dostęp)
  • Czytnik danych indeksu wyszukiwania do produkcyjnych zapytań, które są tylko do odczytu

  Aby uzyskać instrukcje krok po kroku, zobacz Przypisywanie ról do programowania.

Instalowanie biblioteki klienta Azure Identity

Aby użyć podejścia bez klucza, zaktualizuj kod z włączoną funkcją wyszukiwania sztucznej inteligencji za pomocą biblioteki klienta Azure Identity.

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

Zaktualizuj kod źródłowy, aby używać DefaultAzureCredential.

Biblioteka Azure Identity DefaultAzureCredential umożliwia uruchamianie tego samego kodu w lokalnym środowisku projektowym i w chmurze Azure. Utwórz pojedyncze poświadczenie i ponownie skorzystaj z instancji poświadczenia w razie potrzeby, aby skorzystać z buforowania tokenów.

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)

Weryfikowanie połączenia

Po skonfigurowaniu klienta sprawdź połączenie, uruchamiając prostą operację. Poniższy przykład zawiera listę indeksów w usłudze wyszukiwania:

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

Udane połączenie wyświetla nazwy indeksów (lub pustą listę, jeśli nie istnieją żadne indeksy). Jeśli wystąpi błąd uwierzytelniania, sprawdź, czy dostęp oparty na rolach jest włączony, a Twoja tożsamość ma przypisane wymagane role.

Domyślnym urzędem jest Azure chmura publiczna. Niestandardowe audience wartości dla chmur suwerennych lub wyspecjalizowanych obejmują:

• https://search.azure.us dla Azure Government
• https://search.azure.cn dla Azure obsługiwanego przez firmę 21Vianet
• https://search.microsoftazure.de dla platformy Azure Germany

Rozwój lokalny

Programowanie lokalne przy użyciu ról obejmuje następujące kroki:

• Przypisz tożsamość osobistą do ról RBAC w określonym zasobie.
• Użyj narzędzia, takiego jak Azure CLI lub Azure PowerShell, aby uwierzytelnić się za pomocą Azure.
• Ustaw zmienne środowiskowe dla zasobu.

Role na potrzeby rozwoju lokalnego

Jako lokalny deweloper, Twoja tożsamość Azure musi mieć pełną kontrolę nad operacjami płaszczyzny danych. Są to sugerowane role:

• Współautor usługi wyszukiwania, tworzenie obiektów i zarządzanie nimi
• Współautor danych indeksu wyszukiwania, ładowanie i wykonywanie zapytań względem indeksu oraz pobieranie ich z bazy wiedzy

Znajdź swoją tożsamość osobistą przy użyciu jednego z następujących narzędzi. Użyj tej tożsamości jako <identity-id> wartości.

Uwierzytelnianie na potrzeby programowania lokalnego

Użyj narzędzia w lokalnym środowisku projektowym do uwierzytelniania względem tożsamości Azure. Gdy jesteś uwierzytelniony, wystąpienie DefaultAzureCredential w kodzie źródłowym znajduje i używa Twojej tożsamości do celów uwierzytelniania.

Wybierz narzędzie do uwierzytelniania podczas programowania lokalnego.

Konfigurowanie zmiennych środowiskowych na potrzeby programowania lokalnego

Aby nawiązać połączenie z Wyszukiwanie AI platformy Azure, kod musi znać punkt końcowy zasobu.

Utwórz zmienną środowiskową o nazwie AZURE_SEARCH_ENDPOINT dla punktu końcowego Wyszukiwanie AI platformy Azure. Ten adres URL ma zazwyczaj format https://<YOUR-RESOURCE-NAME>.search.windows.net/.

Obciążenia produkcyjne

Wdrażanie obciążeń produkcyjnych obejmuje następujące kroki:

• Wybierz role RBAC, które są zgodne z zasadą minimalnych uprawnień.
• Przypisz role RBAC do tożsamości produkcyjnej dla określonego zasobu.
• Skonfiguruj zmienne środowiskowe dla zasobu.

Role dla obciążeń produkcyjnych

Aby utworzyć zasoby produkcyjne, należy utworzyć tożsamość zarządzaną przypisaną przez użytkownika , a następnie przypisać jej tożsamość do zasobów przy użyciu odpowiednich ról.

W przypadku aplikacji produkcyjnej sugerowana jest następująca rola:

Uwierzytelnianie dla obciążeń produkcyjnych

Użyj następującego szablonu Wyszukiwanie AI platformy Azure Bicep, aby utworzyć zasób i aby ustawić uwierzytelnianie dla identityId. Bicep wymaga identyfikatora roli. name pokazany w tym fragmencie kodu Bicep nie jest rolą Azure; jest specyficzna dla wdrożenia 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
    }
}

Plik main.bicep wywołuje następujący ogólny kod Bicep, aby utworzyć dowolną rolę. Istnieje możliwość utworzenia wielu ról RBAC, takich jak jedna dla użytkownika, a druga dla środowiska produkcyjnego. Umożliwia to włączenie zarówno środowisk deweloperskich, jak i produkcyjnych w ramach tego samego wdrożenia 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)
    }
}

Konfigurowanie zmiennych środowiskowych dla obciążeń produkcyjnych

Aby nawiązać połączenie z Wyszukiwanie AI platformy Azure, kod musi znać punkt końcowy zasobu i identyfikator tożsamości zarządzanej.

Utwórz zmienne środowiskowe dla wdrożonego i bez klucza zasobu Wyszukiwanie AI platformy Azure:

• AZURE_SEARCH_ENDPOINT: ten adres URL jest punktem dostępu dla zasobu Wyszukiwanie AI platformy Azure. Ten adres URL ma zazwyczaj format https://<YOUR-RESOURCE-NAME>.search.windows.net/.
• AZURE_CLIENT_ID: To jest tożsamość używana do uwierzytelniania.

Rozwiązywanie typowych błędów

Treści powiązane

• Przewodnik dewelopera dotyczący połączeń bez kluczy
• Role wbudowane w Azure
• Ustawianie zmiennych środowiskowych