Authentifizieren bei einer Azure Funktions-App mit "Easy Auth" (Foundry IQ (Azure KI-Suche))

Hinweis

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 diesem Artikel wird erläutert, wie Sie mithilfe der integrierten Authentifizierungsfunktionen von Azure App Service, auch als "Easy Auth" bezeichnet, eine Indizierungsverbindung mit einer Azure Function-App einrichten. Azure Funktions-Apps sind eine großartige Lösung zum Hosten von benutzerdefinierten Web-APIs, die ein Foundry IQ (Azure KI-Suche) kann zum Anreichern von Inhalten verwendet werden, die während einer Indizierungsausführung aufgenommen werden, oder, wenn Sie ein benutzerdefiniertes Einbettungsmodell für die integrierte Vektorisierung verwenden, Vektorisieren von Inhalten in einer Suchabfrage.

Sie können eine vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identität des Foundry IQ-Diensts verwenden, um sich gegenüber der Azure Function-App zu authentifizieren. Für diesen Ansatz ist die Einrichtung einer Microsoft Entra ID-Anwendungsregistrierung erforderlich, die als Authentifizierungsanbieter für die Azure Function-App verwendet wird, die in diesem Artikel erläutert wird.

Voraussetzungen

Konfigurieren der Microsoft Entra ID-Anwendung als Authentifizierungsanbieter

Um Microsoft Entra ID als Authentifizierungsanbieter für eine Azure-Funktions-App zu verwenden, muss eine Anwendungsregistrierung erstellt werden. Es gibt zwei Optionen: Erstellen Sie eine automatisch über die Azure Function-App selbst oder verwenden Sie eine vorhandene Anwendung. Weitere Informationen zu diesen Schritten finden Sie in der App Service-Dokumentation.

Stellen Sie unabhängig von der gewählten Option sicher, dass die App-Registrierung gemäß den folgenden Schritten konfiguriert wird, damit sie mit Foundry IQ kompatibel ist.

Vergewissern Sie sich, dass für die App-Registrierung ein Anwendungs-ID-URI konfiguriert wurde.

Die App-Registrierung sollte mit einer Anwendungs-ID-URI konfiguriert werden, die als Zielgruppe des Tokens für Azure Function-Apps und Foundry IQ verwendet werden kann. Konfigurieren Sie ihn im Format api://<applicationId>. Dazu navigieren Sie zum Abschnitt Übersicht der App-Registrierung und legen das Feld Anwendungs-ID-URI fest.

Screenshot einer App-Registrierung mit einer Anwendungs-ID-URI.

Festlegen unterstützter Kontotypen für die Authentifizierung

Wechseln Sie zum Abschnitt " Authentifizierung" der App-Registrierung , und konfigurieren Sie die unterstützten Kontotypen , sodass nur Konten im selben Organisationsverzeichnis wie die App-Registrierung sie für die Authentifizierung verwenden können.

Screenshot einer App-Registrierung mit konfigurierten unterstützten Kontotypen.

(Optional:) Konfigurieren eines geheimen Clientschlüssels

Der App-Dienst empfiehlt die Verwendung eines geheimen Clientschlüssels für die Authentifizierungsanbieteranwendung. Die Authentifizierung funktioniert aber auch ohne geheimen Clientschlüssel, sofern delegierte Berechtigungen eingerichtet sind. Um einen geheimen Clientschlüssel einzurichten, navigieren Sie zum Abschnitt Zertifikate und Geheimnisse der App-Registrierung und fügen einen neuen geheimen Clientschlüssel hinzu, wie in diesem Artikel erläutert.

Screenshot einer App-Registrierung mit Option zum Konfigurieren des geheimen Clientschlüssels.

Hinzufügen eines Geltungsbereichs zum Delegieren von Berechtigungen

Navigieren Sie zum Abschnitt Eine API verfügbar machen, und konfigurieren Sie die App-Registrierung so, dass ihr Geltungsbereich Administrator- und Benutzerberechtigungen an sie delegiert. Damit stellen Sie sicher, dass sie mit dem Authentifizierungsflow des Indexers kompatibel ist.

Screenshot einer App-Registrierung, die den Berechtigungsbereich delegiert.

Nachdem der Geltungsbereich der delegierten Berechtigungen eingerichtet wurde, sollte im Abschnitt API-Berechtigungen der App-Registrierung die User.Read-API auf „Microsoft.Graph“ festgelegt sein.

Screenshot einer App-Registrierung mit delegierten Berechtigungen.

Konfigurieren des Microsoft Entra ID-Authentifizierungsanbieters in der Azure-Funktions-App

Nachdem die Clientanwendung mit den vorherigen Spezifikationen registriert wurde, kann die Microsoft Entra ID-Authentifizierung für die Azure Function-App mithilfe der App-Dienstdokumentation eingerichtet werden. Navigieren Sie zum Abschnitt Authentifizierung der Azure-Funktions-App, um die Authentifizierungsdetails einzurichten.

Stellen Sie sicher, dass die folgenden Einstellungen konfiguriert sind, um sicherzustellen, dass Foundry IQ sich erfolgreich bei der Azure Function-App authentifizieren kann.

Konfigurieren der Authentifizierungseinstellungen

  • Stellen Sie sicher, dass App Service-Authentifizierung auf Aktiviert festgelegt ist.
  • Einschränken des Zugriffs auf die Azure-Funktions-App mit Authentifizierung erforderlich
  • Wählen Sie für nicht authentifizierte Anforderungen den Fehler HTTP 401: Nicht autorisiert aus.

Der folgende Screenshot zeigt diese spezifischen Einstellungen für eine Azure-Funktions-Beispiel-App.

Screenshot einer Azure Function-App, die für die Authentifizierung konfiguriert ist.

Hinzufügen des Microsoft Entra ID-Authentifizierungsanbieters

  • Fügen Sie Microsoft Entra ID als Authentifizierungsanbieter für die Azure-Funktions-App hinzu.
  • Erstellen Sie entweder eine neue App-Registrierung, oder wählen Sie eine zuvor konfigurierte App-Registrierung aus. Vergewissern Sie sich, dass sie gemäß den Richtlinien im vorherigen Abschnitt dieses Dokuments konfiguriert wurde.
  • Vergewissern Sie sich, dass im Abschnitt Zugelassene Tokenzielgruppen der Anwendungs-ID-URI der App-Registrierung angegeben ist. Er sollte das Format api://<applicationId> aufweisen und mit der zuvor erstellten App-Registrierung übereinstimmen.
  • Wenn Sie möchten, können Sie andere Prüfungen so konfigurieren, dass der Zugriff speziell auf den Indexer beschränkt wird.

Screenshot einer Azure Function-App mit Microsoft Entra ID Authentifizierungsanbieter.

Konfigurieren anderer Prüfungen

  • Stellen Sie sicher, dass die Objekt-ID (Prinzipal-ID) der Identität des spezifischen Foundry IQ-Diensts als Identitätsanforderung angegeben ist, indem Sie die Option " Anforderungen von bestimmten Identitäten zulassen " überprüfen und die OBJEKT-ID (Prinzipal-ID) im Identitätsbereich eingeben.

Screenshot des Identitätsabschnitts für einen Foundry IQ-Dienst.

  • Wählen Sie in der Clientanwendungsanforderung die Option " Anforderungen von einer bestimmten Clientanwendung zulassen" aus. Sie müssen die Client-ID der Identität des Foundry IQ-Diensts nachschlagen. Kopieren Sie dazu die Objekt-ID (Prinzipal-ID) aus dem vorherigen Schritt, und suchen Sie in Ihrem Microsoft Entra ID-Mandanten danach. Es sollte eine übereinstimmende Unternehmensanwendung vorhanden sein, auf deren Übersichtsseite eine Anwendungs-ID aufgeführt wird. Dabei handelt es sich um die GUID, die als Clientanwendungsanforderung angegeben werden muss.

Screenshot der Unternehmensanwendungsdetails der Identität eines Foundry IQ-Diensts.

Hinweis

Dieser Schritt ist der wichtigste Konfigurationsschritt für die Azure-Funktions-App. Eine falsche Vorgehensweise kann dazu führen, dass der Indexer nicht auf die Azure-Funktions-App zugreifen kann. Achten Sie darauf, die Unternehmensanwendungsdetails der Identität korrekt nachzuschlagen und die Anwendungs-ID und die Objekt-ID (Prinzipal-ID) an den richtigen Stellen anzugeben.

  • Wählen Sie unter Mandantenanforderung eine der Optionen aus, die Ihrem Sicherheitsstatus entspricht. Weitere Informationen finden Sie in der App Service-Dokumentation.

Einrichten einer Verbindung mit der Azure Function-App

Je nachdem, ob die Verbindung mit der Azure-Funktions-App in einem benutzerdefinierten Web-API-Skill oder einem benutzerdefinierten Web-API-Vektorisierer hergestellt werden muss, unterscheidet sich die JSON-Definition geringfügig. Stellen Sie in beiden Fällen sicher, dass Sie den richtigen URI für die Azure-Funktions-App angeben und authResourceId auf denselben Wert festlegen, der unter Zugelassene Tokenzielgruppen für den Authentifizierungsanbieter konfiguriert wurde.

Je nachdem, ob Sie eine Verbindung mit einer vom System zugewiesenen Identität oder einer vom Benutzer zugewiesenen Identität herstellen möchten, unterscheiden sich die erforderlichen Eigenschaften geringfügig.

Eine systemseitig zugewiesene Identität verwenden

Hier ist ein Beispiel zum Aufrufen einer Funktion, die für das Beispiel Azure Funktions-App benannt test ist, wobei die vom System zugewiesene Identität des Foundry IQ-Diensts über "Easy Auth" authentifiziert werden darf.

"uri": "https://contoso-function-app.azurewebsites.net/api/test?",
"authResourceId": "api://00000000-0000-0000-0000-000000000000"

Verwenden einer benutzerseitig zugewiesenen Identität

Hier ist ein Beispiel für den Aufruf in dieselbe Funktion, bei dem die bestimmte vom Benutzer zugewiesene Identität über "Easy Auth" authentifiziert werden darf. Sie müssen die Ressourcen-ID der genauen vom Benutzer zugewiesenen Identität angeben, die in der identity Eigenschaft der Konfiguration verwendet werden soll.

"uri": "https://contoso-function-app.azurewebsites.net/api/test?",
"authResourceId": "api://00000000-0000-0000-0000-000000000000",
"identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }

Hinweis

Bevor Sie eine vom Benutzer zugewiesene Identität in einer Benutzerdefinierten Web-API-Fähigkeit oder Vektorizerdefinition angeben, weisen Sie die Identität dem Foundry IQ-Dienst zu.

Ausführen des Indexers/Vektorisierers zum Überprüfen der Berechtigungen

Bei benutzerdefinierten Web-API-Skills werden die Berechtigungen zur Indexerlaufzeit überprüft. Bei Vektorizern werden sie überprüft, wenn eine Vektorabfrage mit dem benutzerdefinierten Web-API-Vektorizer ausgegeben wird. Um Probleme mit der Authentifizierung auszuschließen, können Sie testweise den Authentifizierungsanbieter in der Azure-Funktions-App deaktivieren und dann überprüfen, ob Aufrufe von Indexer/Vektorisierer erfolgreich ausgeführt werden.

  • Wenn Authentifizierungsprobleme bestehen, stellen Sie sicher, dass die richtigen Identitätsinformationen – nämlich Anwendungs-ID, Objekt-ID (Prinzipal)-ID für die Identität des Foundry IQ-Diensts im Authentifizierungsanbieter der Azure Function-App angegeben sind.