Op rollen gebaseerd toegangsbeheer in- of uitschakelen in Azure AI Search

Azure AI Search maakt standaard gebruik van verificatie op basis van sleutels, maar biedt volledige ondersteuning voor Verificatie en autorisatie van Microsoft Entra-id's voor alle bewerkingen in het besturingsvlak en gegevensvlak via op rollen gebaseerd toegangsbeheer van Azure (RBAC).

Voordat u rollen voor geautoriseerde toegang tot het gegevensvlak tot Azure AI Search kunt toewijzen, moet u op rollen gebaseerd toegangsbeheer inschakelen voor uw zoekservice. Rollen voor servicebeheer (besturingsvlak) zijn ingebouwd en kunnen niet worden ingeschakeld of uitgeschakeld.

Notitie

Het gegevensvlak verwijst naar bewerkingen op basis van het eindpunt van de zoekservice, zoals indexering of query's, of een andere bewerking die is opgegeven in de REST API's van de Search Service of equivalente Azure SDK-clientbibliotheken. Het besturingsvlak verwijst naar Azure-resourcebeheer, zoals het maken of configureren van een zoekservice.

Vereisten

• Een zoekservice in elke regio, op elke laag, inclusief gratis.

• Eigenaar, beheerder van gebruikerstoegang of een aangepaste rol met Microsoft.Authorization/roleAssignments/write-machtigingen .

Op rollen gebaseerde toegang inschakelen voor gegevensvlakbewerkingen

Configureer uw zoekservice voor het herkennen van een autorisatieheader voor gegevensaanvragen die een OAuth2-toegangstoken bieden.

Wanneer u rollen voor het gegevensvlak inschakelt, wordt de wijziging onmiddellijk doorgevoerd, maar wacht u enkele seconden voordat u rollen toewijst.

De standaardfoutmodus voor niet-geautoriseerde aanvragen is http401WithBearerChallenge. U kunt ook de foutmodus instellen op http403.

Azure-portal

1. Meld u aan bij Azure Portal en open de zoekservicepagina.

2. Selecteer Instellingen en selecteer vervolgens Sleutels in het linkernavigatiedeelvenster.

   

3. Kies Op rollen gebaseerd besturingselement of Beide als u momenteel sleutels gebruikt en tijd nodig hebt om clients over te zetten naar op rollen gebaseerd toegangsbeheer.

   Optie	Omschrijving
   API-sleutel	(standaard). Vereist API-sleutels in de aanvraagheader voor autorisatie.
   Op rollen gebaseerd toegangsbeheer	Vereist lidmaatschap van een roltoewijzing om de taak te voltooien. Er is ook een autorisatieheader voor de aanvraag vereist.
   Beide	Aanvragen zijn geldig met behulp van een API-sleutel of op rollen gebaseerd toegangsbeheer, maar als u beide in dezelfde aanvraag opgeeft, wordt de API-sleutel gebruikt.

4. Als beheerder, als u een benadering met alleen rollen kiest, wijst u gegevensvlakrollen toe aan uw gebruikersaccount om volledige beheerderstoegang te herstellen via gegevensvlakbewerkingen in Azure Portal. Rollen zijn onder andere Inzender voor zoekservice, Inzender voor zoekindexgegevens en Lezer van zoekindexgegevens. U hebt de eerste twee rollen nodig als u gelijkwaardige toegang wilt.

   Soms kan het vijf tot tien minuten duren voordat roltoewijzingen van kracht worden. Tot dat gebeurt, wordt het volgende bericht weergegeven op de Azure Portal-pagina's die worden gebruikt voor bewerkingen in het gegevensvlak.

   

Azure-CLI

Voer dit script uit om alleen rollen te ondersteunen:

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

Of voer dit script uit om zowel sleutels als rollen te ondersteunen:

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --aad-auth-failure-mode http401WithBearerChallenge `
  --auth-options aadOrApiKey

Zie Uw Azure AI-Search-service beheren met de Azure CLI voor meer informatie.

Azure PowerShell

Voer deze opdracht uit om alleen het verificatietype in te stellen op rollen:

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

Of voer deze opdracht uit om zowel sleutels als rollen te ondersteunen:

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -AuthOption AadOrApiKey

Zie Uw Azure AI-Search-service beheren met PowerShell voor meer informatie.

REST API

Gebruik de BEHEER REST API Create of Update Service om uw service te configureren voor op rollen gebaseerd toegangsbeheer.

Alle aanroepen naar de Management REST API worden geverifieerd via Microsoft Entra-id. Zie Azure AI Search beheren met REST voor hulp bij het instellen van geverifieerde aanvragen.

1. Service-instellingen ophalen zodat u de huidige configuratie kunt controleren.

   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
   

2. Gebruik PATCH om de serviceconfiguratie bij te werken. Met de volgende wijzigingen zijn zowel sleutels als op rollen gebaseerd toegang mogelijk. Zie API-sleutels uitschakelen als u een configuratie met alleen rollen wilt.

   Stel onder 'properties' 'authOptions' in op aadOrApiKey. De eigenschap disableLocalAuth moet onwaar zijn om 'authOptions' in te stellen.

   Stel desgewenst 'aadAuthFailureMode' in om op te geven of 401 wordt geretourneerd in plaats van 403 wanneer de verificatie mislukt. Geldige waarden zijn http401WithBearerChallenge of http403.

   PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
   {
       "properties": {
           "disableLocalAuth": false,
           "authOptions": {
               "aadOrApiKey": {
                   "aadAuthFailureMode": "http401WithBearerChallenge"
               }
           }
       }
   }
   

Op rollen gebaseerd toegangsbeheer uitschakelen

Het is mogelijk om op rollen gebaseerd toegangsbeheer uit te schakelen voor bewerkingen in het gegevensvlak en in plaats daarvan verificatie op basis van sleutels te gebruiken. U kunt dit doen als onderdeel van een testwerkstroom, bijvoorbeeld om machtigingsproblemen uit te sluiten.

Draai de stappen die u eerder hebt gevolgd om op rollen gebaseerde toegang in te schakelen.

1. Meld u aan bij Azure Portal en open de zoekservicepagina.

2. Selecteer Instellingen en selecteer vervolgens Sleutels in het linkernavigatiedeelvenster.

3. Selecteer API-sleutels.

VERIFICATIE van API-sleutel uitschakelen

Sleuteltoegang, of lokale verificatie, kan worden uitgeschakeld op uw service als u exclusief gebruikmaakt van de ingebouwde rollen en Microsoft Entra-verificatie. Als u API-sleutels uitschakelt, weigert de zoekservice alle gegevensgerelateerde aanvragen die een API-sleutel doorgeven in de header.

Beheer-API-sleutels kunnen worden uitgeschakeld, maar niet verwijderd. Query-API-sleutels kunnen worden verwijderd.

Machtigingen voor eigenaar of inzender zijn vereist om beveiligingsfuncties uit te schakelen.

Azure-portal

1. Navigeer in Azure Portal naar uw zoekservice.

2. Selecteer Sleutels in het linkernavigatiedeelvenster.

3. Selecteer op rollen gebaseerd toegangsbeheer.

De wijziging is onmiddellijk van kracht, maar wacht enkele seconden voordat u gaat testen. Ervan uitgaande dat u gemachtigd bent om rollen toe te wijzen als lid van eigenaar, servicebeheerder of coadministrator, kunt u portalfuncties gebruiken om op rollen gebaseerde toegang te testen.

Azure-CLI

Als u verificatie op basis van sleutels wilt uitschakelen, stelt u -disableLocalAuth in op true. Dit is dezelfde syntaxis als het script 'alleen rollen inschakelen' dat in de vorige sectie wordt weergegeven.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

Als u sleutelverificatie opnieuw wilt inschakelen, stelt u -disableLocalAuth in op false. De zoekservice hervat de acceptatie van API-sleutels op de aanvraag automatisch (ervan uitgaande dat deze zijn opgegeven).

Zie Uw Azure AI-Search-service beheren met de Azure CLI voor meer informatie.

Azure PowerShell

Als u verificatie op basis van sleutels wilt uitschakelen, stelt u DisableLocalAuth in op true. Dit is dezelfde syntaxis als het script 'alleen rollen inschakelen' dat in de vorige sectie wordt weergegeven.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

Als u sleutelverificatie opnieuw wilt inschakelen, stelt u DisableLocalAuth in op false. De zoekservice hervat de acceptatie van API-sleutels op de aanvraag automatisch (ervan uitgaande dat deze zijn opgegeven).

Zie Uw Azure AI-Search-service beheren met PowerShell voor meer informatie.

REST API

Als u verificatie op basis van sleutels wilt uitschakelen, stelt u 'disableLocalAuth' in op true.

1. Service-instellingen ophalen zodat u de huidige configuratie kunt controleren.

   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
   

2. Gebruik PATCH om de serviceconfiguratie bij te werken. Met de volgende wijziging wordt 'authOptions' ingesteld op null.

   PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
   {
       "properties": {
           "disableLocalAuth": true
       }
   }
   

Als u sleutelverificatie opnieuw wilt inschakelen, stelt u DisableLocalAuth in op False. De zoekservice hervat de acceptatie van API-sleutels op de aanvraag automatisch (ervan uitgaande dat deze zijn opgegeven).

Effecten van op rollen gebaseerd toegangsbeheer

• Op rollen gebaseerd toegangsbeheer kan de latentie van sommige aanvragen verhogen. Elke unieke combinatie van serviceresources (index, indexeerfunctie, vaardighedensets 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.

Volgende stappen

Rollen instellen voor toegang tot een zoekservice