Freigeben über

Verbinden Ihrer App mit Azure KI-Suche mithilfe von Identitäten

  • Artikel

In Ihrem Anwendungscode können Sie eine schlüssellose Verbindung mit der Azure KI-Suche einrichten, die Microsoft Entra ID und -Rollen für die Authentifizierung und Autorisierung verwendet. Anwendungsanforderungen an die meisten Azure-Dienste müssen mit Schlüsseln oder schlüssellosen Verbindungen authentifiziert werden. Entwickler müssen darauf achten, dass die Schlüssel nicht an einem unsicheren Ort offengelegt werden. Jeder Benutzer, der Zugriff auf den Schlüssel erhält, kann sich beim Dienst authentifizieren. Die schlüssellose Authentifizierung bietet verbesserte Verwaltungs- und Sicherheitsvorteile gegenüber dem Kontoschlüssel, da kein Schlüssel (und keine Verbindungszeichenfolge) zum Speichern vorhanden ist.

Schlüssellose Verbindungen werden mit den folgenden Schritten aktiviert:

  • Konfigurieren Sie die Authentifizierung.
  • Legen Sie je nach Bedarf die Umgebungsvariablen fest.
  • Verwenden Sie einen Anmeldeinformationstyp der Azure Identity-Bibliothek, um ein Azure KI-Suche-Clientobjekt zu erstellen.

Voraussetzungen

Die folgenden Schritte müssen für lokale Entwicklungs- und Produktionsworkloads ausgeführt werden:

Erstellen einer Azure KI-Suche-Ressource

Bevor Sie mit diesem Artikel fortfahren, benötigen Sie eine Azure KI-Suche-Ressource, mit der Sie arbeiten können. Wenn Sie über keine Ressource verfügen, erstellen Sie Ihre Ressource jetzt. Aktivieren Sie die rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) für die Ressource.

Installieren der Azure Identity-Clientbibliothek

Für die Herangehensweise ohne Schlüssel aktualisieren Sie Ihren für KI-Suche aktivierten Code mit der Azure Identity-Clientbibliothek.

Azure Identity-Clientbibliothek für .NET:

dotnet add package Azure.Identity

Quellcode aktualisieren, um DefaultAzureCredential zu verwenden

Mit dem DefaultAzureCredential der Azure Identity-Bibliothek können Sie denselben Code in der lokalen Entwicklungsumgebung und in der Azure-Cloud ausführen. Erstellen Sie eine einzelne Anmeldeinformation, und verwenden Sie die Anmeldeinformationsinstanz nach Bedarf wieder, um die Zwischenspeicherung von Tokens zu nutzen.

Weitere Informationen zu DefaultAzureCredential für .NET finden Sie unter Azure Identity-Clientbibliothek 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);

Lokale Entwicklung

Die lokale Entwicklung mit Rollen umfasst die folgenden Schritte:

  • Weisen Sie Ihre persönliche Identität RBAC-Rollen für die jeweilige Ressource zu.
  • Verwenden Sie ein Tool wie die Azure-Befehlszeilenschnittstelle oder Azure PowerShell, um sich bei Azure zu authentifizieren.
  • Richten Sie Umgebungsvariablen für Ihre Ressource ein.

Rollen für lokale Entwicklung

Als lokaler Entwickler benötigt Ihre Azure-Identität die vollständige Kontrolle über Vorgänge auf Datenebene. Dies sind die vorgeschlagenen Rollen:

  • Suchdienstmitwirkender, Erstellen und Verwalten von Objekten
  • Mitwirkender an Suchindexdaten, Laden und Abfragen eines Index

Suchen Sie Ihre persönliche Identität mit einem der folgenden Tools. Verwenden Sie diese Identität als <identity-id>-Wert.

  1. Melden Sie sich bei der Azure-Befehlszeilenschnittstelle an.

    az login

  2. Rufen Sie Ihre persönliche Identität ab.

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

  3. Weisen Sie die rollenbasierte Zugriffssteuerung der Identität für die Ressourcengruppe zu.

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

Ersetzen Sie gegebenenfalls <identity-id>, <subscription-id> und <resource-group-name> durch Ihre tatsächlichen Werte.

Authentifizierung für die lokale Entwicklung

Verwenden Sie ein Tool in Ihrer lokalen Entwicklungsumgebung, um die Authentifizierung für Azure Identity durchzuführen. Nachdem Sie sich authentifiziert haben, findet und verwendet die DefaultAzureCredential-Instanz im Quellcode die Authentifizierung.

Konfigurieren von Umgebungsvariablen für die lokale Entwicklung

Um eine Verbindung mit Azure KI-Suche herzustellen, muss Ihr Code Ihren Ressourcenendpunkt kennen.

Erstellen Sie eine Umgebungsvariable namens AZURE_SEARCH_ENDPOINT für Ihren Azure KI-Suche-Endpunkt. Diese URL weist im Allgemeinen das Format https://<YOUR-RESOURCE-NAME>.search.windows.net/ auf.

Produktionsworkloads

Die Bereitstellung von Produktionsworkloads umfasst die folgenden Schritte:

  • Wählen Sie RBAC-Rollen, die das Prinzip der geringsten Rechte einhalten.
  • Weisen Sie Ihrer Produktionsidentität RBAC-Rollen für die jeweilige Ressource zu.
  • Richten Sie Umgebungsvariablen für Ihre Ressource ein.

Rollen für Produktionsworkloads

Um Ihre Produktionsressourcen zu erstellen, müssen Sie eine benutzerseitig zugewiesene verwaltete Identität erstellen und diese Identität dann Ihren Ressourcen mit den richtigen Rollen zuweisen.

Die folgende Rolle wird für eine Produktionsanwendung vorgeschlagen:

Rollenname Kennung
Suchindexdatenleser 1407120a-92aa-4202-b7e9-c0e197c71c8f

Authentifizierung für Produktionsworkloads

Verwenden Sie die folgende Bicep-Vorlage für die Azure KI-Suche, um die Ressource zu erstellen und die Authentifizierung für die identityId festzulegen. Bicep erfordert die Rollen-ID. Der in diesem Bicep-Ausschnitt angezeigte name ist nicht die Azure-Rolle. Er ist spezifisch für die Bicep-Bereitstellung.

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

Die main.bicep-Datei ruft den folgenden generischen Bicep-Code auf, um eine beliebige Rolle zu erstellen. Sie haben die Möglichkeit, mehrere RBAC-Rollen zu erstellen, z. B. eine für den Benutzer und eine für die Produktion. Auf diese Weise können Sie sowohl Entwicklungs- als auch Produktionsumgebungen innerhalb derselben Bicep-Bereitstellung aktivieren.

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

Konfigurieren von Umgebungsvariablen für Produktionsworkloads

Um eine Verbindung mit Azure KI-Suche herzustellen, muss Ihr Code Ihren Ressourcenendpunkt und die ID der verwalteten Identität kennen.

Erstellen Sie Umgebungsvariablen für Ihre bereitgestellte und schlüssellose Azure KI-Suche-Ressource:

  • AZURE_SEARCH_ENDPOINT: Diese URL ist der Zugriffspunkt für Ihre Azure KI-Suche-Ressource. Diese URL weist im Allgemeinen das Format https://<YOUR-RESOURCE-NAME>.search.windows.net/ auf.
  • AZURE_CLIENT_ID: Dies ist die Identität für die Authentifizierung.

Zugehöriger Inhalt