Aktivera eller inaktivera rollbaserad åtkomstkontroll i Azure AI Search

Azure AI Search stöder både nyckellös och nyckelbaserad autentisering för alla kontrollplans- och dataplansåtgärder. Du kan använda Microsoft Entra ID-autentisering och auktorisering för alla kontrollplans- och dataplansåtgärder via rollbaserad åtkomstkontroll i Azure (RBAC).

Viktigt!

När du skapar en söktjänst är nyckelbaserad autentisering standard, men det är inte det säkraste alternativet. Vi rekommenderar att du ersätter den med rollbaserad åtkomst enligt beskrivningen i den här artikeln.

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 gå till söktjänsten.

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

   

3. Välj Rollbaserad kontroll. Välj endast 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 (rekommenderas)	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.

Så här inaktiverar du rollbaserad åtkomstkontroll i Azure Portal:

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).

Nästa steg

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