Använda API-nycklar för Azure Cognitive Search-autentisering

Cognitive Search erbjuder nyckelbaserad autentisering som primär autentiseringsmetod. För inkommande begäranden till en tjänstslutpunkt för sökning, till exempel begäranden som skapar eller frågar ett index, är API-nycklar det enda allmänt tillgängliga autentiseringsalternativet som du har. Några scenarier för utgående begäranden, särskilt de som rör indexerare, kan använda Azure Active Directory-identiteter och roller.

Anteckning

Rollbaserad åtkomstkontroll i Azure (RBAC) för inkommande begäranden till en sökslutpunkt är nu i förhandsversion. Du kan använda den här förhandsgranskningsfunktionen för att komplettera eller ersätta API-nycklar i sökindexbegäranden.

API-nycklar genereras när tjänsten skapas. Att skicka en giltig API-nyckel i begäran anses vara ett bevis på att begäran kommer från en auktoriserad klient. Det finns två typer av nycklar. Admin nycklar förmedlar skrivbehörigheter för tjänsten och beviljar även behörighet att fråga systeminformation. Frågenycklar förmedlar läsbehörigheter och kan användas av appar för att fråga ett specifikt index.

När du ansluter till en söktjänst måste alla begäranden innehålla en API-nyckel som genererades specifikt för din tjänst.

Du kan visa och hantera API-nycklar i Azure-Portal eller via PowerShell, Azure CLI eller REST API.

Portalsida, avsnittet hämta inställningar, nycklar

Vad är en API-nyckel?

En API-nyckel är en unik sträng som består av slumpmässigt genererade siffror och bokstäver som skickas på varje begäran till söktjänsten. Tjänsten accepterar begäran om både själva begäran och nyckeln är giltiga.

Två typer av nycklar används för att komma åt söktjänsten: administratör (skrivskyddad) och fråga (skrivskyddad).

Nyckel Beskrivning Gränser
Administratör Ger fullständig behörighet till alla åtgärder, inklusive möjligheten att hantera tjänsten, skapa och ta bort index, indexerare och datakällor.

Två administratörsnycklar, som kallas primära och sekundära nycklar i portalen, genereras när tjänsten skapas och kan återskapas individuellt på begäran. Med två nycklar kan du rulla över en nyckel medan du använder den andra nyckeln för fortsatt åtkomst till tjänsten.

Admin nycklar anges endast i HTTP-begärandehuvuden. Du kan inte placera en administratörs-API-nyckel i en URL.
Högst 2 per tjänst
Söka i data Ger skrivskyddad åtkomst till index och dokument och distribueras vanligtvis till klientprogram som utfärdar sökbegäranden.

Frågenycklar skapas på begäran.

Frågenycklar kan anges i en HTTP-begäranderubrik för sökning, förslag eller sökning. Du kan också skicka en frågenyckel som en parameter på en URL. Beroende på hur klientprogrammet formulerar begäran kan det vara enklare att skicka nyckeln som en frågeparameter:

GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]
50 per tjänst

Visuellt finns det ingen skillnad mellan en administratörsnyckel eller frågenyckel. Båda nycklarna är strängar som består av 32 slumpmässigt genererade alfanumeriska tecken. Om du tappar reda på vilken typ av nyckel som anges i ditt program kan du kontrollera nyckelvärdena i portalen.

Anteckning

Det anses vara en dålig säkerhetspraxis att skicka känsliga data, till exempel en api-key i begärande-URI:n. Därför accepterar Azure Cognitive Search bara en frågenyckel som en api-key i frågesträngen, och du bör undvika att göra det om inte innehållet i ditt index ska vara offentligt tillgängligt. Som en allmän regel rekommenderar vi att du skickar som api-key ett begärandehuvud.

Hitta befintliga nycklar

Du kan hämta åtkomstnycklar i portalen eller via PowerShell, Azure CLI eller REST API.

  1. Logga in på Azure-portalen.

  2. Visa en lista över söktjänsterna för din prenumeration.

  3. Välj tjänsten och klicka på Inställningar>nycklar på sidan Översikt för att visa administratörs- och frågenycklar.

    Portalsida, visningsinställningar, nyckelavsnitt

Skapa frågenycklar

Frågenycklar används för skrivskyddad åtkomst till dokument i ett index för åtgärder som riktar sig mot en dokumentsamling. Sök-, filter- och förslagsfrågor är alla åtgärder som tar en frågenyckel. Alla skrivskyddade åtgärder som returnerar systemdata eller objektdefinitioner, till exempel en indexdefinition eller indexeringsstatus, kräver en administratörsnyckel.

Det är viktigt att begränsa åtkomst och åtgärder i klientappar för att skydda söktillgångarna i din tjänst. Använd alltid en frågenyckel i stället för en administratörsnyckel för frågor som kommer från en klientapp.

  1. Logga in på Azure-portalen.

  2. Visa en lista över söktjänsterna för din prenumeration.

  3. Välj tjänsten och klicka på Inställningar>nycklar på sidan Översikt.

  4. Klicka på Hantera frågenycklar.

  5. Använd den frågenyckel som redan har genererats för din tjänst eller skapa upp till 50 nya frågenycklar. Standardfrågenyckeln namnges inte, men ytterligare frågenycklar kan namnges för hanterbarhet.

    Skapa eller använda en frågenyckel

Anteckning

Ett kodexempel som visar användning av frågenycklar finns i DotNetHowTo.

Återskapa administratörsnycklar

Två administratörsnycklar skapas för varje tjänst så att du kan rotera en primärnyckel med hjälp av den sekundära nyckeln för affärskontinuitet.

  1. På sidan Inställningar>nycklar kopierar du den sekundära nyckeln.
  2. För alla program uppdaterar du API-nyckelinställningarna för att använda den sekundära nyckeln.
  3. Återskapa primärnyckeln.
  4. Uppdatera alla program så att de använder den nya primärnyckeln.

Om du oavsiktligt återskapar båda nycklarna samtidigt misslyckas alla klientbegäranden som använder dessa nycklar med HTTP 403 Förbjuden. Innehållet tas dock inte bort och du är inte permanent utelåst.

Du kan fortfarande komma åt tjänsten via portalen eller programmatiskt. Hanteringsfunktioner fungerar via ett prenumerations-ID, inte en tjänst-API-nyckel, och är därför fortfarande tillgängliga även om dina API-nycklar inte är det.

När du har skapat nya nycklar via portalen eller hanteringslagret återställs åtkomsten till ditt innehåll (index, indexerare, datakällor, synonymmappningar) när du har de nya nycklarna och anger dessa nycklar på begäranden.

Säkra API-nycklar

Rolltilldelningar avgör vem som kan läsa och hantera nycklar. Medlemmar i följande roller kan visa och återskapa nycklar: Ägare, Deltagare, Search Service-deltagare. Rollen Läsare har inte åtkomst till API-nycklar.

Prenumerationsadministratörer kan visa och återskapa alla API-nycklar. Som en försiktighetsåtgärd granskar du rolltilldelningar för att förstå vem som har åtkomst till administratörsnycklarna.

  1. Gå till söktjänstsidan i Azure-Portal.
  2. I det vänstra navigeringsfönstret väljer du Åtkomstkontroll (IAM) och sedan fliken Rolltilldelningar .
  3. Ange Omfång till Den här resursen för att visa rolltilldelningar för din tjänst.

Se även