Herstellen einer Verbindung mit Azure KI-Suche mithilfe von Schlüsseln

Azure KI-Suche bietet eine schlüsselbasierte Authentifizierung für Verbindungen mit Ihrem Suchdienst. Ein API-Schlüssel ist eine einzigartige Zeichenfolge aus 52 zufällig generierten Ziffern und Buchstaben. Im Quellcode können Sie sie als Umgebungsvariable oder als App-Einstellung in Ihrem Projekt angeben und dann auf die Variable für die Anforderung verweisen. 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 sie durch rollenbasierten Zugriff ersetzen, wodurch die Notwendigkeit hartcodierter Schlüssel in Ihrer Codebasis entfällt.

Typen von API-Schlüsseln

Es gibt zwei Arten von Schlüsseln, die für die Authentifizierung einer Anforderung verwendet 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.

### 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 }
         ]
   }

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

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

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.

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

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

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.

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.

1. Wählen Sie unter Einstellungen die Option Schlüssel aus, und kopieren Sie dann den sekundären Schlüssel.

2. Aktualisieren Sie für alle Anwendungen die Einstellungen des API-Schlüssels so, dass der Sekundärschlüssel verwendet wird.

3. Generieren Sie den Primärschlüssel neu.

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

1. Navigieren Sie im Azure-Portal zur Seite Ihres Suchdiensts.

2. Wählen Sie im linken Navigationsbereich Zugriffssteuerung (IAM) und anschließend die Registerkarte Rollenzuweisungen aus.

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

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

Weitere Informationen

• Sicherheit in Azure AI Search
• Rollenbasierte Azure-Zugriffssteuerung in Azure AI Search
• Verwalten mit PowerShell