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

Artikel
04/28/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.

Die schlüsselbasierte Authentifizierung ist der Standard. Sie können es deaktivieren, wenn Sie die rollenbasierte Authentifizierung abonnieren.

Hinweis

Eine kurzer Hinweis auf die wichtigste Terminologie. Ein API-Schlüssel ist ein GUID, der für die Authentifizierung verwendet wird. Ein separater Begriff, Dokumentschlüssel, bezieht sich auf eine eindeutige Zeichenfolge in Ihrem indizierten Inhalt, der Dokumente in einem Suchindex eindeutig identifiziert.

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-APIs dargestellt 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.

Administratorschlüssel werden zum Erstellen, Ändern oder Löschen von Objekten verwendet. Administratorschlüssel werden auch für GET-Objektdefinitionen und Systeminformationen verwendet.

Abfrageschlüssel werden in der Regel an Clientanwendungen verteilt, die Abfragen ausgeben.

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, wie z. B. LIST-Indizes oder Abrufen von Dienststatistiken.

Hier finden Sie ein Beispiel für die Verwendung des Administrator-API-Schlüssels für eine Anforderung zum Erstellen eines Indexes:

### Create an index
POST {{baseUrl}}/indexes?api-version=2023-11-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 }
         ]
   }

Legen Sie einen Abfrageschlüssel in einem Anforderungsheader für POST fest oder im URI für GET. Abfrageschlüssel werden für Vorgänge verwendet, die auf die index/docs-Sammlung abzielen: Dokumente durchsuchen, Autovervollständigen, Vorschlag oder Dokument abrufen.

Nachfolgend finden Sie ein Beispiel für die Verwendung von API-Schlüsseln für eine Anforderung zum Durchsuchen von Dokumenten:

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

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.

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.

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.

Es ist nicht möglich, die Verschlüsselung durch kundenseitig verwaltete Schlüssel 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.

Bewährte Methoden

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.