Verbinding maken met Cognitive Search met behulp van sleutelverificatie

Artikel
03/25/2023
7 minuten om te lezen

Cognitive Search biedt verificatie op basis van sleutels die u kunt gebruiken voor verbindingen met uw zoekservice. Een API-sleutel is een unieke tekenreeks die bestaat uit 52 willekeurig gegenereerde cijfers en letters. Een aanvraag naar een zoekservice-eindpunt wordt geaccepteerd als zowel de aanvraag als de API-sleutel geldig zijn.

Notitie

Een korte opmerking over hoe 'sleutel'-terminologie wordt gebruikt in Cognitive Search. Een 'API-sleutel', die in dit artikel wordt beschreven, verwijst naar een GUID die wordt gebruikt voor het verifiëren van een aanvraag. Een afzonderlijke term, 'documentsleutel', verwijst naar een unieke tekenreeks in uw geïndexeerde inhoud die wordt gebruikt om documenten in een zoekindex uniek te identificeren.

Typen API-sleutels

Er zijn twee soorten sleutels die worden gebruikt voor het verifiëren van een aanvraag:

Type	Machtigingsniveau	Maximum	Hoe gemaakt
Beheerder	Volledige toegang (lezen/schrijven) voor alle inhoudsbewerkingen	2 ¹	Twee beheersleutels, in de portal primaire en secundaire sleutels genoemd, worden gegenereerd wanneer de service wordt gemaakt en kunnen op aanvraag afzonderlijk opnieuw worden gegenereerd.
Query’s uitvoeren	Alleen-lezentoegang, gericht op de documentenverzameling van een zoekindex	50	Er wordt één querysleutel gegenereerd met de service. Meer kan op aanvraag worden gemaakt door een zoekservicebeheerder.

¹ Als u er twee hebt, kunt u één sleutel overschakelen terwijl u de tweede sleutel gebruikt voor continue toegang tot de service.

Visueel gezien is er geen onderscheid tussen een beheerderssleutel of een querysleutel. Beide sleutels zijn tekenreeksen die bestaan uit 52 willekeurig gegenereerde alfanumerieke tekens. Als u niet meer weet welk type sleutel is opgegeven in uw toepassing, kunt u de sleutelwaarden controleren in de portal.

API-sleutels gebruiken voor verbindingen

API-sleutels worden gebruikt voor gegevensvlakaanvragen (inhoud), zoals het maken of openen van een index of een andere aanvraag die wordt weergegeven in de REST API's voor zoeken. Bij het maken van de service is een API-sleutel het enige verificatiemechanisme voor gegevensvlakbewerkingen, maar u kunt sleutelverificatie vervangen of aanvullen met Azure-rollen als u geen in code vastgelegde sleutels in uw code kunt gebruiken.

API-sleutels worden opgegeven voor clientaanvragen voor een zoekservice. Het doorgeven van een geldige API-sleutel voor de aanvraag wordt beschouwd als bewijs dat de aanvraag afkomstig is van een geautoriseerde client. Als u objecten maakt, wijzigt of verwijdert, hebt u een api-sleutel voor de beheerder nodig. Anders worden querysleutels doorgaans gedistribueerd naar clienttoepassingen die query's uitvoeren.

U kunt API-sleutels opgeven in een aanvraagheader voor REST API-aanroepen of in code die de azure.search.documents-clientbibliotheken in de Azure SDK's aanroept. Als u de Azure Portal gebruikt om taken uit te voeren, bepaalt uw roltoewijzing het toegangsniveau.

Aanbevolen procedures voor het gebruik van in code vastgelegde sleutels in bronbestanden zijn onder andere:

Gebruik tijdens vroege ontwikkeling en proof-of-concept-tests wanneer de beveiliging losser is, voorbeeldgegevens of openbare gegevens.
Voor volwassen oplossingen of productiescenario's schakelt u over naar Azure Active Directory en toegang op basis van rollen om de noodzaak van in code vastgelegde sleutels te elimineren. Als u API-sleutels wilt blijven gebruiken, moet u altijd controleren wie toegang heeft tot uw API-sleutels en api-sleutels regelmatig opnieuw genereren .

Sleutelverificatie is ingebouwd, dus er is geen actie vereist. De portal gebruikt standaard API-sleutels om de aanvraag automatisch te verifiëren. Als u echter API-sleutels uitschakelt en roltoewijzingen instelt, gebruikt de portal in plaats daarvan roltoewijzingen.

In Cognitive Search kunnen de meeste taken worden uitgevoerd in Azure Portal, waaronder het maken van objecten, het indexeren via de wizard Gegevens importeren en query's via Search Explorer.

Stel API-sleutels in de aanvraagheader in met behulp van de volgende syntaxis:

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

Een voorbeeldscript met het gebruik van API-sleutels voor verschillende bewerkingen vindt u in Quickstart: Een Azure Cognitive Search-index maken in PowerShell met behulp van REST API's.

Stel een beheerderssleutel in de aanvraagheader in met behulp van de syntaxis api-key die gelijk is aan uw sleutel. Beheer sleutels worden gebruikt voor de meeste bewerkingen, waaronder maken, verwijderen en bijwerken. Beheer sleutels worden ook gebruikt voor aanvragen die zijn verzonden naar de zoekservice zelf, zoals het weergeven van objecten of het aanvragen van servicestatistieken. Zie Verbinding maken met Azure Cognitive Search met behulp van REST API's voor een meer gedetailleerd voorbeeld.

Querysleutels worden gebruikt voor zoek-, suggestie- of opzoekbewerkingen die gericht zijn op de index/docs verzameling. Stel voor POST api-key in de aanvraagheader in. Of plaats de sleutel op de URI voor een GET: GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]

Notitie

Het wordt beschouwd als een slechte beveiligingspraktijk om gevoelige gegevens, zoals een api-key in de aanvraag-URI, door te geven. Daarom accepteert Azure Cognitive Search alleen een querysleutel als een api-key in de queryreeks. Als algemene regel raden we u aan om uw api-key door te geven als aanvraagheader.

Machtigingen voor het weergeven of beheren van API-sleutels

Machtigingen voor het weergeven en beheren van API-sleutels worden overgebracht via roltoewijzingen. Leden van de volgende rollen kunnen sleutels weergeven en opnieuw genereren:

Eigenaar
Inzender
Inzender voor zoekservice
Beheerder en medebeheerder (klassiek)

De volgende rollen hebben geen toegang tot API-sleutels:

Lezer
Inzender voor zoekindexgegevens
Lezer voor zoekindexgegevens

Bestaande sleutels zoeken

U kunt API-sleutels weergeven en beheren in de Azure Portal of via PowerShell, Azure CLI of REST API.

Meld u aan bij de Azure Portal en zoek uw zoekservice.
Selecteer onder Instellingende optie Sleutels om beheerders- en querysleutels weer te geven.

Installeer de Az.Search module:
```
Install-Module Az.Search
```

Beheersleutels retourneren:

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

Querysleutels retourneren:

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

Gebruik de volgende opdrachten om respectievelijk beheerders- en query-API-sleutels te retourneren:

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

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

Gebruik List Beheer Keys of List Query Keys in de Management REST API om API-sleutels te retourneren.

U moet een geldige roltoewijzing hebben om API-sleutels te retourneren of bij te werken. Zie Uw Azure Cognitive Search-service beheren met REST API's voor hulp bij het voldoen aan rolvereisten met behulp van de REST API's.

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

Querysleutels maken

Querysleutels worden gebruikt voor alleen-lezentoegang tot documenten in een index voor bewerkingen die gericht zijn op een documentenverzameling. Zoek-, filter- en suggestiequery's zijn allemaal bewerkingen waarvoor een querysleutel wordt gebruikt. Voor elke alleen-lezenbewerking die systeemgegevens of objectdefinities retourneert, zoals een indexdefinitie of indexeerfunctiestatus, is een beheerderssleutel vereist.

Het beperken van toegang en bewerkingen in client-apps is essentieel voor het beveiligen van de zoekassets in uw service. Gebruik altijd een querysleutel in plaats van een beheerderssleutel voor query's die afkomstig zijn van een client-app.

Meld u aan bij de Azure Portal en zoek uw zoekservice.
Selecteer onder Instellingende optie Sleutels om API-sleutels weer te geven.
Gebruik onder Querysleutels beheren de querysleutel die al is gegenereerd voor uw service of maak nieuwe querysleutels. De standaardquerysleutel heeft geen naam, maar andere gegenereerde querysleutels kunnen een naam krijgen voor beheerbaarheid.

Gebruik Querysleutels maken in de MANAGEMENT REST API.

U moet een geldige roltoewijzing hebben om API-sleutels te kunnen maken of beheren. Zie Uw Azure Cognitive Search-service beheren met REST API's voor hulp bij het voldoen aan rolvereisten met behulp van de REST API's.

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

Beheersleutels opnieuw genereren

Er worden twee beheersleutels gemaakt voor elke service, zodat u een primaire sleutel kunt roteren terwijl u de secundaire sleutel gebruikt voor bedrijfscontinuïteit.

Selecteer onder Instellingende optie Sleutels en kopieer vervolgens de secundaire sleutel.
Werk voor alle toepassingen de api-sleutelinstellingen bij om de secundaire sleutel te gebruiken.
Genereer de primaire sleutel opnieuw.
Werk alle toepassingen bij om de nieuwe primaire sleutel te gebruiken.

Als u per ongeluk beide sleutels tegelijk opnieuw genereert, mislukken alle clientaanvragen met behulp van deze sleutels met HTTP 403 Verboden. Inhoud wordt echter niet verwijderd en u wordt niet permanent vergrendeld.

U hebt nog steeds toegang tot de service via de portal of programmatisch. Beheerfuncties zijn actief via een abonnements-id en geen service-API-sleutel en zijn dus nog steeds beschikbaar, zelfs als uw API-sleutels dat niet zijn.

Nadat u nieuwe sleutels hebt gemaakt via de portal of beheerlaag, wordt de toegang tot uw inhoud (indexen, indexeerfuncties, gegevensbronnen, synoniementoewijzingen) hersteld zodra u deze sleutels voor aanvragen hebt opgegeven.

Api-sleutels beveiligen

Gebruik roltoewijzingen om de toegang tot API-sleutels te beperken.

Houd er rekening mee dat het niet mogelijk is om door de klant beheerde sleutelversleuteling te gebruiken om API-sleutels te versleutelen. Alleen gevoelige gegevens binnen de zoekservice zelf (bijvoorbeeld indexinhoud of verbindingsreeksen in objectdefinities van gegevensbronnen) kunnen cmk-versleuteld zijn.

Ga naar de pagina van de zoekservice in Azure Portal.
Selecteer in het linkernavigatiedeelvenster Toegangsbeheer (IAM) en selecteer vervolgens het tabblad Roltoewijzingen .
Selecteer in het filter Rol de rollen die gemachtigd zijn om sleutels weer te geven of te beheren (Eigenaar, Inzender, Inzender voor zoekservice). De resulterende beveiligingsprincipals die aan deze rollen zijn toegewezen, hebben sleutelmachtigingen voor uw zoekservice.
Als voorzorgsmaatregel controleert u ook het tabblad Klassieke beheerders om te bepalen of beheerders en medebeheerders toegang hebben.