Share via

Anslut till Azure AI Search med hjälp av rollbaserade åtkomstkontroller

  • Artikel

Azure tillhandahåller ett globalt rollbaserat auktoriseringssystem för åtkomstkontroll för alla tjänster som körs på plattformen. I Azure AI Search kan du tilldela Azure-roller för:

Åtkomst per användare via sökresultat (kallas ibland säkerhet på radnivå eller säkerhet på dokumentnivå) stöds inte via rolltilldelningar. Som en lösning skapar du säkerhetsfilter som trimmar resultatet efter användaridentitet och tar bort dokument som beställaren inte ska ha åtkomst till. Se det här enterprise-chattexemplet med RAG för en demonstration.

Rolltilldelningar är kumulativa och genomgripande för alla verktyg och klientbibliotek. Du kan tilldela roller med någon av de metoder som stöds som beskrivs i dokumentationen om rollbaserad åtkomstkontroll i Azure.

Rollbaserad åtkomst är valfri, men rekommenderas. Alternativet är nyckelbaserad autentisering, vilket är standardinställningen.

Förutsättningar

Begränsningar

  • Rollbaserad åtkomstkontroll kan öka svarstiden för vissa begäranden. Varje unik kombination av tjänstresurs (index, indexerare osv.) och tjänstens huvudnamn utlöser en auktoriseringskontroll. Dessa auktoriseringskontroller kan ge upp till 200 millisekunder svarstid per begäran.

  • I sällsynta fall där begäranden kommer från ett stort antal olika tjänsthuvudnamn, alla riktade mot olika tjänstresurser (index, indexerare osv.), är det möjligt att auktoriseringskontrollerna resulterar i begränsning. Begränsning skulle bara ske om hundratals unika kombinationer av söktjänstens resurs och tjänstens huvudnamn användes inom en sekund.

Aktivera rollbaserad åtkomst för dataplansåtgärder

Roller för tjänstadministration (kontrollplan) är obligatoriska. Roller för dataplansåtgärder är valfria. Du måste aktivera rollbaserad åtkomst innan du kan tilldela Söktjänstdeltagare, Search Index Data Contributor eller Search Index Data Reader-roller för dataåtgärder.

I det här steget konfigurerar du söktjänsten för att identifiera ett auktoriseringshuvud på dataplansbegäranden som tillhandahåller en OAuth2-åtkomsttoken.

Dataplanet refererar till åtgärder mot söktjänstens slutpunkt, till exempel indexering eller frågor, eller någon annan åtgärd som anges i REST API för sökning eller motsvarande klientbibliotek.

  1. Logga in på Azure-portalen och öppna söktjänstsidan.

  2. Välj Nycklar i det vänstra navigeringsfönstret.

    Skärmbild av sidan nycklar med autentiseringsalternativ.

  3. Välj Rollbaserad kontroll eller Båda om du vill ha flexibilitet.

    Alternativ Description
    API-nyckel (standard). Kräver API-nycklar i begärandehuvudet för auktorisering.
    Rollbaserad åtkomstkontroll Kräver medlemskap i en rolltilldelning för att slutföra uppgiften. Det kräver också ett auktoriseringshuvud för begäran.
    Båda Begäranden är giltiga med antingen en API-nyckel eller rollbaserad åtkomstkontroll, men om du anger båda i samma begäran används API-nyckeln.

Ändringen träder i kraft omedelbart, men vänta några sekunder innan du tilldelar roller.

När du aktiverar rollbaserad åtkomstkontroll är felläget "http401WithBearerChallenge" om auktoriseringen misslyckas.

Följande roller är inbyggda. Om de här rollerna inte räcker till skapar du en anpassad roll.

Roll Plan beskrivning
Ägare Kontrollera & data Fullständig åtkomst till kontrollplanet för sökresursen, inklusive möjligheten att tilldela Azure-roller. Endast rollen Ägare kan aktivera eller inaktivera autentiseringsalternativ eller hantera roller för andra användare. Prenumerationsadministratörer är medlemmar som standard.

På dataplanet har den här rollen samma åtkomst som rollen Search Service-deltagare. Den innehåller åtkomst till alla dataplansåtgärder förutom möjligheten att fråga eller indexera dokument.
Deltagare Kontrollera & data Samma nivå av kontrollplansåtkomst som Ägare, minus möjligheten att tilldela roller eller ändra autentiseringsalternativ.

På dataplanet har den här rollen samma åtkomst som rollen Search Service-deltagare. Den innehåller åtkomst till alla dataplansåtgärder förutom möjligheten att fråga eller indexera dokument.
Läsare Kontrollera & data Läsåtkomst i hela tjänsten, inklusive sökmått, innehållsmått (förbrukad lagring, antal objekt) och objektdefinitioner av dataplansresurser (index, indexerare och så vidare). Det går dock inte att läsa API-nycklar eller läsa innehåll i index.
Söktjänstdeltagare Kontrollera & data Läs- och skrivåtkomst till objektdefinitioner (index, alias, synonymkartor, indexerare, datakällor och kompetensuppsättningar). Den här rollen är till för utvecklare som skapar objekt och för administratörer som hanterar en söktjänst och dess objekt, men utan åtkomst till indexinnehåll. Använd den här rollen för att skapa, ta bort och lista index, hämta indexdefinitioner, hämta tjänstinformation (statistik och kvoter), testa analysverktyg, skapa och hantera synonymkartor, indexerare, datakällor och kompetensuppsättningar. Se Microsoft.Search/searchServices/* för behörighetslistan.
Search Index Data Contributor Data Läs- och skrivåtkomst till innehåll i index. Den här rollen är avsedd för utvecklare eller indexägare som behöver importera, uppdatera eller köra frågor mot dokumentsamlingen för ett index. Den här rollen stöder inte skapande eller hantering av index. Som standard är den här rollen för alla index i en söktjänst. Se Bevilja åtkomst till ett enda index för att begränsa omfånget.
Dataläsare för sökindex Data Skrivskyddad åtkomst för att fråga efter sökindex. Den här rollen gäller för appar och användare som kör frågor. Den här rollen stöder inte läsåtkomst till objektdefinitioner. Du kan till exempel inte läsa en definition av sökindex eller hämta statistik för söktjänsten. Som standard är den här rollen för alla index i en söktjänst. Se Bevilja åtkomst till ett enda index för att begränsa omfånget.

Kommentar

Om du inaktiverar rollbaserad åtkomst i Azure fortsätter inbyggda roller för kontrollplanet (ägare, deltagare, läsare) att vara tillgängliga. Om du inaktiverar rollbaserad åtkomst tar du bort bara de datarelaterade behörigheter som är associerade med dessa roller. Om dataplansroller är inaktiverade motsvarar Search Service-deltagaren kontrollplansdeltagaren.

Tilldela roller

I det här avsnittet tilldelar du roller för:

Tilldela roller för tjänstadministration

Som tjänstadministratör kan du skapa och konfigurera en söktjänst och utföra alla kontrollplansåtgärder som beskrivs i REST API för hantering eller motsvarande klientbibliotek. Beroende på vilken roll du har kan du också utföra de flesta REST API-uppgifter för dataplansökning.

  1. Logga in på Azure-portalen.

  2. Gå till söktjänsten.

  3. Välj Åtkomstkontroll (IAM) i det vänstra navigeringsfönstret.

  4. Välj + Lägg till>Lägg till rolltilldelning.

  5. Välj en tillämplig roll:

    • Ägare (fullständig åtkomst till alla dataplans- och kontrollplansåtgärder, förutom frågebehörigheter)
    • Deltagare (samma som Ägare, förutom behörigheter för att tilldela roller)
    • Läsare (godkänd för övervakning och visning av mått)

  6. På fliken Medlemmar väljer du Microsoft Entra-användar- eller gruppidentiteten.

  7. På fliken Granska + tilldela väljer du Granska + tilldela för att tilldela rollen.

Tilldela roller för utveckling

Rolltilldelningar är globala i söktjänsten. Om du vill begränsa behörigheter till ett enda index använder du PowerShell eller Azure CLI för att skapa en anpassad roll.

Viktigt!

Om du konfigurerar rollbaserad åtkomst för en tjänst eller ett index och du även anger en API-nyckel för begäran använder söktjänsten API-nyckeln för att autentisera.

  1. Logga in på Azure-portalen.

  2. Gå till söktjänsten.

  3. Välj Åtkomstkontroll (IAM) i det vänstra navigeringsfönstret.

  4. Välj + Lägg till>Lägg till rolltilldelning.

    Åtkomstkontrollsidan (IAM) med menyn Lägg till rolltilldelning öppen.

  5. Välj en roll:

    • Söktjänstdeltagare (create-read-update-delete-åtgärder för index, indexerare, kompetensuppsättningar och andra objekt på den översta nivån)
    • Sök indexdatadeltagare (läs in dokument och kör indexeringsjobb)
    • Dataläsare för sökindex (fråga efter ett index)

    En annan kombination av roller som ger fullständig åtkomst är Deltagare eller Ägare, plus Dataläsare för sökindex.

  6. På fliken Medlemmar väljer du Microsoft Entra-användar- eller gruppidentiteten.

  7. På fliken Granska + tilldela väljer du Granska + tilldela för att tilldela rollen.

  8. Upprepa för de andra rollerna. De flesta utvecklare behöver alla tre.

Tilldela roller för skrivskyddade frågor

Använd rollen Dataläsare för sökindex för appar och processer som bara behöver läsåtkomst till ett index. Detta är en mycket specifik roll. Den ger GET- eller POST-åtkomst till dokumentsamlingen för ett sökindex för sökning, automatisk komplettering och förslag.

Det stöder inte GET- eller LIST-åtgärder för ett index eller andra objekt på den översta nivån eller GET-tjänststatistik.

  1. Logga in på Azure-portalen.

  2. Gå till söktjänsten.

  3. Välj Åtkomstkontroll (IAM) i det vänstra navigeringsfönstret.

  4. Välj + Lägg till>Lägg till rolltilldelning.

  5. Välj rollen Dataläsare för sökindex.

  6. På fliken Medlemmar väljer du Microsoft Entra-användar- eller gruppidentiteten. Om du konfigurerar behörigheter för en annan tjänst kanske du använder en system- eller användarhanterad identitet. Välj det alternativet om rolltilldelningen är för en tjänstidentitet.

  7. På fliken Granska + tilldela väljer du Granska + tilldela för att tilldela rollen.

Testa rolltilldelningar

Använd en klient för att testa rolltilldelningar. Kom ihåg att roller är kumulativa och ärvda roller som är begränsade till prenumerations- eller resursgruppsnivå inte kan tas bort eller nekas på resursnivå (söktjänst).

Kontrollera att du registrerar klientprogrammet med Microsoft Entra-ID och har rolltilldelningar på plats innan du testar åtkomsten.

  1. Logga in på Azure-portalen.

  2. Gå till söktjänsten.

  3. På sidan Översikt väljer du fliken Index :

    • Search Service-deltagare kan visa och skapa ett objekt, men kan inte läsa in dokument eller köra frågor mot ett index. Om du vill verifiera behörigheter skapar du ett sökindex.

    • Search Index Data Contributors kan läsa in dokument. Det finns inget alternativ för inläsningsdokument i portalen utanför guiden Importera data, men du kan återställa och köra en indexerare för att bekräfta dokumentinläsningsbehörigheter.

    • Search Index Data Readers kan köra frågor mot indexet. Om du vill verifiera behörigheter använder du Sökutforskaren. Du bör kunna skicka frågor och visa resultat, men du bör inte kunna visa indexdefinitionen eller skapa en.

Testa som aktuell användare

Om du redan är deltagare eller ägare av söktjänsten kan du presentera en ägartoken för din användaridentitet för autentisering till Azure AI Search.

  1. Hämta en ägartoken för den aktuella användaren med hjälp av Azure CLI:

    az account get-access-token --scope https://search.azure.com/.default

    Eller genom att använda PowerShell:

    Get-AzAccessToken -ResourceUrl https://search.azure.com

  2. I en ny textfil i Visual Studio Code klistrar du in följande variabler:

    @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
@index-name = PASTE-YOUR-INDEX-NAME-HERE
@token = PASTE-YOUR-TOKEN-HERE

  3. Klistra in och skicka sedan en begäran för att bekräfta åtkomsten. Här är en som frågar indexet hotels-quickstart

    POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2023-11-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

    {
         "queryType": "simple",
         "search": "motel",
         "filter": "",
         "select": "HotelName,Description,Category,Tags",
         "count": true
     }

Bevilja åtkomst till ett enda index

I vissa scenarier kanske du vill begränsa ett programs åtkomst till en enskild resurs, till exempel ett index.

Portalen stöder för närvarande inte rolltilldelningar på den här detaljnivån, men det kan göras med PowerShell eller Azure CLI.

I PowerShell använder du New-AzRoleAssignment, anger Azure-användaren eller gruppnamnet och tilldelningens omfattning.

  1. Läs in modulerna Azure och AzureAD och anslut till ditt Azure-konto:

    Import-Module -Name Az
Import-Module -Name AzureAD
Connect-AzAccount

  2. Lägg till en rolltilldelning som är begränsad till ett enskilt index:

    New-AzRoleAssignment -ObjectId <objectId> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Skapa en anpassad roll

Om inbyggda roller inte ger rätt kombination av behörigheter kan du skapa en anpassad roll för att stödja de åtgärder du behöver.

Det här exemplet klonar Search Index Data Reader och lägger sedan till möjligheten att lista index efter namn. Normalt betraktas en lista över index i en söktjänst som en administrativ rättighet.

De här stegen härleds från Skapa eller uppdatera anpassade Azure-roller med hjälp av Azure-portalen. Kloning från en befintlig roll stöds på en söktjänstsida.

De här stegen skapar en anpassad roll som utökar sökfrågebehörigheten till att inkludera listindex efter namn. Vanligtvis betraktas listning av index som en administratörsfunktion.

  1. Gå till söktjänsten i Azure-portalen.

  2. I det vänstra navigeringsfönstret väljer du Åtkomstkontroll (IAM).

  3. I åtgärdsfältet väljer du Roller.

  4. Högerklicka på Sök indexdataläsare (eller en annan roll) och välj Klona för att öppna guiden Skapa en anpassad roll .

  5. På fliken Grundläggande anger du ett namn för den anpassade rollen, till exempel "Sök indexdatautforskaren" och väljer sedan Nästa.

  6. På fliken Behörigheter väljer du Lägg till behörighet.

  7. På fliken Lägg till behörigheter söker du efter och väljer sedan panelen Microsoft Search .

  8. Ange behörigheter för din anpassade roll. Överst på sidan använder du standardalternativet Åtgärder :

    • Under Microsoft.Search/operations (Microsoft.Search/operations) väljer du Läs : Lista alla tillgängliga åtgärder.
    • Under Microsoft.Search/searchServices/index väljer du Läs: Läs index.

  9. På samma sida växlar du till Dataåtgärder och under Microsoft.Search/searchServices/index/documents väljer du Läs : Läs dokument.

    JSON-definitionen ser ut som i följande exempel:

    {
 "properties": {
     "roleName": "search index data explorer",
     "description": "",
     "assignableScopes": [
         "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
     ],
     "permissions": [
         {
             "actions": [
                 "Microsoft.Search/operations/read",
                 "Microsoft.Search/searchServices/indexes/read"
             ],
             "notActions": [],
             "dataActions": [
                 "Microsoft.Search/searchServices/indexes/documents/read"
             ],
             "notDataActions": []
         }
     ]
   }
 }

  10. Välj Granska + skapa för att skapa rollen. Nu kan du tilldela användare och grupper till rollen.

Inaktivera API-nyckelautentisering

Nyckelåtkomst, eller lokal autentisering, kan inaktiveras på din tjänst om du använder de inbyggda rollerna och Microsoft Entra-autentiseringen. Om du inaktiverar API-nycklar nekas söktjänsten alla datarelaterade begäranden som skickar en API-nyckel i huvudet.

Kommentar

Administratörs-API-nycklar kan bara inaktiveras, inte tas bort. Fråge-API-nycklar kan tas bort.

Ägar- eller deltagarbehörigheter krävs för att inaktivera funktioner.

Om du vill inaktivera nyckelbaserad autentisering använder du Azure-portalen eller REST-API:et för hantering.

  1. Gå till söktjänsten i Azure-portalen.

  2. I det vänstra navigeringsfönstret väljer du Nycklar.

  3. Välj Rollbaserad åtkomstkontroll.

Ändringen träder i kraft omedelbart, men vänta några sekunder innan du testar. Förutsatt att du har behörighet att tilldela roller som medlem i Ägare, tjänstadministratör eller medadministratör kan du använda portalfunktioner för att testa rollbaserad åtkomst.

Villkorlig åtkomst

Vi rekommenderar villkorsstyrd åtkomst i Microsoft Entra om du behöver tillämpa organisationsprinciper, till exempel multifaktorautentisering.

Följ dessa steg för att aktivera en princip för villkorlig åtkomst för Azure AI Search:

  1. Logga in på Azure-portalen.

  2. Sök efter villkorsstyrd åtkomst i Microsoft Entra.

  3. Välj Principer.

  4. Välj Ny princip.

  5. I avsnittet Molnappar eller åtgärder i principen lägger du till Azure AI Search som en molnapp beroende på hur du vill konfigurera din princip.

  6. Uppdatera de återstående parametrarna för principen. Ange till exempel vilka användare och grupper som den här principen gäller för.

  7. Spara principen.

Viktigt!

Om din söktjänst har tilldelats en hanterad identitet visas den specifika söktjänsten som en molnapp som kan inkluderas eller exkluderas som en del av principen för villkorsstyrd åtkomst. Principer för villkorlig åtkomst kan inte tillämpas på en specifik söktjänst. Kontrollera i stället att du väljer den allmänna Azure AI Search-molnappen .

Felsöka problem med rollbaserad åtkomstkontroll

När du utvecklar program som använder rollbaserad åtkomstkontroll för autentisering kan några vanliga problem uppstå:

  • Om auktoriseringstoken kom från en hanterad identitet och lämpliga behörigheter nyligen har tilldelats kan det ta flera timmar innan dessa behörighetstilldelningar börjar gälla.

  • Standardkonfigurationen för en söktjänst är nyckelbaserad autentisering. Om du inte ändrade standardnyckelinställningen till Både eller Rollbaserad åtkomstkontroll nekas alla begäranden som använder rollbaserad autentisering automatiskt oavsett underliggande behörigheter.