Beveiligingsfilters voor het bijsnijden van resultaten in Azure AI Search

Artikel
06/21/2024

Azure AI Search biedt geen systeemeigen machtigingen op documentniveau en kan de zoekresultaten niet variëren van binnen dezelfde index op gebruikersmachtigingen. Als tijdelijke oplossing kunt u een filter maken waarmee zoekresultaten worden geknipt op basis van een tekenreeks die een groep of gebruikersidentiteit bevat.

In dit artikel wordt een patroon voor beveiligingsfilters beschreven met de volgende stappen:

Brondocumenten samenstellen met de vereiste inhoud
Een veld maken voor de principal-id's
Push de documenten naar de zoekindex voor indexering
Een query uitvoeren op de index met de search.in filterfunctie

Het eindigt met koppelingen naar demo's en voorbeelden die praktische training bieden. We raden u aan dit artikel eerst te bekijken om het patroon te begrijpen.

Over het beveiligingsfilterpatroon

Hoewel Azure AI Search niet kan worden geïntegreerd met beveiligingssubsystemen voor toegang tot inhoud binnen een index, vinden veel klanten met beveiligingsvereisten op documentniveau dat filters aan hun behoeften kunnen voldoen.

In Azure AI Search is een beveiligingsfilter een normaal OData-filter dat een zoekresultaat bevat of uitsluit op basis van een tekenreeks die bestaat uit een beveiligingsprincipaal. Er is geen verificatie of autorisatie via de beveiligingsprincipaal. De principal is slechts een tekenreeks die in een filterexpressie wordt gebruikt om een document op te nemen of uit te sluiten van de zoekresultaten.

Er zijn verschillende manieren om beveiligingsfilters te bereiken. Een manier is door een gecompliceerde ontkoppeling van gelijkheidsexpressies, bijvoorbeeld, Id eq 'id1' or Id eq 'id2'enzovoort. Deze benadering is foutgevoelig, moeilijk te onderhouden en in gevallen waarin de lijst honderden of duizenden waarden bevat, vertraagt de reactietijd van query's met veel seconden.

Een betere oplossing is het gebruik van de search.in functie voor beveiligingsfilters, zoals beschreven in dit artikel. Als u in plaats van een gelijkheidsexpressie gebruikt search.in(Id, 'id1, id2, ...') , kunt u een reactietijd van een subseconde verwachten.

Vereisten

Een tekenreeksveld met een groeps- of gebruikersidentiteit, zoals een Microsoft Entra-object-id.

Andere velden in hetzelfde document moeten de inhoud bieden die toegankelijk is voor die groep of gebruiker. In de volgende JSON-documenten bevatten de velden 'security_id' identiteiten die worden gebruikt in een beveiligingsfilter en worden de naam, het salaris en de burgerlijke status opgenomen als de identiteit van de beller overeenkomt met de 'security_id' van het document.

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

Beveiligingsveld maken

In de zoekindex hebt u in de verzameling velden één veld nodig dat de groep of gebruikersidentiteit bevat, vergelijkbaar met het fictieve veld 'security_id' in het vorige voorbeeld.

Voeg een beveiligingsveld toe als een Collection(Edm.String).
Stel het kenmerk van filterable het veld in op true.
Stel het kenmerk van retrievable het veld in op false zodat het niet wordt geretourneerd als onderdeel van de zoekaanvraag.
Voor indexen is een documentsleutel vereist. Het veld file_id voldoet aan die vereiste.

Indexen moeten ook doorzoekbare en ophaalbare inhoud bevatten. De velden 'file_name' en 'file_description' vertegenwoordigen dat in dit voorbeeld.

Het volgende indexschema voldoet aan de veldvereisten. Documenten die u indexeren in Azure AI Search moeten waarden hebben voor al deze velden, inclusief de 'group_ids'. Voor het document met file_name 'secured_file_b' hebben alleen gebruikers die behoren tot groep-id's 'group_id1' of 'group_id2' leestoegang tot het bestand.

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

Gegevens naar uw index pushen met behulp van de REST API

Vul uw zoekindex in met documenten die waarden voor elk veld in de verzameling velden bevatten, inclusief waarden voor het beveiligingsveld. Azure AI Search biedt geen API's of functies voor het vullen van het beveiligingsveld. In verschillende voorbeelden aan het einde van dit artikel worden echter technieken uitgelegd voor het vullen van dit veld.

In Azure AI Search zijn de methoden voor het laden van gegevens:

Eén push- of pull-bewerking (indexeerfunctie) waarmee documenten worden geïmporteerd die zijn gevuld met alle velden
Meerdere push- of pull-bewerkingen. Zolang secundaire importbewerkingen gericht zijn op de juiste document-id, kunt u velden afzonderlijk laden via meerdere importbewerkingen.

In het volgende voorbeeld ziet u één HTTP POST-aanvraag voor de docs-verzameling van het URL-eindpunt van uw index (zie Documenten - Index). De hoofdtekst van de HTTP-aanvraag is een JSON-rendering van de documenten die moeten worden geïndexeerd:

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

Als u een bestaand document wilt bijwerken met de lijst met groepen, kunt u de merge of mergeOrUpload actie gebruiken:

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

Het beveiligingsfilter in de query toepassen

Als u documenten wilt knippen op group_ids basis van toegang, moet u een zoekquery uitgeven met een group_ids/any(g:search.in(g, 'group_id1, group_id2,...')) filter, waarbij 'group_id1, group_id2,...' zijn de groepen waartoe de verlener van zoekaanvragen behoort.

Dit filter komt overeen met alle documenten waarvoor het group_ids veld een van de opgegeven id's bevat. Voor volledige informatie over het zoeken naar documenten met behulp van Azure AI Search, kunt u Zoekdocumenten lezen.

In dit voorbeeld ziet u hoe u een query instelt met behulp van een POST-aanvraag.

Geef de HTTP POST-aanvraag op en geef het filter op in de aanvraagbody:

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

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

U moet de documenten terughalen met group_ids 'group_id1' of 'group_id2'. Met andere woorden, u krijgt de documenten waartoe de verlener van de aanvraag leestoegang heeft.

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

Volgende stappen

In dit artikel wordt een patroon beschreven voor het filteren van resultaten op basis van gebruikersidentiteit en de search.in() functie. U kunt deze functie gebruiken om principal-id's door te geven voor de aanvragende gebruiker om overeen te komen met principal-id's die aan elk doeldocument zijn gekoppeld. Wanneer een zoekaanvraag wordt verwerkt, filtert de search.in functie zoekresultaten waarvoor geen van de principals van de gebruiker leestoegang heeft. De principal-id's kunnen zaken vertegenwoordigen zoals beveiligingsgroepen, rollen of zelfs de eigen identiteit van de gebruiker.

Voor meer voorbeelden, demo's en video's:

Delen via