Verbinding maken met Azure AI Search met behulp van rollen
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
Een zoekservice in elke regio, op elke laag, die is ingeschakeld voor op rollen gebaseerde toegang.
Eigenaar, beheerder van gebruikerstoegang of een aangepaste rol met Microsoft.Authorization/roleAssignments/write-machtigingen .
Ingebouwde rollen die worden gebruikt in Azure AI Search
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:
-
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 Reader
met PowerShell1407120a-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.
Meld u aan bij het Azure-portaal.
Navigeer naar uw zoekservice.
Selecteer Toegangsbeheer (IAM) in het linkernavigatiedeelvenster.
Selecteer + Toevoegen>Roltoewijzing toevoegen.
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)
Selecteer op het tabblad Leden de microsoft Entra-gebruikers- of groepsidentiteit.
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.
Meld u aan bij het Azure-portaal.
Navigeer naar uw zoekservice.
Selecteer Toegangsbeheer (IAM) in het linkernavigatiedeelvenster.
Selecteer + Toevoegen>Roltoewijzing toevoegen.
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.
Selecteer op het tabblad Leden de microsoft Entra-gebruikers- of groepsidentiteit.
Selecteer op het tabblad Beoordelen en toewijzen de optie Beoordelen en toewijzen om de rol toe te wijzen.
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.
Meld u aan bij het Azure-portaal.
Navigeer naar uw zoekservice.
Selecteer Toegangsbeheer (IAM) in het linkernavigatiedeelvenster.
Selecteer + Toevoegen>Roltoewijzing toevoegen.
Selecteer de rol Search Index Data Reader .
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.
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.
Meld u aan bij het Azure-portaal.
Navigeer naar uw zoekservice.
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.
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
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
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.
Laad de
Azure
enAzureAD
modules en maak verbinding met uw Azure-account:Import-Module -Name Az Import-Module -Name AzureAD Connect-AzAccount
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.
Navigeer in Azure Portal naar uw zoekservice.
Selecteer toegangsbeheer (IAM) in het linkernavigatiedeelvenster.
Selecteer Rollen in de actiebalk.
Klik met de rechtermuisknop op Zoekindexgegevenslezer (of een andere rol) en selecteer Klonen om de wizard Een aangepaste rol maken te openen.
Geef op het tabblad Basisinformatie een naam op voor de aangepaste rol, zoals Search Index Data Explorer, en selecteer Vervolgens.
Selecteer Op het tabblad Machtigingen de optie Machtiging toevoegen.
Zoek op het tabblad Machtigingen toevoegen naar en selecteer vervolgens de tegel Microsoft Search .
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.
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": [] } ] } }
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:
Zoek naar voorwaardelijke toegang van Microsoft Entra.
Selecteer Beleidsregels.
Selecteer Nieuw beleid.
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.
Werk de resterende parameters van het beleid bij. Geef bijvoorbeeld op op welke gebruikers en groepen dit beleid van toepassing is.
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.
Feedback
https://aka.ms/ContentUserFeedback.
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie:Feedback verzenden en weergeven voor