Verbinden Sie Ihre App mit Foundry IQ (Azure KI-Suche) mithilfe von Identitäten

Note

Foundry IQ (Azure KI-Suche) bietet direkte Indizierungs- und Abfrage-APIs zusammen mit Wissensquellen- und Knowledge Base-APIs auf höherer Ebene für den verwalteten Abruf. Verwenden Sie das Azure Portal, REST-APIs oder Azure SDKs, um diese Funktionen zu konfigurieren, oder verbinden Sie Agents mit Wissensdatenbanken im Microsoft Foundry-Portal.

In Ihrem Anwendungscode können Sie eine schlüssellose Verbindung mit Foundry IQ (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 (oder Verbindungszeichenfolge) zum Speichern vorhanden ist.

In diesem Artikel wird erläutert, wie Sie in Ihrem Anwendungscode verwenden DefaultAzureCredential .

Führen Sie die folgenden Schritte aus, um schlüssellose Verbindungen in Ihrem Code zu implementieren:

  • Aktivieren Sie den rollenbasierten Zugriff für Ihren Foundry IQ-Dienst
  • Legen Sie je nach Bedarf die Umgebungsvariablen fest.
  • Verwenden Sie einen Anmeldeinformationstyp einer Azure Identity-Bibliothek, um ein Foundry IQ-Clientobjekt zu erstellen.

Voraussetzungen

  • Foundry IQ, jede Region, aber es muss eine abrechenbare Stufe (Basic oder höher) sein.

  • Rollenbasierter Zugriff aktiviert für Ihren Foundry IQ-Dienst.

  • Rollenzuweisungen zu Foundry IQ. Weisen Sie Ihrer Identität diese Rollen zu:

    • Mitwirkender für Suchdienst und Mitwirkender für Suchindexdaten für die lokale Entwicklung (Vollzugriff)
    • Search Index Data Reader für schreibgeschützte Produktionsabfragen

    Anleitungen Schritt für Schritt finden Sie unter "Zuweisen von Rollen für die Entwicklung".

Installieren Azure Identity-Clientbibliothek

Um einen schlüssellosen Ansatz zu verwenden, aktualisieren Sie Ihren Foundry IQ-fähigen Code mit der Azure Identity-Clientbibliothek.

Installieren Sie die clientbibliothek Azure Identity für .NET und die Clientbibliothek Azure Search Documents:

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

Quellcode aktualisieren, um DefaultAzureCredential zu verwenden

Mit der Azure Identitätsbibliothek DefaultAzureCredential können Sie den gleichen 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);

Reference:SearchClient, SearchIndexClient, DefaultAzureCredential

überprüfen Sie die Verbindung

Überprüfen Sie nach dem Einrichten des Clients Ihre Verbindung, indem Sie einen einfachen Vorgang ausführen. Im folgenden Beispiel werden Indizes für Ihren Foundry IQ-Dienst aufgelistet:

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

Eine erfolgreiche Verbindung druckt die Namen Ihrer Indizes (oder eine leere Liste, wenn keine Indizes vorhanden sind). Wenn Sie einen Authentifizierungsfehler erhalten, überprüfen Sie, ob der rollenbasierte Zugriff aktiviert ist und Ihre Identität über die erforderlichen Rollenzuweisungen verfügt.

Die Standardautorität ist Azure öffentliche Cloud. Benutzerdefinierte audience Werte für souveräne oder spezialisierte Clouds umfassen:

  • https://search.azure.usfür Azure Government
  • https://search.azure.cnfür Azure betrieben von 21Vianet
  • https://search.microsoftazure.defür Azure Deutschland

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 CLI 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 Datenebenenvorgänge. Dies sind die vorgeschlagenen Rollen:

  • Suchdienstmitwirkender, Erstellen und Verwalten von Objekten
  • Mitwirkender an Suchindexdaten, Laden und Abfragen eines Indexes und Abrufen aus einer Knowledge Base

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

Ersetzen Sie die Platzhalter <role-name>, <identity-id>, <subscription-id> und <resource-group-name> mit Ihren tatsächlichen Werten in den folgenden Befehlen.

  1. Melden Sie sich bei Azure CLI an.

    az login
    

    Ein Browserfenster wird zur Authentifizierung geöffnet. Nach erfolgreicher Anmeldung zeigt das Terminal Ihre Abonnementinformationen an.

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

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

    Der Befehl gibt Ihre Benutzerobjekt-ID (eine GUID) zurück. Speichern Sie diesen Wert für den nächsten Schritt.

  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>"
    

    Eine erfolgreiche Zuweisung gibt ein JSON-Objekt mit den Details zur Rollenzuweisung zurück.

Authentifizierung für die lokale Entwicklung

Verwenden Sie ein Tool in Ihrer lokalen Entwicklungsumgebung, um sich mit Azure-Identität zu authentifizieren. Nachdem Sie sich authentifiziert haben, findet und verwendet die DefaultAzureCredential Instanz im Quellcode Ihre Identität zu Authentifizierungszwecken.

Wählen Sie ein Tool für Authentifizierung während der lokalen Entwicklung aus.

Konfigurieren von Umgebungsvariablen für die lokale Entwicklung

Um eine Verbindung mit Foundry IQ herzustellen, muss Ihr Code Ihren Ressourcenendpunkt kennen.

Erstellen Sie eine Umgebungsvariable mit dem Namen AZURE_SEARCH_ENDPOINT für Ihren Foundry IQ-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 Id
Suchindexdatenleser 1407120a-92aa-4202-b7e9-c0e197c71c8f

Authentifizierung für Produktionsworkloads

Verwenden Sie die folgende Foundry IQ Bicep Vorlage, um die Ressource zu erstellen und die Authentifizierung für die identityIdWorkload 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 Foundry IQ herzustellen, muss Ihr Code Ihren Ressourcenendpunkt und die ID der verwalteten Identität kennen.

Erstellen Sie Umgebungsvariablen für Ihre bereitgestellte und schlüssellose Foundry IQ-Ressource:

  • AZURE_SEARCH_ENDPOINT: Diese URL ist der Zugriffspunkt für Ihre Foundry IQ-Ressource. Diese URL weist im Allgemeinen das Format https://<YOUR-RESOURCE-NAME>.search.windows.net/ auf.
  • AZURE_CLIENT_ID: Dies ist die Identität, mit der authentifiziert werden soll.

Häufige Fehler beheben

Fehler Ursache Lösung
AuthenticationFailedException Fehlende oder ungültige Anmeldeinformationen Stellen Sie sicher, dass Sie mit az login (CLI) oder Connect-AzAccount (PowerShell) angemeldet sind. Überprüfen Sie, ob Ihr Azure Konto Zugriff auf das Abonnement hat.
403 Forbidden Der Identität fehlt die erforderliche Rolle Weisen Sie die entsprechende Rolle zu (Suchindexdatenleser für Abfragen, Suchindexdatenmitwirkender für die Indizierung). Rollenzuweisungen können bis zu 10 Minuten dauern, bis sie verteilt werden.
401 Unauthorized RBAC nicht im Foundry IQ-Dienst aktiviert Aktivieren Sie den rollenbasierten Zugriff im Azure-Portal unter Settings>Keys>Role-based access control.
ResourceNotFoundException Ungültiger Endpunkt- oder Indexname Überprüfen Sie, ob die Umgebungsvariable AZURE_SEARCH_ENDPOINT Ihrer Foundry IQ-Service-URL entspricht (Format: https://<service-name>.search.windows.net).
CredentialUnavailableException Keine gültigen Anmeldeinformationen gefunden DefaultAzureCredential probiert mehrere Authentifizierungsmethoden aus. Stellen Sie sicher, dass mindestens eine konfiguriert ist (Azure CLI, Visual Studio, Umgebungsvariablen).