Uw app verbinden met Azure AI Search met behulp van identiteiten

In uw toepassingscode kunt u een sleutelloze verbinding met Azure AI Search instellen die gebruikmaakt van Microsoft Entra-id en -rollen voor verificatie en autorisatie. Toepassingsaanvragen voor de meeste Azure-services moeten worden geverifieerd met sleutels of sleutelloze verbindingen. Ontwikkelaars moeten ijverig zijn om de sleutels nooit beschikbaar te maken op een onbeveiligde locatie. Iedereen die toegang krijgt tot de sleutel, kan zich verifiëren bij de service. Sleutelloze verificatie biedt verbeterde beheer- en beveiligingsvoordelen ten opzichte van de accountsleutel, omdat er geen sleutel (of verbindingsreeks) is om op te slaan.

In dit artikel wordt uitgelegd hoe u deze kunt gebruiken DefaultAzureCredential in uw toepassingscode.

Voer de volgende stappen uit om sleutelloze verbindingen in uw code te implementeren:

• Op rollen gebaseerde toegang inschakelen voor uw zoekservice
• Stel indien nodig omgevingsvariabelen in.
• Gebruik een referentietype van de Azure Identity-bibliotheek om een Azure AI Search-clientobject te maken.

Vereiste voorwaarden

• Azure AI Search, elke regio, maar moet een factureerbare laag zijn (basic of hoger).

• Op rollen gebaseerde toegang ingeschakeld voor uw zoekservice.

• Roltoewijzingen in Azure AI Search. Wijs deze rollen toe aan uw identiteit:

  • Inzender voor zoekservice en inzender voor zoekindexgegevens voor lokale ontwikkeling (volledige toegang)
  • Search Index Data Reader voor productiequery's met het kenmerk Alleen-lezen

  Zie Rollen toewijzen voor ontwikkeling voor stapsgewijze instructies.

Azure Identity-clientbibliotheek installeren

Als u een sleutelloze benadering wilt gebruiken, werkt u uw code met AI Search bij met de Azure Identity-clientbibliotheek.

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

Broncode bijwerken voor gebruik van DefaultAzureCredential

Met de Azure Identity-bibliotheek DefaultAzureCredential kunt u dezelfde code uitvoeren in de lokale ontwikkelomgeving en in de Azure-cloud. Maak één referentie en hergebruik het referentie-exemplaar indien nodig om gebruik te maken van tokencaching.

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)

Uw verbinding controleren

Nadat u de client hebt ingesteld, controleert u de verbinding door een eenvoudige bewerking uit te voeren. In het volgende voorbeeld ziet u indexen voor uw zoekservice:

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

Met een geslaagde verbinding worden de namen van uw indexen afgedrukt (of een lege lijst als er geen indexen bestaan). Als u een verificatiefout ontvangt, controleert u of op rollen gebaseerde toegang is ingeschakeld en of uw identiteit de vereiste roltoewijzingen heeft.

De standaardinstantie is de publieke Azure-cloud. Aangepaste audience waarden voor onafhankelijke of gespecialiseerde clouds zijn onder andere:

• https://search.azure.us voor Azure Government
• https://search.azure.cn voor Azure beheerd door 21Vianet
• https://search.microsoftazure.de voor Azure Duitsland

Lokale ontwikkeling

Lokale ontwikkeling met behulp van rollen omvat de volgende stappen:

• Wijs uw persoonlijke identiteit toe aan RBAC-rollen voor de specifieke resource.
• Gebruik een hulpprogramma zoals de Azure CLI of Azure PowerShell om te verifiëren met Azure.
• Stel omgevingsvariabelen voor uw resource in.

Rollen voor lokale ontwikkeling

Als lokale ontwikkelaar heeft uw Azure-identiteit volledige controle nodig over gegevensvlakbewerkingen. Dit zijn de voorgestelde rollen:

• Inzender voor zoekservice, objecten maken en beheren
• Inzender voor zoekindexgegevens, een index laden en er query's op uitvoeren

Zoek uw persoonlijke identiteit met een van de volgende hulpprogramma's. Gebruik die identiteit als de <identity-id> waarde.

Authenticatie voor lokale ontwikkeling

Gebruik een hulpprogramma in uw lokale ontwikkelomgeving voor verificatie bij Azure-identiteit. Zodra u bent geverifieerd, zoekt en gebruikt het DefaultAzureCredential exemplaar in uw broncode uw identiteit voor verificatiedoeleinden.

Selecteer een hulpprogramma voor verificatie tijdens lokale ontwikkeling.

Omgevingsvariabelen configureren voor lokale ontwikkeling

Als u verbinding wilt maken met Azure AI Search, moet uw code uw resource-eindpunt kennen.

Maak een omgevingsvariabele met de naam AZURE_SEARCH_ENDPOINT voor uw Azure AI Search-eindpunt. Deze URL heeft over het algemeen de indeling https://<YOUR-RESOURCE-NAME>.search.windows.net/.

Productiewerkbelastingen

De implementatie van productieworkloads omvat de volgende stappen:

• Kies RBAC-rollen die voldoen aan het principe van minimale bevoegdheden.
• Wijs RBAC-rollen toe aan uw productie-identiteit voor de specifieke resource.
• Omgevingsvariabelen instellen voor uw resource.

Rollen voor productiewerkbelastingen

Als u uw productiebronnen wilt maken, moet u een door de gebruiker toegewezen beheerde identiteit maken en die identiteit vervolgens toewijzen aan uw resources met de juiste rollen.

De volgende rol wordt voorgesteld voor een productietoepassing:

Authenticatie voor productieomgevingen

Gebruik de volgende Azure AI Search Bicep-sjabloon om de resource te maken en de verificatie voor de identityIdresource in te stellen. Bicep vereist de rol-id. De name weergave in dit Bicep-fragment is niet de Azure-rol. Dit is specifiek voor de Bicep-implementatie.

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

Het main.bicep bestand roept de volgende generieke Bicep-code aan om een rol te maken. U hebt de mogelijkheid om meerdere RBAC-rollen te maken, zoals een voor de gebruiker en een andere voor productie. Hierdoor kunt u zowel ontwikkel- als productieomgevingen inschakelen binnen dezelfde Bicep-implementatie.

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

Omgevingsvariabelen configureren voor productieworkloads

Als u verbinding wilt maken met Azure AI Search, moet uw code uw resource-eindpunt en de id van de beheerde identiteit kennen.

Maak omgevingsvariabelen voor uw geïmplementeerde en sleutelloze Azure AI Search-resource:

• AZURE_SEARCH_ENDPOINT: Deze URL is het toegangspunt voor uw Azure AI Search-resource. Deze URL heeft over het algemeen de indeling https://<YOUR-RESOURCE-NAME>.search.windows.net/.
• AZURE_CLIENT_ID: Dit is de identiteit die moet worden geverifieerd als.

Veelvoorkomende fouten oplossen

Verwante inhoud

• Ontwikkelaarshandleiding voor sleutelloze verbindingen
• Ingebouwde Azure-rollen
• Omgevingsvariabelen instellen