Sicherheitsfilter zum Einschränken von Ergebnissen in Azure KI Search

Artikel
09/03/2024

Azure KI-Suche bietet keine nativen Berechtigungen auf Dokumentebene und kann keine Suchergebnisse innerhalb desselben Indexes nach Benutzerberechtigungen variieren. Als Workaround können Sie einen Filter erstellen, der Suchergebnisse basierend auf einer Zeichenfolge, die eine Gruppe oder Benutzeridentität enthält, kürzt.

In diesem Artikel wird ein Muster für die Sicherheitsfilterung beschrieben, das die folgenden Schritte umfasst:

Zusammenstellen von Quelldokumenten mit dem erforderlichen Inhalt
Erstellen eines Felds für die Prinzipalbezeichner
Übertragen der Dokumente an den Suchindex für die Indizierung
Abfragen des Indexes mit der search.in Filterfunktion

Am Ende werden Links zu Demos und Beispielen bereitgestellt, die praxisbezogenes Lernen ermöglichen. Es wird empfohlen, zuerst diesen Artikel zu lesen, um das Muster zu verstehen.

Informationen zum Sicherheitsfiltermuster

Obwohl Azure KI-Suche nicht in Sicherheitssubsysteme für den Zugriff auf Inhalte in einem Index integriert ist, haben viele Kunden mit Sicherheitsanforderungen auf Dokumentebene festgestellt, dass Filter ihre Anforderungen erfüllen können.

In Azure KI-Suche ist ein Sicherheitsfilter ein regulärer OData-Filter, der ein Suchergebnis basierend auf einer Zeichenfolge einschließt oder ausschließt, die aus einem Sicherheitsprinzipal besteht. Es gibt keine Authentifizierung oder Autorisierung über den Sicherheitsprinzipal. Der Prinzipal ist nur eine Zeichenfolge, die in einem Filterausdruck verwendet wird, um ein Dokument aus den Suchergebnissen einzuschließen oder auszuschließen.

Es gibt mehrere Möglichkeiten zum Erreichen der Sicherheitsfilterung. Eine Möglichkeit besteht in einer komplizierten Disjunktion von Gleichheitsausdrücken, z. B Id eq 'id1' or Id eq 'id2', usw. Dieser Ansatz ist fehleranfällig, schwierig zu verwalten und verlangsamt die Antwortzeit von Anfragen um mehrere Sekunden, wenn die Liste Hunderte oder Tausende von Werten enthält.

Eine bessere Lösung ist die Verwendung der search.in Funktion für Sicherheitsfilter, wie in diesem Artikel beschrieben. Wenn Sie search.in(Id, 'id1, id2, ...') statt einem Gleichheitsausdruck verwenden, können Sie Antwortzeiten von unter einer Sekunde erwarten.

Voraussetzungen

Ein Zeichenfolgenfeld, das eine Gruppen- oder Benutzeridentität enthält, z. B. einen Microsoft Entra-Objektbezeichner.

Andere Felder im selben Dokument sollten den für diese Gruppe oder diesen Benutzer zugänglichen Inhalt bereitstellen. In den folgenden JSON-Dokumenten enthalten die Felder „security_id“ Identitäten, die in einem Sicherheitsfilter verwendet werden, und der Name, das Gehalt und der Familienstatus werden einbezogen, wenn die Identität des Aufrufers mit „security_id“ des Dokuments übereinstimmt.

{  
    "Employee-1": {  
        "employee_id": "100-1000-10-1-10000-1",
        "name": "Abram",   
        "salary": 75000,   
        "married": true,
        "security_id": "alphanumeric-object-id-for-employee-1"
    },
    "Employee-2": {  
        "employee_id": "200-2000-20-2-20000-2",
        "name": "Adams",   
        "salary": 75000,   
        "married": true,
        "security_id": "alphanumeric-object-id-for-employee-2"
    } 
}

Erstellen des Sicherheitsfelds

Im Suchindex benötigen Sie innerhalb der Feldauflistung ein Feld, das die Gruppen- oder Benutzeridentität enthält, ähnlich dem fiktiven Feld „security_id“ im vorherigen Beispiel.

Fügen Sie ein Sicherheitsfeld als ein Collection(Edm.String) hinzu.
Legen Sie das Attribut filterable des Felds auf true fest.
Legen Sie das Attribut des Felds retrievable auf false fest, dass es nicht als Teil der Suchanforderung zurückgegeben wird.
Für Indizes ist ein Dokumentschlüssel erforderlich. Das Feld „file_id“ erfüllt diese Anforderung.

Indizes sollten auch durchsuchbare und abrufbare Inhalte enthalten. Die Felder „file_name“ und „file_description“ stellen dies in diesem Beispiel dar.

Das folgende Indexschema erfüllt die Feldanforderungen. Dokumente, die Sie in Azure KI-Suche indizieren, sollten Werte für alle diese Felder aufweisen, einschließlich „group_ids“. Beim Dokument mit file_name „secured_file_b“ haben nur die Benutzer Lesezugriff auf die Datei, die zu den Gruppen-IDs „group_id1“ oder „group_id2“ gehören.

POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2024-07-01
{
     "name": "securedfiles",  
     "fields": [
         {"name": "file_id", "type": "Edm.String", "key": true, "searchable": false },
         {"name": "file_name", "type": "Edm.String", "searchable": true },
         {"name": "file_description", "type": "Edm.String", "searchable": true },
         {"name": "group_ids", "type": "Collection(Edm.String)", "filterable": true, "retrievable": false }
     ]
 }

Verwenden der REST-API, um Daten mithilfe von Push in Ihren Index zu übertragen

Füllen Sie den Suchindex mit Dokumenten auf, die Werte für jedes Feld in der Feldauflistung bereitstellen, einschließlich der Werte für das Sicherheitsfeld. Azure KI-Suche bietet keine APIs oder Features zum speziellen Auffüllen des Sicherheitsfelds. Einige der Beispiele, die am Ende dieses Artikels aufgeführt sind, erläutern jedoch Techniken zum Auffüllen dieses Felds.

In Azure KI-Suche werden folgende Ansätze zum Laden von Daten verwendet:

Ein einzelner Push- oder Pullvorgang (Indexer), der Dokumente importiert, die mit allen Feldern aufgefüllt sind
Mehrere Push- oder Pullvorgänge. Solange sekundäre Importvorgänge auf den richtigen Dokumentbezeichner abzielen, können Sie Felder einzeln über mehrere Importe laden.

Im folgenden Beispiel wird eine einzelne HTTP POST-Anforderung an die docs-Auflistung des URL-Endpunkts Ihres Index gezeigt (siehe Dokumente: Index). Der Haupttext der HTTP-Anforderung ist ein JSON-Rendering der Dokumente, die indiziert werden sollen:

POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2024-07-01
{
    "value": [
        {
            "@search.action": "upload",
            "file_id": "1",
            "file_name": "secured_file_a",
            "file_description": "File access is restricted to Human Resources.",
            "group_ids": ["group_id1"]
        },
        {
            "@search.action": "upload",
            "file_id": "2",
            "file_name": "secured_file_b",
            "file_description": "File access is restricted to Human Resources and Recruiting.",
            "group_ids": ["group_id1", "group_id2"]
        },
        {
            "@search.action": "upload",
            "file_id": "3",
            "file_name": "secured_file_c",
            "file_description": "File access is restricted to Operations and Logistics.",
            "group_ids": ["group_id5", "group_id6"]
        }
    ]
}

Wenn Sie ein vorhandenes Dokument mit der Liste der Gruppen aktualisieren müssen, können Sie die merge- oder mergeOrUpload-Aktion verwenden:

{
    "value": [
        {
            "@search.action": "mergeOrUpload",
            "file_id": "3",
            "group_ids": ["group_id7", "group_id8", "group_id9"]
        }
    ]
}

Anwenden des Sicherheitsfilters in der Abfrage

Für das Kürzen von Dokumenten basierend auf dem group_ids-Zugriff sollten Sie eine Suchabfrage mit einem group_ids/any(g:search.in(g, 'group_id1, group_id2,...'))-Filter eingeben, bei der „group_id1, group_id2,...“ die Gruppen sind, zu denen der Aussteller der Suchanforderung gehört.

Dieser Filter vergleicht alle Dokumente, für die das group_ids-Feld einen der angegebenen Bezeichner enthält. Vollständige Details zum Durchsuchen von Dokumenten mithilfe von Azure KI Search finden Sie unter Durchsuchen von Dokumenten.

In diesem Beispiel wird gezeigt, wie Sie eine Abfrage mithilfe einer POST-Anforderung einrichten.

Geben Sie die HTTP POST-Anforderung aus, und geben Sie den Filter im Anforderungstext an:

POST https://[service name].search.windows.net/indexes/securedfiles/docs/search?api-version=2024-07-01

{
   "filter":"group_ids/any(g:search.in(g, 'group_id1, group_id2'))"  
}

Es sollten die Dokumente zurückgegeben werden, bei denen group_ids entweder „group_id1“ oder „group_id2“ enthält. Das heißt, Sie erhalten die Dokumente, für die der Anforderungsaussteller über Lesezugriff verfügt.

{
 [
   {
    "@search.score":1.0,
     "file_id":"1",
     "file_name":"secured_file_a",
   },
   {
     "@search.score":1.0,
     "file_id":"2",
     "file_name":"secured_file_b"
   }
 ]
}

Nächste Schritte

In diesem Artikel wurde ein Muster zum Filtern von Ergebnissen basierend auf der Benutzeridentität und der search.in()-Funktion beschrieben. Sie können diese Funktion verwenden, um Prinzipalbezeichner für den anfordernden Benutzer zu übergeben, um diese mit den Prinzipalbezeichnern zu vergleichen, die dem entsprechenden Zieldokument zugeordnet sind. Wenn eine Suchanforderung verarbeitet wird, filtert die search.in-Funktion die Suchergebnisse heraus, für die keiner der Prinzipale des Benutzers über Lesezugriff verfügt. Der Prinzipalbezeichner kann beispielsweise Sicherheitsgruppen, Rollen oder sogar die Identität des Benutzers darstellen.

Weitere Beispiele, Demos und Videos:

Freigeben über