Ansluta till Azure AI Search med hjälp av nycklar

Artikel
10/30/2024

Azure AI Search erbjuder nyckelbaserad autentisering för anslutningar till din söktjänst. En API-nyckel är en unik sträng som består av 52 slumpmässigt genererade siffror och bokstäver. I källkoden kan du ange den som en miljövariabel eller som en appinställning i projektet och sedan referera till variabeln på begäran. En begäran som görs till en slutpunkt för söktjänsten godkänns om både begäran och API-nyckeln är giltiga.

Nyckelbaserad autentisering är standard.

Du kan ersätta den med rollbaserad åtkomst, vilket eliminerar behovet av hårdkodade nycklar i din kodbas.

Typer av API-nycklar

Det finns två typer av nycklar som används för att autentisera en begäran:

Typ	Behörighetsnivå	Högsta	Så här skapas
Administratör	Fullständig åtkomst (läs-och-skrivbehörighet) för alla innehållsåtgärder	2 ¹	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.
Fråga	Skrivskyddad åtkomst, begränsad till dokumentsamlingen för ett sökindex	50	En frågenyckel genereras med tjänsten. Fler kan skapas på begäran av en administratör för söktjänsten.

¹ Om du har två kan du rulla över en nyckel medan du använder den andra nyckeln för fortsatt åtkomst till tjänsten.

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

Använda API-nycklar för anslutningar

API-nycklar används för begäranden om dataplan (innehåll), till exempel att skapa eller komma åt ett index eller någon annan begäran som visas i REST-API:erna för sökning. När tjänsten skapas är en API-nyckel den enda autentiseringsmekanismen för dataplansåtgärder, men du kan ersätta eller komplettera nyckelautentisering med Azure-roller om du inte kan använda hårdkodade nycklar i koden.

Administratörsnycklar används för att skapa, ändra eller ta bort objekt. Administratörsnycklar används också för GET-objektdefinitioner och systeminformation.

Frågenycklar distribueras vanligtvis till klientprogram som utfärdar frågor.

Så här används API-nycklar i REST-anrop:

Ange en administratörsnyckel i begärandehuvudet. Du kan inte skicka administratörsnycklar på URI:n eller i brödtexten i begäran. Administratörsnycklar används för åtgärden create-read-update-delete och för begäranden som utfärdas till själva söktjänsten, till exempel LIST-index eller GET-tjänststatistik.

Här är ett exempel på admin-API-nyckelanvändning för en begäran om att skapa index:

### Create an index
POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{adminApiKey}}

    {
        "name": "my-new-index",  
        "fields": [
            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "Name", "type": "Edm.String", "searchable": true }
         ]
   }

Ange en frågenyckel i ett begärandehuvud för POST eller på URI:n för GET. Frågenycklar används för åtgärder som riktar sig till index/docs samlingen: Sök dokument, komplettera automatiskt, Föreslå eller HÄMTA dokument.

Här är ett exempel på fråge-API-nyckelanvändning i en GET-begäran (Search Documents):

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2024-07-01&api-key={{queryApiKey}}

Kommentar

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 AI Search endast en frågenyckel som en api-key i frågesträngen. Som en allmän regel rekommenderar vi att du skickar huvudet api-key som en begäran.

Så här används API-nycklar i PowerShell:

Ange API-nycklar i begärandehuvudet med följande syntax:

$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

Ett skriptexempel som visar API-nyckelanvändning för olika åtgärder finns i Snabbstart: Skapa ett Azure AI Search-index i PowerShell med hjälp av REST-API:er.

Behörigheter för att visa eller hantera API-nycklar

Behörigheter för att visa och hantera API-nycklar förmedlas via rolltilldelningar. Medlemmar i följande roller kan visa och återskapa nycklar:

Ägare
Deltagare
Söktjänstdeltagare
Administratör och medadministratör (klassisk)

Följande roller har inte åtkomst till API-nycklar:

Läsare
Search Index Data Contributor
Dataläsare för sökindex

Hitta befintliga nycklar

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

Logga in på Azure Portal och hitta söktjänsten.
Under Inställningar väljer du Nycklar för att visa administratörs- och frågenycklar.

Installera modulen Az.Search :
```
Install-Module Az.Search
```

Returnera administratörsnycklar:

Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Returnera frågenycklar:

Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Använd följande kommandon för att returnera administratörs- respektive fråge-API-nycklar:

az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>

az search query-key list --resource-group <myresourcegroup> --service-name <myservice>

Använd listadministratörsnycklar eller frågenycklar i hanterings-REST-API:et för att returnera API-nycklar.

Du måste ha en giltig rolltilldelning för att returnera eller uppdatera API-nycklar. Mer information om hur du uppfyller rollkraven med hjälp av REST-API:er finns i Hantera azure AI-tjänsten Search med REST-API:er.

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01

Skapa frågenycklar

Frågenycklar används för skrivskyddad åtkomst till dokument i ett index för åtgärder som riktar sig till 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.

Logga in på Azure Portal och hitta söktjänsten.
Under Inställningar väljer du Nycklar för att visa API-nycklar.
Under Hantera frågenycklar använder du den frågenyckel som redan har genererats för din tjänst eller skapar nya frågenycklar. Standardfrågenyckeln namnges inte, men andra genererade frågenycklar kan namnges för hanterbarhet.

Använd Create Query Keys (Skapa frågenycklar ) i REST API för hantering.

Du måste ha en giltig rolltilldelning för att skapa eller hantera API-nycklar. Mer information om hur du uppfyller rollkraven med hjälp av REST-API:er finns i Hantera azure AI-tjänsten Search med REST-API:er.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2023-11-01

Återskapa administratörsnycklar

Två administratörsnycklar skapas för varje tjänst så att du kan rotera en primärnyckel när du använder den sekundära nyckeln för affärskontinuitet.

Under Inställningar väljer du Nycklar och kopierar sedan den sekundära nyckeln.
För alla program uppdaterar du API-nyckelinställningarna så att den sekundära nyckeln används.
Återskapa primärnyckeln.
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, synonymkartor) när du har angett dessa nycklar på begäranden.

Säkra API-nycklar

Använd rolltilldelningar för att begränsa åtkomsten till API-nycklar.

Det går inte att använda kundhanterad nyckelkryptering för att kryptera API-nycklar. Endast känsliga data i själva söktjänsten (till exempel indexinnehåll eller anslutningssträng i datakällobjektdefinitioner) kan vara CMK-krypterade.

Gå till söktjänstsidan i Azure Portal.
I det vänstra navigeringsfönstret väljer du Åtkomstkontroll (IAM) och sedan fliken Rolltilldelningar .
I filtret Roll väljer du de roller som har behörighet att visa eller hantera nycklar (ägare, deltagare, söktjänstdeltagare). De resulterande säkerhetsobjekt som tilldelats dessa roller har nyckelbehörigheter för din söktjänst.
Som en försiktighetsåtgärd kontrollerar du även fliken Klassiska administratörer för att avgöra om administratörer och medadministratörer har åtkomst.

Bästa praxis

Använd endast API-nycklar om avslöjande av data inte är en risk (till exempel när du använder exempeldata) och om du arbetar bakom en brandvägg. Exponering av API-nycklar är en risk för både data och obehörig användning av din söktjänst.
Kontrollera alltid kod, exempel och utbildningsmaterial innan du publicerar för att se till att du inte lämnade giltiga API-nycklar kvar.
För produktionsarbetsbelastningar växlar du till Microsoft Entra-ID och rollbaserad åtkomst. Om du vill fortsätta använda API-nycklar bör du alltid övervaka vem som har åtkomst till dina API-nycklar och återskapa API-nycklar med jämna mellanrum.

Dela via