Aktivera eller inaktivera rollbaserad åtkomstkontroll i Azure AI Search

Azure AI Search använder nyckelbaserad autentisering som standard, men har fullt stöd för Microsoft Entra ID-autentisering och auktorisering för alla kontrollplans- och dataplansåtgärder via rollbaserad åtkomstkontroll i Azure (RBAC).

Innan du kan tilldela roller för auktoriserad dataplansåtkomst till Azure AI Search måste du aktivera rollbaserad åtkomstkontroll för din söktjänst. Roller för tjänstadministration (kontrollplan) är inbyggda och kan inte aktiveras eller inaktiveras.

Kommentar

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:er för söktjänsten eller motsvarande Azure SDK-klientbibliotek. Kontrollplan refererar till Azure-resurshantering, till exempel att skapa eller konfigurera en söktjänst.

Förutsättningar

• En söktjänst i valfri region, på valfri nivå, inklusive kostnadsfritt.

• Ägare, administratör för användaråtkomst eller en anpassad roll med Behörigheter för Microsoft.Authorization/roleAssignments/write .

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

Konfigurera söktjänsten för att identifiera ett auktoriseringshuvud för databegäranden som tillhandahåller en OAuth2-åtkomsttoken.

När du aktiverar roller för dataplanet gäller ändringen omedelbart, men vänta några sekunder innan du tilldelar roller.

Standardfelläget för obehöriga begäranden är http401WithBearerChallenge. Du kan också ange felläget till http403.

Azure-portalen

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

2. Välj Inställningar och välj sedan Nycklar i det vänstra navigeringsfönstret.

   

3. Välj Rollbaserad kontroll eller Båda om du för närvarande använder nycklar och behöver tid för att överföra klienter till rollbaserad åtkomstkontroll.

   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.

4. Om du som administratör väljer en metod för endast roller tilldelar du dataplansroller till ditt användarkonto för att återställa fullständig administrativ åtkomst över dataplansåtgärder i Azure Portal. Roller inkluderar Search Service-deltagare, Search Index Data Contributor och Search Index Data Reader. Du behöver de två första rollerna om du vill ha motsvarande åtkomst.

   Ibland kan det ta fem till tio minuter innan rolltilldelningar börjar gälla. Tills det händer visas följande meddelande på de Azure Portal sidor som används för dataplansåtgärder.

   

Azure CLI

Kör det här skriptet för att endast stödja roller:

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

Eller kör det här skriptet för att stödja både nycklar och roller:

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

Mer information finns i Hantera din Azure AI-tjänsten Search med Azure CLI.

Azure PowerShell

Kör det här kommandot om du bara vill ange autentiseringstypen till roller:

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

Eller kör det här kommandot för att stödja både nycklar och roller:

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

Mer information finns i Hantera din Azure AI-tjänsten Search med PowerShell.

REST-API

Använd REST API :et Management Create or Update Service för att konfigurera tjänsten för rollbaserad åtkomstkontroll.

Alla anrop till MANAGEMENT REST API autentiseras via Microsoft Entra-ID. Hjälp med att konfigurera autentiserade begäranden finns i Hantera Azure AI Search med REST.

1. Hämta tjänstinställningar så att du kan granska den aktuella konfigurationen.

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

2. Använd PATCH för att uppdatera tjänstkonfigurationen. Följande ändringar aktiverar både nycklar och rollbaserad åtkomst. Om du vill ha en konfiguration med endast roller kan du läsa Inaktivera API-nycklar.

   Under "egenskaper" anger du "authOptions" till "aadOrApiKey". Egenskapen "disableLocalAuth" måste vara false för att ange "authOptions".

   Du kan också ange "aadAuthFailureMode" för att ange om 401 returneras i stället för 403 när autentiseringen misslyckas. Giltiga värden är "http401WithBearerChallenge" eller "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"
               }
           }
       }
   }
   

Inaktivera rollbaserad åtkomstkontroll

Det går att inaktivera rollbaserad åtkomstkontroll för dataplansåtgärder och använda nyckelbaserad autentisering i stället. Du kan göra detta som en del av ett testarbetsflöde, till exempel för att utesluta behörighetsproblem.

Ångra de steg som du följde tidigare för att aktivera rollbaserad åtkomst.

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

2. Välj Inställningar och välj sedan Nycklar i det vänstra navigeringsfönstret.

3. Välj API-nycklar.

Inaktivera API-nyckelautentisering

Nyckelåtkomst, eller lokal autentisering, kan inaktiveras för din tjänst om du uteslutande 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.

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

Behörigheter som ägare eller deltagare krävs för att inaktivera säkerhetsfunktioner.

Azure-portalen

1. I Azure Portal navigerar du till söktjänsten.

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.

Azure CLI

Om du vill inaktivera nyckelbaserad autentisering anger du -disableLocalAuth till true. Det här är samma syntax som skriptet "aktivera endast roller" som visades i föregående avsnitt.

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

Om du vill återaktivera nyckelautentisering anger du -disableLocalAuth till false. Söktjänsten återupptar godkännandet av API-nycklar på begäran automatiskt (förutsatt att de anges).

Mer information finns i Hantera din Azure AI-tjänsten Search med Azure CLI.

Azure PowerShell

Om du vill inaktivera nyckelbaserad autentisering anger du DisableLocalAuth till true. Det här är samma syntax som skriptet "aktivera endast roller" som visades i föregående avsnitt.

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

Om du vill återaktivera nyckelautentisering anger du DisableLocalAuth till false. Söktjänsten återupptar godkännandet av API-nycklar på begäran automatiskt (förutsatt att de anges).

Mer information finns i Hantera din Azure AI-tjänsten Search med PowerShell.

REST-API

Om du vill inaktivera nyckelbaserad autentisering anger du "disableLocalAuth" till true.

1. Hämta tjänstinställningar så att du kan granska den aktuella konfigurationen.

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

2. Använd PATCH för att uppdatera tjänstkonfigurationen. Följande ändring anger "authOptions" till 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
       }
   }
   

Om du vill återaktivera nyckelautentisering anger du "disableLocalAuth" till false. Söktjänsten återupptar godkännandet av API-nycklar på begäran automatiskt (förutsatt att de anges).

Effekter av rollbaserad åtkomstkontroll

• Rollbaserad åtkomstkontroll kan öka svarstiden för vissa begäranden. Varje unik kombination av tjänstresurs (index, indexerare, kompetensuppsättningar och så vidare) 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 och så vidare), ä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.

Nästa steg

Konfigurera roller för åtkomst till en söktjänst