Dela via

Ansluta din app till Azure AI Search med hjälp av identiteter

I programkoden kan du konfigurera en nyckellös anslutning till Azure AI Search som använder Microsoft Entra-ID och roller för autentisering och auktorisering. Programbegäranden till de flesta Azure-tjänster måste autentiseras med nycklar eller nyckellösa anslutningar. Utvecklare måste vara noggranna för att aldrig exponera nycklarna på en osäker plats. Alla som får åtkomst till nyckeln kan autentisera till tjänsten. Nyckellös autentisering ger bättre hanterings- och säkerhetsfördelar jämfört med kontonyckeln eftersom det inte finns någon nyckel (eller anslutningssträng) att lagra.

I den här artikeln beskrivs hur du använder DefaultAzureCredential i programkoden.

Följ dessa steg för att implementera nyckellösa anslutningar i koden:

  • Aktivera rollbaserad åtkomst i söktjänsten
  • Ange miljövariabler efter behov.
  • Använd en autentiseringstyp för Azure Identity-biblioteket för att skapa ett Azure AI Search-klientobjekt.

Förutsättningar

  • Azure AI Search, vilken region som helst, men den måste vara en fakturerbar nivå (grundläggande eller högre).

  • Rollbaserad åtkomst aktiverad i söktjänsten.

  • Rolltilldelningar i Azure AI Search. Tilldela dessa roller till din identitet:

    • Search Service-deltagare och Search Index Data-deltagare för lokal utveckling (fullständig åtkomst)
    • Databläddrare för sökindex för skrivskyddade förfrågningar i produktion

    Stegvisa instruktioner finns i Tilldela roller för utveckling.

Installera Azure Identity-klientbiblioteket

Om du vill använda en nyckellös metod uppdaterar du din AI Search-aktiverade kod med Azure Identity-klientbiblioteket.

Installera Azure Identity-klientbiblioteket för .NET och Azure Search Documents-klientbiblioteket:

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

Uppdatera källkoden för att använda DefaultAzureCredential

Med Azure Identity-biblioteket kan DefaultAzureCredential du köra samma kod i den lokala utvecklingsmiljön och i Azure-molnet. Skapa en enda autentiseringsuppgift och återanvänd autentiseringsuppgiftsinstansen efter behov för att dra nytta av tokencachelagring.

Mer information om DefaultAzureCredential för .NET finns i Azure Identity-klientbiblioteket för .NET.

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

Referens:SearchClient, SearchIndexClient, DefaultAzureCredential

Verifiera anslutningen

När du har konfigurerat klienten kontrollerar du anslutningen genom att köra en enkel åtgärd. I följande exempel visas index för söktjänsten:

// List indexes to verify connection
var indexes = searchIndexClient.GetIndexNames();
foreach (var name in indexes)
{
    Console.WriteLine(name);
}

En lyckad anslutning skriver ut namnen på dina index (eller en tom lista om det inte finns några index). Om du får ett autentiseringsfel kontrollerar du att rollbaserad åtkomst är aktiverad och att din identitet har de rolltilldelningar som krävs.

Standardauktoriteten är Azure public cloud. Anpassade audience värden för nationella eller specialiserade moln är:

  • https://search.azure.us för Azure Government
  • https://search.azure.cn för Azure som drivs av 21Vianet
  • https://search.microsoftazure.de för Azure Tyskland

Lokal utveckling

Lokal utveckling med hjälp av roller innehåller följande steg:

  • Tilldela din användaridentitet till RBAC-roller för den specifika resursen.
  • Använd ett verktyg som Azure CLI eller Azure PowerShell för att autentisera med Azure.
  • Upprätta miljövariabler för resursen.

Roller för lokal utveckling

Som lokal utvecklare behöver din Azure-identitet fullständig kontroll över åtgärder i dataplanen. Det här är de föreslagna rollerna:

  • Söktjänstdeltagare, skapa och hantera objekt
  • Indexdatamedverkare, ladda och utför en sökning i ett index

Hitta din personliga identitet med något av följande verktyg. Använd den identiteten <identity-id> som värde.

Ersätt platshållarna <role-name>, <identity-id>, <subscription-id>och <resource-group-name> med dina faktiska värden i följande kommandon.

  1. Logga in på Azure CLI.

    az login

    Ett webbläsarfönster öppnas för autentisering. Efter lyckad inloggning visar terminalen din prenumerationsinformation.

  2. Hämta din personliga identitet.

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

    Kommandot returnerar ditt användarobjekt-ID (ett GUID). Spara det här värdet för nästa steg.

  3. Tilldela rollen rollbaserad åtkomstkontroll (RBAC) till resursgruppens identitet.

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

    En lyckad tilldelning returnerar ett JSON-objekt med rolltilldelningsinformationen.

Autentisering för lokal utveckling

Använd ett verktyg i din lokala utvecklingsmiljö för autentisering till Azure-identitet. När du har autentiserats hittar och använder instansen i källkoden DefaultAzureCredential din identitet i autentiseringssyfte.

Välj ett verktyg för autentisering under lokal utveckling.

Konfigurera miljövariabler för lokal utveckling

Om du vill ansluta till Azure AI Search måste koden känna till resursslutpunkten.

Skapa en miljövariabel med namnet AZURE_SEARCH_ENDPOINT för din Azure AI Search-slutpunkt. Den här URL:en har vanligtvis formatet https://<YOUR-RESOURCE-NAME>.search.windows.net/.

Produktionsarbetsbelastningar

Distribuera produktionsarbetsbelastningar innehåller följande steg:

  • Välj RBAC-roller som följer principen om minsta behörighet.
  • Tilldela RBAC-roller till din produktionsidentitet på den specifika resursen.
  • Konfigurera miljövariabler för din resurs.

Roller för produktionsarbetsbelastningar

Om du vill skapa dina produktionsresurser måste du skapa en användartilldelad hanterad identitet och sedan tilldela den identiteten till dina resurser med rätt roller.

Följande roll föreslås för ett produktionsprogram:

Rollnamn Id
Dataläsare för sökindex 1407120a-92aa-4202-b7e9-c0e197c71c8f

Autentisering för produktionsarbetsbelastningar

Använd följande Azure AI Search Bicep-mall för att skapa resursen och ange autentiseringen för identityId. Bicep kräver roll-ID: t. Det name som visas i det här Bicep-kodfragmentet är inte Azure-rollen. Det är specifikt för Bicep-distributionen.

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

Filen main.bicep anropar följande generiska Bicep-kod för att skapa valfri roll. Du har möjlighet att skapa flera RBAC-roller, till exempel en för användaren och en annan för produktion. På så sätt kan du aktivera både utvecklings- och produktionsmiljöer i samma Bicep-distribution.

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

Konfigurera miljövariabler för produktionsarbetsbelastningar

För att ansluta till Azure AI Search måste koden känna till resursslutpunkten och ID:t för den hanterade identiteten.

Skapa miljövariabler för din distribuerade och nyckellösa Azure AI Search-resurs:

  • AZURE_SEARCH_ENDPOINT: Den här URL:en är åtkomstpunkten för din Azure AI Search-resurs. Den här URL:en har vanligtvis formatet https://<YOUR-RESOURCE-NAME>.search.windows.net/.
  • AZURE_CLIENT_ID: Det här är den identitet som ska autentiseras som.

Felsök vanliga fel

Error Orsak Lösning
AuthenticationFailedException Saknade eller ogiltiga autentiseringsuppgifter Kontrollera att du är inloggad med az login (CLI) eller Connect-AzAccount (PowerShell). Kontrollera att ditt Azure-konto har åtkomst till prenumerationen.
403 Forbidden Identiteten saknar nödvändig roll Tilldela lämplig roll (Sök indexdataläsare för frågor, Sök indexdatadeltagare för indexering). Rolltilldelningar kan ta upp till 10 minuter att propagera.
401 Unauthorized RBAC är inte aktiverat i söktjänsten Aktivera rollbaserad åtkomst i Azure-portalen under Inställningar>Nycklar>Rollbaserad åtkomstkontroll.
ResourceNotFoundException Ogiltigt slutpunkts- eller indexnamn Kontrollera att AZURE_SEARCH_ENDPOINT miljövariabeln matchar söktjänstens URL (format: https://<service-name>.search.windows.net).
CredentialUnavailableException Inga giltiga autentiseringsuppgifter hittades DefaultAzureCredential försöker med flera autentiseringsmetoder. Se till att minst en är konfigurerad (Azure CLI, Visual Studio, miljövariabler).

Relaterat innehåll

  • Last updated on