Herstellen einer Verbindung mit Azure AI Search mithilfe der Schlüsselauthentifizierung

Artikel
02/15/2024

Azure AI Search bietet eine schlüsselbasierte Authentifizierung, die Sie für Verbindungen mit Ihrem Suchdienst verwenden können. Ein API-Schlüssel ist eine einzigartige Zeichenfolge aus 52 zufällig generierten Ziffern und Buchstaben. Eine Anforderung an einen Suchdienstendpunkt wird akzeptiert, wenn sowohl die Anforderung als auch der API-Schlüssel gültig sind.

Hinweis

Eine kurze Notiz darüber, wie die Terminologie „Schlüssel“ in Azure AI Search verwendet wird. Ein „API-Schlüssel“, der in diesem Artikel beschrieben wird, bezieht sich auf eine GUID, die für die Authentifizierung einer Anforderung verwendet wird. Ein separater Begriff, „Dokumentschlüssel“, bezieht sich auf eine eindeutige Zeichenfolge in Ihrem indizierten Inhalt, der verwendet wird, um Dokumente in einem Suchindex eindeutig zu identifizieren.

Typen von API-Schlüsseln

Es gibt zwei Arten von Schlüsseln, die für die Authentifizierung einer Anforderung verwendet werden:

Typ	Berechtigungsstufe	Maximum	So wird's erstellt
Administrator	Vollzugriff (Lese-/Schreibzugriff) für alle Inhaltsvorgänge	2 ¹	Für Administratoren werden zwei Schlüssel generiert, wenn der Dienst erstellt wird. Diese werden im Portal als primärer bzw. sekundärer Schlüssel bezeichnet und können bei Bedarf einzeln neu generiert werden.
Abfrage	Schreibgeschützter Zugriff, der auf die Dokumentensammlung eines Suchindex festgelegt ist	50	Ein Abfrageschlüssel wird mit dem Dienst generiert. Mehr können bei Bedarf von einem Suchdienstadministrator erstellt werden.

¹ Durch die Verwendung von zwei Schlüsseln kann weiterhin auf den Dienst zugegriffen werden, während für einen der Schlüssel ein Rollover durchgeführt wird.

Administrator- und Abfrageschlüssel sind rein optisch nicht zu unterscheiden. Bei beiden Schlüsseln handelt es sich um eine Zeichenfolge mit 52 nach dem Zufallsprinzip generierten alphanumerischen Zeichen. Sollten Sie nicht mehr wissen, welche Art von Schlüssel in Ihrer Anwendung angegeben ist, können Sie die Schlüsselwerte im Portal überprüfen.

Verwenden von API-Schlüsseln für Verbindungen

API-Schlüssel werden für Datenebenenanforderungen (Inhaltsanforderungen) verwendet, z. B. zum Erstellen oder Zugreifen auf einen Index oder eine andere Anforderung, die in den Search-REST-APIsdargestellt wird. Bei der Diensterstellung ist ein API-Schlüssel der einzige Authentifizierungsmechanismus für Datenebenenvorgänge, Sie können die Schlüsselauthentifizierung jedoch durch Azure-Rollen ersetzen oder ergänzen, wenn Sie in Ihrem Code keine hartcodierten Schlüssel verwenden können.

API-Schlüssel werden für Clientanforderungen an einen Suchdienst angegeben. Die Übergabe eines gültigen API-Schlüssels bei der Anforderung gilt als Nachweis dafür, dass die Anforderung von einem autorisierten Client stammt. Wenn Sie Objekte erstellen, ändern oder löschen, benötigen Sie einen Administrator-API-Schlüssel. Andernfalls werden Abfrageschlüssel in der Regel an Clientanwendungen verteilt, die Abfragen ausgeben.

Sie können API-Schlüssel in einem Anforderungsheader für REST-API-Aufrufe oder in Code angeben, der die Clientbibliotheken von azure.search.documents in den Azure-SDKs aufruft. Wenn Sie das Azure-Portal zum Ausführen von Aufgaben verwenden, bestimmt Ihre Rollenzuweisung die Zugriffsebene.

Zu den bewährten Methoden für die Verwendung hartcodierter Schlüssel in Quelldateien gehören:

Verwenden Sie API-Schlüssel nur, wenn die Offenlegung von Daten kein Risiko ist (z. B. bei Verwendung von Beispieldaten) und wenn Sie hinter einer Firewall arbeiten. Die Offenlegung von API-Schlüsseln ist ein Risiko für Daten sowie für die nicht autorisierte Verwendung Ihres Suchdiensts.
Überprüfen Sie Ihren Code vor der Veröffentlichung von Beispielen und Schulungsmaterialien immer, um sicherzustellen, dass Sie keine gültigen API-Schlüssel hinterlassen haben.
Wechseln Sie für Produktionsworkloads zu Microsoft Entra ID und rollenbasiertem Zugriff. Oder, wenn Sie auch weiterhin API-Schlüssel verwenden möchten, sollten Sie auch immer überwachen, wer Zugriff auf Ihre API-Schlüssel hat, und API-Schlüssel in regelmäßigen Abständen neu generieren.

Verwendung von API-Schlüsseln im Azure-Portal:

Die Schlüsselauthentifizierung ist integriert. Standardmäßig versucht das Portal zuerst API-Schlüssel. Wenn Sie jedoch API-Schlüssel deaktivieren und Rollenzuweisungen einrichten, verwendet das Portal stattdessen Rollenzuweisungen.

Verwendung von API-Schlüsseln in PowerShell:

Legen Sie API-Schlüssel im Anforderungsheader mithilfe der folgenden Syntax fest:

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

Ein Skriptbeispiel, das die API-Schlüsselverwendung für verschiedene Vorgänge zeigt, finden Sie in der Schnellstartanleitung: Erstellen eines Azure AI Search-Index in PowerShell mithilfe von REST-APIs.

Verwendung von API-Schlüsseln in REST-Aufrufen:

Legen Sie einen Administratorschlüssel im Anforderungsheader fest. Sie können keine Administratorschlüssel für den URI oder im Textkörper der Anforderung übergeben.

Administratorschlüssel werden für den Erstellen-Lesen-Aktualisieren-Löschen-Vorgang und für Anforderungen verwendet, die an den Suchdienst selbst ausgestellt wurden, z. B. das Auflisten von Objekten oder das Anfordern von Dienststatistiken.

Abfrageschlüssel werden für Such-, Vorschlags- oder Nachschlagevorgänge verwendet, die auf die index/docs-Sammlungen abzielen. Legen Sie für POST im Anforderungsheader api-key fest. Oder setzen Sie den Schlüssel auf den URI für einen GET: GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]

Hinweis

Aus Sicherheitsgründen sollten im Anforderungs-URI keine vertraulichen Daten wie etwa ein API-Schlüssel (api-key) übergeben werden. Aus diesem Grund akzeptiert Azure AI Search nur einen Abfrageschlüssel als api-key in der Abfragezeichenfolge. Wir empfehlen generell, api-key als Anforderungsheader zu übergeben.

Berechtigungen zum Anzeigen oder Verwalten von API-Schlüsseln

Berechtigungen zum Anzeigen und Verwalten von API-Schlüsseln werden über Rollenzuweisungenvermittelt. Mitglieder der folgenden Rollen können Schlüssel anzeigen und erneut generieren:

Besitzer
Mitwirkender
Mitwirkender von Suchdienst
Administrator und Co-Administrator (klassisch)

Die folgenden Rollen haben keinen Zugriff auf API-Schlüssel:

Leser
Mitwirkender an Suchindexdaten
Suchindexdatenleser

Suchen vorhandener Schlüssel

Sie können API-Schlüssel im Azure-Portal oder über PowerShell, Azure CLI oder REST-API anzeigen und verwalten.

Melden Sie sich beim Azure-Portal an, und finden Sie Ihren Suchdienst.
Wählen Sie unter Einstellungen die Option Schlüssel aus, um Administrator- und Abfrageschlüssel anzuzeigen.

Installieren Sie das Az.Search-Modul:
```
Install-Module Az.Search
```

Rückgabe von Administratorschlüsseln:

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

Rückgabeabfrageschlüssel:

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

Verwenden Sie die folgenden Befehle, um Administrator- bzw. Abfrage-API-Schlüssel zurückzugeben:

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

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

Verwenden Sie Listenadministratorschlüssel oder Listenabfrageschlüssel in der Verwaltungs-REST-API, um API-Schlüssel zurückzugeben.

Sie müssen über eine gültige Rollenzuweisung verfügen, um API-Schlüssel zurückzugeben oder zu aktualisieren. Unter Verwalten Ihres Azure AI Search-Diensts mit REST-APIs finden Sie Anleitungen zur Erfüllung von Rollenanforderungen mithilfe der REST-APIs.

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

Erstellen von Abfrageschlüsseln

Abfrageschlüssel werden für den schreibgeschützten Zugriff auf Dokumente in einem Index für die Vorgänge für eine Dokumentensammlung verwendet. Such-, Filter- und Vorschlagsabfragen sind Vorgänge, die einen Abfrageschlüssel verwenden. Alle schreibgeschützten Vorgänge, die Systemdaten oder Objektdefinitionen zurückgeben, z. B. eine Indexdefinition oder einen Indexerstatus, erfordern einen Administratorschlüssel.

Das Einschränken des Zugriffs und der Vorgänge in Client-Apps ist besonders wichtig, um die Suchobjekte in Ihrem Dienst zu schützen. Verwenden Sie für Abfragen aus einer Client-App immer einen Abfrageschlüssel anstelle eines Administratorschlüssels.

Melden Sie sich beim Azure-Portal an, und finden Sie Ihren Suchdienst.
Wählen Sie unter Einstellungen die Option Schlüssel aus, um API-Schlüssel anzuzeigen.
Verwenden Sie unter Abfrageschlüssel verwalten den für Ihren Dienst bereits generierten Abfrageschlüssel, oder erstellen Sie neue Abfrageschlüssel. Der Standardabfrageschlüssel ist nicht benannt, aber andere generierte Abfrageschlüssel können zur Verwaltbarkeit benannt werden.

Verwenden Sie Abfrageschlüssel erstellen in der Verwaltungs-REST-API.

Sie müssen über eine gültige Rollenzuweisung verfügen, um API-Schlüssel zu erstellen oder zu verwalten. Unter Verwalten Ihres Azure AI Search-Diensts mit REST-APIs finden Sie Anleitungen zur Erfüllung von Rollenanforderungen mithilfe der REST-APIs.

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

Erneutes Generieren von Administratorschlüsseln

Für jeden Dienst werden zwei Administratorschlüssel erstellt, sodass Sie einen Primärschlüssel rotieren können, während Sie einen Sekundärschlüssel für Geschäftskontinuität verwenden.

Wählen Sie unter Einstellungen die Option Schlüssel aus, und kopieren Sie dann den sekundären Schlüssel.
Aktualisieren Sie für alle Anwendungen die Einstellungen des API-Schlüssels so, dass der Sekundärschlüssel verwendet wird.
Generieren Sie den Primärschlüssel neu.
Aktualisieren Sie alle Anwendungen so, dass sie den neuen Primärschlüssel verwenden.

Wenn Sie versehentlich beide Schlüssel gleichzeitig neu generieren, wird für alle Clientanforderungen, die diese Schlüssel verwenden, der Fehler „HTTP 403 – Verboten“ zurückgegeben. Inhalte werden jedoch nicht gelöscht und Sie werden nicht dauerhaft gesperrt.

Sie können weiterhin über das Portal oder programmatisch auf den Dienst zugreifen. Verwaltungsfunktionen werden über eine Abonnement-ID und nicht einen Dienst-API-Schlüssel verwendet und sind daher auch dann verfügbar, wenn Ihre API-Schlüssel nicht verfügbar sind.

Nach der Erstellung neuer Schlüssel über das Portal oder die Verwaltungsebene wird der Zugriff auf Ihre Inhalte (Indizes, Indexer, Datenquellen, Synonymzuordnungen) wiederhergestellt, sobald Sie die neuen Schlüssel haben und nach Aufforderung angeben.

Sichern von API-Schlüsseln

Verwenden Sie Rollenzuweisungen, um den Zugriff auf API-Schlüssel einzuschränken.

Beachten Sie, dass es nicht möglich ist, die vom Kunden verwaltete Schlüsselverschlüsselung zum Verschlüsseln von API-Schlüsseln zu verwenden. Nur vertrauliche Daten innerhalb des Suchdienstes selbst (z. B. Indexinhalt oder Verbindungszeichenfolgen in Datenquellenobjektdefinitionen) können CMK-verschlüsselt werden.

Navigieren Sie im Azure-Portal zur Seite Ihres Suchdiensts.
Wählen Sie im linken Navigationsbereich Zugriffssteuerung (IAM) und anschließend die Registerkarte Rollenzuweisungen aus.
Wählen Sie im Rollenfilter die Rollen aus, die über die Berechtigung zum Anzeigen oder Verwalten von Schlüsseln verfügen (Besitzer, Mitwirkender, Suchdienstmitwirkender). Die resultierenden Sicherheitsprinzipale, die diesen Rollen zugewiesen sind, verfügen über Schlüsselberechtigungen für Ihren Suchdienst.
Überprüfen Sie als Vorsichtsmaßnahme auch die Registerkarte Klassische Administratoren, um festzustellen, ob Administratoren und Co-Administratoren Zugriff haben.