Delen via

Verbinding maken met Azure AI Search met behulp van rollen

  • Artikel

Azure biedt een globaal verificatie- en op rollen gebaseerd autorisatiesysteem voor alle services die op het platform worden uitgevoerd. In Azure AI Search kunt u Azure-rollen toewijzen voor:

Toegang per gebruiker via zoekresultaten (ook wel beveiliging op rijniveau of beveiliging op documentniveau genoemd) wordt niet ondersteund via roltoewijzingen. Als tijdelijke oplossing kunt u beveiligingsfilters maken die de resultaten op gebruikersidentiteit bijsnijden, waardoor documenten worden verwijderd waarvoor de aanvrager geen toegang mag hebben. Bekijk dit voorbeeld van een Enterprise-chat met behulp van RAG voor een demonstratie.

Roltoewijzingen zijn cumulatief en verspreid over alle hulpprogramma's en clientbibliotheken. U kunt rollen toewijzen met behulp van een van de ondersteunde benaderingen die worden beschreven in documentatie voor op rollen gebaseerd toegangsbeheer van Azure.

Op rollen gebaseerde toegang is optioneel, maar wordt aanbevolen. Het alternatief is verificatie op basis van sleutels. Dit is de standaardinstelling.

Vereisten

De volgende rollen zijn ingebouwd. Als deze rollen onvoldoende zijn, maakt u een aangepaste rol.

Role Vliegtuig Beschrijving
Eigenaar Control & Data Volledige toegang tot het besturingsvlak van de zoekresource, inclusief de mogelijkheid om Azure-rollen toe te wijzen. Alleen de rol Eigenaar kan verificatieopties in- of uitschakelen of rollen voor andere gebruikers beheren. Abonnementsbeheerders zijn standaard leden.

Op het gegevensvlak heeft deze rol dezelfde toegang als de rol Inzender voor de zoekservice. Het bevat toegang tot alle gegevensvlakacties, behalve de mogelijkheid om documenten op te vragen of te indexeren.
Inzender Control & Data Hetzelfde niveau van toegang tot het besturingsvlak als eigenaar, minus de mogelijkheid om rollen toe te wijzen of verificatieopties te wijzigen.

Op het gegevensvlak heeft deze rol dezelfde toegang als de rol Inzender voor de zoekservice. Het bevat toegang tot alle gegevensvlakacties, behalve de mogelijkheid om documenten op te vragen of te indexeren.
Lezer Control & Data Leestoegang voor de hele service, inclusief metrische zoekgegevens, metrische gegevens over inhoud (verbruikte opslag, aantal objecten) en de objectdefinities van gegevensvlakbronnen (indexen, indexeerfuncties, enzovoort). Api-sleutels kunnen echter niet worden gelezen of inhoud in indexen worden gelezen.
Inzender voor zoekservice Control & Data Lees-schrijftoegang tot objectdefinities (indexen, aliassen, synoniemenkaarten, indexeerfuncties, gegevensbronnen en vaardighedensets). Deze rol is bedoeld voor ontwikkelaars die objecten maken en beheerders die een zoekservice en de bijbehorende objecten beheren, maar zonder toegang tot indexinhoud. Gebruik deze rol om indexen te maken, te verwijderen en weer te geven, indexdefinities op te halen, servicegegevens (statistieken en quota' op te halen), analyseanalyses te testen, synoniemenkaarten, indexeerfuncties, gegevensbronnen en vaardighedensets te maken en te beheren. Zie Microsoft.Search/searchServices/* voor de lijst met machtigingen.
Inzender voor zoekindexgegevens Gegevens Lees-schrijftoegang tot inhoud in indexen. Deze rol is bedoeld voor ontwikkelaars of indexeigenaren die de documentenverzameling van een index moeten importeren, vernieuwen of er query's op moeten uitvoeren. Deze rol biedt geen ondersteuning voor het maken of beheren van indexen. Deze rol is standaard bedoeld voor alle indexen in een zoekservice. Zie Toegang verlenen tot één index om het bereik te beperken.
Zoekindexgegevenslezer Gegevens Alleen-lezentoegang voor het uitvoeren van query's op zoekindexen. Deze rol is bedoeld voor apps en gebruikers die query's uitvoeren. Deze rol biedt geen ondersteuning voor leestoegang tot objectdefinities. U kunt bijvoorbeeld geen definitie van een zoekindex lezen of zoekservicestatistieken ophalen. Deze rol is standaard bedoeld voor alle indexen in een zoekservice. Zie Toegang verlenen tot één index om het bereik te beperken.

Combineer deze rollen om voldoende machtigingen te krijgen voor uw use-case.

Notitie

Als u op rollen gebaseerde toegang van Azure uitschakelt, zijn ingebouwde rollen voor het besturingsvlak (Eigenaar, Inzender, Lezer) nog steeds beschikbaar. Als u op rollen gebaseerde toegang uitschakelt, worden alleen de gegevensmachtigingen verwijderd die aan deze rollen zijn gekoppeld. Als de rollen van het gegevensvlak zijn uitgeschakeld, is De inzender voor de zoekservice gelijk aan de inzender van het besturingsvlak.

Rollen toewijzen

Wijs in deze sectie rollen toe voor:

  • Servicebeheer

    Role Id
    Owner 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
    Contributor b24988ac-6180-42a0-ab88-20f7382dd24c
    Reader acdd72a7-3385-48ef-bd42-f606fba81ae7

  • Ontwikkeling of schrijftoegang tot een zoekservice

    Opdracht Role Id
    CRUD-bewerkingen Search Service Contributor 7ca78c08-252a-4471-8644-bb5ff32d4ba0
    Documenten laden, indexeringstaken uitvoeren Search Index Data Contributor 8ebe5a00-799e-43f5-93ac-243d3dce84a7
    Een query op uitvoeren op een index Search Index Data Reader 1407120a-92aa-4202-b7e9-c0e197c71c8f

  • Alleen-lezentoegang voor query's

    Role Id
    Search Index Data Readermet PowerShell 1407120a-92aa-4202-b7e9-c0e197c71c8f

Rollen toewijzen voor servicebeheer

Als servicebeheerder kunt u een zoekservice maken en configureren en alle besturingsvlakbewerkingen uitvoeren die worden beschreven in de Management REST API of gelijkwaardige clientbibliotheken. Afhankelijk van de rol kunt u ook de meeste rest API-taken voor zoeken in gegevensvlakken uitvoeren.

  1. Meld u aan bij het Azure-portaal.

  2. Navigeer naar uw zoekservice.

  3. Selecteer Toegangsbeheer (IAM) in het linkernavigatiedeelvenster.

  4. Selecteer + Toevoegen>Roltoewijzing toevoegen.

  5. Selecteer een toepasselijke rol:

    • Eigenaar (volledige toegang tot alle bewerkingen van het gegevensvlak en besturingsvlak, met uitzondering van querymachtigingen)
    • Inzender (hetzelfde als eigenaar, met uitzondering van machtigingen voor het toewijzen van rollen)
    • Lezer (acceptabel voor bewaking en weergave van metrische gegevens)

  6. Selecteer op het tabblad Leden de microsoft Entra-gebruikers- of groepsidentiteit.

  7. Selecteer op het tabblad Beoordelen en toewijzen de optie Beoordelen en toewijzen om de rol toe te wijzen.

Rollen toewijzen voor ontwikkeling

Roltoewijzingen zijn globaal in de zoekservice. Als u machtigingen voor één index wilt instellen, gebruikt u PowerShell of de Azure CLI om een aangepaste rol te maken.

Een andere combinatie van rollen die volledige toegang biedt, is Inzender of Eigenaar, plus Search Index Data Reader.

Belangrijk

Als u op rollen gebaseerde toegang configureert voor een service of index en u ook een API-sleutel opgeeft voor de aanvraag, gebruikt de zoekservice de API-sleutel om te verifiëren.

  1. Meld u aan bij het Azure-portaal.

  2. Navigeer naar uw zoekservice.

  3. Selecteer Toegangsbeheer (IAM) in het linkernavigatiedeelvenster.

  4. Selecteer + Toevoegen>Roltoewijzing toevoegen.

    De pagina Toegangsbeheer (IAM) met het menu Roltoewijzing toevoegen geopend.

  5. Selecteer een rol:

    • Inzender voor zoekservice (bewerkingen voor het maken en bijwerken/verwijderen van indexen, indexeerfuncties, vaardighedensets en andere objecten op het hoogste niveau)
    • Inzender voor zoekindexgegevens (documenten laden en indexeringstaken uitvoeren)
    • Search Index Data Reader (een query uitvoeren op een index)

    Een andere combinatie van rollen die volledige toegang biedt, is Inzender of Eigenaar, plus Search Index Data Reader.

  6. Selecteer op het tabblad Leden de microsoft Entra-gebruikers- of groepsidentiteit.

  7. Selecteer op het tabblad Beoordelen en toewijzen de optie Beoordelen en toewijzen om de rol toe te wijzen.

  8. Herhaal dit voor de andere rollen. De meeste ontwikkelaars hebben alle drie nodig.

Rollen toewijzen voor alleen-lezenquery's

Gebruik de rol Search Index Data Reader voor apps en processen die alleen leestoegang tot een index nodig hebben.

Dit is een zeer specifieke rol. Het verleent GET- of POST-toegang tot de documentenverzameling van een zoekindex voor zoekopdrachten, automatisch aanvullen en suggesties. Het biedt geen ondersteuning voor GET- of LIST-bewerkingen op een index of andere objecten op het hoogste niveau, of GET-servicestatistieken.

Deze sectie bevat basisstappen voor het instellen van de roltoewijzing en is hier voor volledigheid, maar we raden u aan Azure AI Search zonder sleutels te gebruiken voor uitgebreide instructies voor het configureren van uw app voor op rollen gebaseerde toegang.

  1. Meld u aan bij het Azure-portaal.

  2. Navigeer naar uw zoekservice.

  3. Selecteer Toegangsbeheer (IAM) in het linkernavigatiedeelvenster.

  4. Selecteer + Toevoegen>Roltoewijzing toevoegen.

  5. Selecteer de rol Search Index Data Reader .

  6. Selecteer op het tabblad Leden de microsoft Entra-gebruikers- of groepsidentiteit. Als u machtigingen voor een andere service instelt, gebruikt u mogelijk een door een systeem of door de gebruiker beheerde identiteit. Kies deze optie als de roltoewijzing voor een service-id is.

  7. Selecteer op het tabblad Beoordelen en toewijzen de optie Beoordelen en toewijzen om de rol toe te wijzen.

Roltoewijzingen testen

Gebruik een client om roltoewijzingen te testen. Houd er rekening mee dat rollen cumulatief en overgenomen rollen zijn die zijn afgestemd op het niveau van het abonnement of de resourcegroep, niet kunnen worden verwijderd of geweigerd op het niveau van de resource (zoekservice).

Configureer uw toepassing voor sleutelloze verbindingen en stel roltoewijzingen in voordat u gaat testen.

  1. Meld u aan bij het Azure-portaal.

  2. Navigeer naar uw zoekservice.

  3. Selecteer op de pagina Overzicht het tabblad Indexen :

    • Inzenders voor zoekservices kunnen elk object bekijken en maken, maar kunnen geen documenten laden of een query uitvoeren op een index. Als u machtigingen wilt controleren, maakt u een zoekindex.

    • Inzenders voor zoekindexgegevens kunnen documenten laden. Er is geen optie documenten laden in de portal buiten de wizard Gegevens importeren, maar u kunt een indexeerfunctie opnieuw instellen en uitvoeren om de machtigingen voor het laden van documenten te bevestigen.

    • Lezers van zoekindexgegevens kunnen een query uitvoeren op de index. Gebruik Search Explorer om machtigingen te verifiëren. U moet query's kunnen verzenden en resultaten kunnen weergeven, maar u kunt de indexdefinitie niet weergeven of er een maken.

Testen als huidige gebruiker

Als u al een inzender of eigenaar van uw zoekservice bent, kunt u een bearer-token voor uw gebruikersidentiteit presenteren voor verificatie bij Azure AI Search.

  1. Een Bearer-token ophalen voor de huidige gebruiker met behulp van de Azure CLI:

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

    Of met behulp van PowerShell:

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

  2. Plak deze variabelen in een nieuw tekstbestand in Visual Studio Code.

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

  3. Plak in en verzend vervolgens een aanvraag om de toegang te bevestigen. Hier volgt een query op de index 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
     }

Toegang verlenen tot één index

In sommige scenario's wilt u de toegang van een toepassing tot één resource beperken, zoals een index.

De portal biedt momenteel geen ondersteuning voor roltoewijzingen op dit niveau van granulariteit, maar kan worden uitgevoerd met PowerShell of de Azure CLI.

Gebruik in PowerShell New-AzRoleAssignment, waarbij u de Azure-gebruikers- of groepsnaam en het bereik van de toewijzing oplevert.

  1. Laad de Azure en AzureAD modules en maak verbinding met uw Azure-account:

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

  2. Voeg een roltoewijzing toe die is afgestemd op een afzonderlijke 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>"

Een aangepaste rol maken

Als ingebouwde rollen niet de juiste combinatie van machtigingen bieden, kunt u een aangepaste rol maken ter ondersteuning van de bewerkingen die u nodig hebt.

In dit voorbeeld wordt de zoekindexgegevenslezer gekloond en wordt vervolgens de mogelijkheid toegevoegd om indexen op naam weer te geven. Normaal gesproken wordt het weergeven van de indexen voor een zoekservice beschouwd als een beheerrecht.

Deze stappen zijn afgeleid van aangepaste Azure-rollen maken of bijwerken met behulp van Azure Portal. Klonen van een bestaande rol wordt ondersteund op een zoekservicepagina.

Met deze stappen maakt u een aangepaste rol waarmee zoekqueryrechten worden uitgebreid, zodat indexen op naam worden opgenomen. Het vermelden van indexen wordt doorgaans beschouwd als een beheerfunctie.

  1. Navigeer in Azure Portal naar uw zoekservice.

  2. Selecteer toegangsbeheer (IAM) in het linkernavigatiedeelvenster.

  3. Selecteer Rollen in de actiebalk.

  4. Klik met de rechtermuisknop op Zoekindexgegevenslezer (of een andere rol) en selecteer Klonen om de wizard Een aangepaste rol maken te openen.

  5. Geef op het tabblad Basisinformatie een naam op voor de aangepaste rol, zoals Search Index Data Explorer, en selecteer Vervolgens.

  6. Selecteer Op het tabblad Machtigingen de optie Machtiging toevoegen.

  7. Zoek op het tabblad Machtigingen toevoegen naar en selecteer vervolgens de tegel Microsoft Search .

  8. Stel de machtigingen voor uw aangepaste rol in. Boven aan de pagina gebruikt u de standaardselectie Acties :

    • Selecteer onder Microsoft.Search/operations de optie Lezen: alle beschikbare bewerkingen weergeven.
    • Selecteer Onder Microsoft.Search/searchServices/indexen de optie Lezen: Index lezen.

  9. Schakel op dezelfde pagina over naar gegevensacties en selecteer onder Microsoft.Search/searchServices/indexen/documenten de optie Lezen: Documenten lezen.

    De JSON-definitie ziet er als volgt uit:

    {
 "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. Selecteer Beoordelen en maken om de rol te maken. U kunt nu gebruikers en groepen toewijzen aan de rol.

Voorwaardelijke toegang

Microsoft Entra voorwaardelijke toegang wordt aangeraden als u organisatiebeleid wilt afdwingen, zoals meervoudige verificatie.

Voer de volgende stappen uit om een beleid voor voorwaardelijke toegang in te schakelen voor Azure AI Search:

  1. Meld u aan bij de Azure-portal.

  2. Zoek naar voorwaardelijke toegang van Microsoft Entra.

  3. Selecteer Beleidsregels.

  4. Selecteer Nieuw beleid.

  5. Voeg in de sectie Cloud-apps of -acties van het beleid Azure AI Search toe als een cloud-app, afhankelijk van hoe u uw beleid wilt instellen.

  6. Werk de resterende parameters van het beleid bij. Geef bijvoorbeeld op op welke gebruikers en groepen dit beleid van toepassing is.

  7. Sla het beleid op.

Belangrijk

Als aan uw zoekservice een beheerde identiteit is toegewezen, wordt de specifieke zoekservice weergegeven als een cloud-app die kan worden opgenomen of uitgesloten als onderdeel van het beleid voor voorwaardelijke toegang. Beleid voor voorwaardelijke toegang kan niet worden afgedwongen voor een specifieke zoekservice. Zorg er in plaats daarvan voor dat u de algemene Azure AI Search-cloud-app selecteert.

Beperkingen

  • Op rollen gebaseerd toegangsbeheer kan de latentie van sommige aanvragen verhogen. Elke unieke combinatie van serviceresources (index, indexeerfunctie, enzovoort) en service-principal activeert een autorisatiecontrole. Deze autorisatiecontroles kunnen maximaal 200 milliseconden aan latentie per aanvraag toevoegen.

  • In zeldzame gevallen waarin aanvragen afkomstig zijn van een groot aantal verschillende service-principals, die allemaal gericht zijn op verschillende servicebronnen (indexen, indexeerfuncties, enzovoort), is het mogelijk dat de autorisatiecontroles leiden tot beperking. Beperking vindt alleen plaats als er binnen een seconde honderden unieke combinaties van zoekserviceresources en service-principals worden gebruikt.

Problemen met op rollen gebaseerd toegangsbeheer oplossen

Bij het ontwikkelen van toepassingen die gebruikmaken van op rollen gebaseerd toegangsbeheer voor verificatie, kunnen er enkele veelvoorkomende problemen optreden:

  • Als het autorisatietoken afkomstig is van een beheerde identiteit en de juiste machtigingen onlangs zijn toegewezen, kan het enkele uren duren voordat deze machtigingentoewijzingen van kracht worden.

  • De standaardconfiguratie voor een zoekservice is verificatie op basis van sleutels. Als u de standaardsleutelinstelling niet hebt gewijzigd in Zowel of op rollen gebaseerd toegangsbeheer, worden alle aanvragen met verificatie op basis van rollen automatisch geweigerd, ongeacht de onderliggende machtigingen.