Verbinding maken met Cognitive Search met behulp van sleutelverificatie

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 bij 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 worden twee soorten sleutels gebruikt voor het verifiëren van een aanvraag:

Type Machtigingsniveau Maximum Hoe gemaakt
Beheerder Volledige toegang (lezen/schrijven) voor alle inhoudsbewerkingen 2 1 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 kunnen op aanvraag worden gemaakt door een beheerder van een zoekservice.

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

Visueel 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 (inhoudsaanvragen), zoals het maken of openen van een index of een andere aanvraag die wordt weergegeven in de SEARCH REST API's. 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 beheer-API-sleutel 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 waarmee de azure.search.documents-clientbibliotheken in de Azure SDK's worden aangeroepen. 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:

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, indexeren via de wizard Gegevens importeren en query's via Search Explorer.

Notitie

Het wordt beschouwd als een slechte beveiligingspraktijk om gevoelige gegevens door te geven, zoals een api-key in de aanvraag-URI. Daarom accepteert Azure Cognitive Search alleen een querysleutel als een api-key in de queryreeks. Als algemene regel raden we u aan 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:

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.

  1. Meld u aan bij de Azure Portal en zoek uw zoekservice.

  2. Selecteer onder Instellingende optie Sleutels om beheerders- en querysleutels weer te geven.

Schermopname van een portalpagina met API-sleutels.

Querysleutels maken

Querysleutels worden gebruikt voor alleen-lezentoegang tot documenten in een index voor bewerkingen die zijn gericht op een documentenverzameling. Zoek-, filter- en suggestiequery's zijn allemaal bewerkingen die een querysleutel gebruiken. 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 elke query die afkomstig is van een client-app.

  1. Meld u aan bij de Azure Portal en zoek uw zoekservice.

  2. Selecteer onder Instellingende optie Sleutels om API-sleutels weer te geven.

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

    Schermopname van de opties voor het beheer van querysleutels.

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.

  1. Selecteer onder Instellingende optie Sleutels en kopieer vervolgens de secundaire sleutel.

  2. Werk voor alle toepassingen de api-sleutelinstellingen bij om de secundaire sleutel te gebruiken.

  3. Genereer de primaire sleutel opnieuw.

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

  1. Ga naar de pagina van de zoekservice in Azure Portal.

  2. Selecteer in het linkernavigatiedeelvenster Toegangsbeheer (IAM) en selecteer vervolgens het tabblad Roltoewijzingen .

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

  4. Als voorzorgsmaatregel controleert u ook het tabblad Klassieke beheerders om te bepalen of beheerders en medebeheerders toegang hebben.

Zie ook