Připojení aplikace k Azure AI Vyhledávač pomocí identit

V kódu aplikace můžete nastavit připojení bez klíčů na Azure AI Vyhledávač, které k ověřování a autorizaci používá Microsoft Entra ID a role. Žádosti aplikací na většinu Azure služeb musí být ověřeny pomocí klíčů nebo bez klíčů připojení. Vývojáři musí být usilovní, aby klíče nikdy nezpřístupnili v nezabezpečeném umístění. Každý, kdo získá přístup ke klíči, se může ověřit ve službě. Ověřování bez klíčů nabízí lepší výhody správy a zabezpečení u klíče účtu, protože neexistuje žádný klíč (nebo připojovací řetězec) pro ukládání.

Tento článek vysvětluje, jak se používá DefaultAzureCredential v kódu aplikace.

Pokud chcete do kódu implementovat bezklíčová připojení, postupujte takto:

• Povolení přístupu na základě role ve vyhledávací službě
• Podle potřeby nastavte proměnné prostředí.
• Pomocí typu přihlašovacích údajů knihovny identit Azure vytvořte objekt klienta Azure AI Vyhledávač.

Požadavky

• Azure AI Vyhledávač, každá oblast, ale musí to být fakturovatelná úroveň (Basic nebo vyšší).

• Ve vyhledávací službě je povolený přístup založený na rolích .

• Přiřazení rolí v Azure AI Vyhledávač Přiřaďte k identitě tyto role:

  • Přispěvatel vyhledávací služby a Přispěvatel dat indexu vyhledávání pro místní vývoj (úplný přístup)
  • Čtenář dat indexu vyhledávání pro produkční dotazy pouze ke čtení

  Podrobné pokyny najdete v tématu Přiřazení rolí pro vývoj.

Instalace klientské knihovny Azure Identity

Pokud chcete použít bezklíčový přístup, aktualizujte kód s povoleným vyhledáváním AI pomocí klientské knihovny 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

Aktualizace zdrojového kódu tak, aby používal DefaultAzureCredential

Knihovna identit Azure identity DefaultAzureCredential umožňuje spustit stejný kód v místním vývojovém prostředí a v cloudu Azure. Vytvořte jednu přihlašovací údaje a podle potřeby znovu použijte instanci přihlašovacích údajů, abyste mohli využívat ukládání tokenů do mezipaměti.

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)

Ověření připojení

Po nastavení klienta ověřte připojení spuštěním jednoduché operace. Následující příklad uvádí indexy ve vyhledávací službě:

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

Úspěšné připojení vytiskne názvy indexů (nebo prázdný seznam, pokud neexistují žádné indexy). Pokud se zobrazí chyba ověřování, ověřte, že je povolený přístup na základě role a že vaše identita má požadovaná přiřazení rolí.

Výchozí autorita je Azure Public Cloud. Vlastní hodnoty audience pro suverénní nebo specializované cloudy zahrnují:

• https://search.azure.us pro Azure Government
• https://search.azure.cn pro Azure provozovaný společností 21Vianet
• https://search.microsoftazure.de pro Azure (Německo)

Místní vývoj

Místní vývoj pomocí rolí zahrnuje tyto kroky:

• Přiřaďte svou osobní identitu k rolím RBAC pro konkrétní prostředek.
• K ověření pomocí Azure použijte nástroj, jako je Azure CLI nebo Azure PowerShell.
• Vytvořte proměnné prostředí pro váš prostředek.

Role pro místní vývoj

Jako místní vývojář potřebuje vaše Azure identita úplnou kontrolu nad operacemi roviny dat. Toto jsou navrhované role:

• Přispěvatel vyhledávací služby, vytváření a správa objektů
• Přispěvatel údajů do indexu vyhledávání, načtení a dotazování se na index a vyhledání ze znalostní báze

Najděte svou osobní identitu pomocí jednoho z následujících nástrojů. Tuto identitu použijte jako <identity-id> hodnotu.

Ověřování pro lokální vývoj

K ověřování Azure identity použijte nástroj v místním vývojovém prostředí. Po ověření DefaultAzureCredential instance ve zdrojovém kódu vyhledá a použije vaši identitu pro účely ověřování.

Vyberte nástroj pro ověřování během místního vývoje.

Konfigurace proměnných prostředí pro místní vývoj

Pokud se chcete připojit k Azure AI Vyhledávač, je třeba, aby váš kód znal koncový bod prostředku.

Vytvořte proměnnou prostředí s názvem AZURE_SEARCH_ENDPOINT pro koncový bod Azure AI Vyhledávač. Tato adresa URL má obecně formát https://<YOUR-RESOURCE-NAME>.search.windows.net/.

Produkční úlohy

Nasazení produkčních úloh zahrnuje tyto kroky:

• Zvolte role RBAC, které se řídí principem nejnižšího oprávnění.
• Přiřaďte role RBAC k produkční identitě pro konkrétní prostředek.
• Nastavte proměnné prostředí pro váš zdroj.

Role pro produkční úlohy

Pokud chcete vytvořit produkční prostředky, musíte vytvořit spravovanou identitu přiřazenou uživatelem a pak ji přiřadit k prostředkům se správnými rolemi.

Pro produkční aplikaci se navrhuje následující role:

Ověřování pro produkční úlohy

Pomocí následující šablony služby Azure AI Vyhledávač Bicep vytvořte prostředek a nastavte ověřování pro identityId. Pro Bicep je nutné ID role. name zobrazený v tomto fragmentu kódu Bicep není rolí Azure; je specifický pro nasazení 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
    }
}

Soubor main.bicep volá následující obecný Bicep kód pro vytváření rolí. Máte možnost vytvořit několik rolí RBAC, jako je jeden pro uživatele a druhý pro produkční prostředí. To vám umožní aktivovat jak vývojová, tak produkční prostředí v rámci stejného nasazení pomocí 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)
    }
}

Konfigurace proměnných prostředí pro produkční úlohy

Pokud se chcete připojit k Azure AI Vyhledávač, váš kód musí znát koncový bod prostředku a ID spravované identity.

Vytvořte proměnné prostředí pro nasazené prostředí Azure AI Vyhledávač bez použití klíčů.

• AZURE_SEARCH_ENDPOINT: Tato adresa URL je přístupovým bodem vašeho prostředku Azure AI Vyhledávač. Tato adresa URL má obecně formát https://<YOUR-RESOURCE-NAME>.search.windows.net/.
• AZURE_CLIENT_ID: Toto je identita, pod kterou se má ověřit.

Řešení běžných chyb

Související obsah

• Příručka pro vývojáře bezklíčového připojení
• Azure předdefinované role
• Nastavení proměnných prostředí