Sicherheitsfilter zum Einschränken von Ergebnissen in Azure KI Search

  • Artikel

Azure KI Search bietet keine 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

Informationen zum Sicherheitsfiltermuster

Obwohl Azure KI Search 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 Search ist ein Sicherheitsfilter ein regulärer OData-Filter, der ein Suchergebnis basierend auf einem übereinstimmenden Wert einschließt oder ausschließt, außer dass es sich bei einem Sicherheitsfilter um eine Zeichenfolge handelt, 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

  • Das Feld mit der Gruppen- oder Benutzeridentität muss eine Zeichenfolge mit dem Attribut „filterbar“ sein. Es sollte eine Sammlung sein. Es sollte keine Nullwerte zulassen.

  • 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 dem „security_id“ des Dokuments übereinstimmt.

    {  
    "Employee-1": {  
        "id": "100-1000-10-1-10000-1",
        "name": "Abram",   
        "salary": 75000,   
        "married": true,
        "security_id": "10011"
    },
    "Employee-2": {  
        "id": "200-2000-20-2-20000-2",
        "name": "Adams",   
        "salary": 75000,   
        "married": true,
        "security_id": "20022"
    } 
}

    Hinweis

    Der Prozess des Abrufens der Prinzipalbezeichner und das Einfügen dieser Zeichenfolgen in Quelldokumente, die von Azure KI Search indiziert werden können, wird in diesem Artikel nicht behandelt. Informationen zum Abrufen von Bezeichnern finden Sie in der Dokumentation Ihres Identitätsdienstanbieters.

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.

  1. Fügen Sie ein Sicherheitsfeld als ein Collection(Edm.String) hinzu. Stellen Sie sicher, dass es einfilterable-Attribut auf true festgelegt hat, sodass Suchergebnisse basierend auf dem Zugriff gefiltert werden, den der Benutzer besitzt. Wenn Sie das group_ids-Feld für das Dokument mit dem file_name „secured_file_b“ beispielsweise auf ["group_id1, group_id2"] festlegen, haben nur die Benutzer Lesezugriff auf die Datei, die zu den Gruppen-IDs „group_id1“ oder „group_id2“ gehören.

    Legen Sie das Attribut des Felds retrievable auf false fest, dass es nicht als Teil der Suchanforderung zurückgegeben wird.

  2. Für Indizes ist ein Dokumentschlüssel erforderlich. Das Feld „file_id“ erfüllt diese Anforderung. Indizes sollten auch durchsuchbare Inhalte enthalten. Die Felder „file_name“ und „file_description“ stellen dies in diesem Beispiel dar.

    POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2023-11-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

Senden Sie eine HTTP POST-Anforderung an die docs-Auflistung des URL-Endpunkts Ihres Index (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=2023-11-01

Geben Sie im Anforderungstext den Inhalt Ihrer Dokumente an:

{
    "value": [
        {
            "@search.action": "upload",
            "file_id": "1",
            "file_name": "secured_file_a",
            "file_description": "File access is restricted to the 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:

POST https://[service name].search.windows.net/indexes/securedfiles/docs/search?api-version=2020-06-30
Content-Type: application/json  
api-key: [admin or query key]

Geben Sie den Filter im Anforderungstext an:

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

Um ein alternatives Muster, das auf Microsoft Entra ID basiert, anzuzeigen oder erneut auf andere Sicherheitsfeatures zuzugreifen, verwenden Sie die folgenden Links.