Share via

Herstellen einer Verbindung mit der Azure KI-Suche mithilfe von rollenbasierten Zugriffssteuerungen

  • Artikel

Azure bietet ein globales Autorisierungssystem mit rollenbasierter Zugriffssteuerung für alle Dienste, die auf der Plattform ausgeführt werden. In Azure KI Search können Sie Azure-Rollen für Folgendes verwenden:

  • Vorgänge auf der Steuerungsebene (Dienstverwaltungsaufgaben über Azure Resource Manager).

  • Vorgänge auf der Datenebene, z. B. Erstellen, Laden und Abfragen von Indizes.

Benutzerbasierter Zugriff über Suchergebnisse (zuweilen als Sicherheit auf Zeilenebene oder Sicherheit auf Dokumentebene bezeichnet) wird nicht unterstützt. Zur Problemumgehung erstellen Sie Sicherheitsfilter, um die Ergebnisse basierend auf der Benutzeridentität einzuschränken, sodass Dokumente entfernt werden, auf die der Anforderer keinen Zugriff haben sollte.

Hinweis

Eine kurzer Hinweis zur Terminologie. Steuerungsebene bezieht sich auf Vorgänge, die von der Verwaltungs-REST-API oder entsprechenden Clientbibliotheken unterstützt werden. Datenebene bezieht sich auf Vorgänge für den Suchdienstendpunkt, z. B. Indizierung oder Abfragen, oder auf andere Vorgänge, die in der REST-API für die Suche oder entsprechenden Clientbibliotheken angegeben sind.

Die folgenden Rollen sind integriert. Wenn diese Rollen nicht ausreichen, erstellen Sie eine benutzerdefinierte Rolle.

Role Plane Beschreibung
Besitzer Daten steuern Vollzugriff auf die Steuerungsebene der Suchressource, einschließlich Fähigkeit zum Zuweisen von Azure-Rollen. Nur die Rolle „Besitzer“ kann Authentifizierungsoptionen aktivieren oder deaktivieren oder Rollen für andere Benutzer verwalten. Abonnementadministratoren sind standardmäßig Mitglieder.

Auf der Datenebene verfügt diese Rolle über dieselben Zugriffsrechte wie die Rolle „Mitwirkender von Suchdienst“. Sie umfasst Zugriff auf alle Aktionen auf Datenebene, außer der Fähigkeit, Dokumente abzufragen oder zu indizieren.
Mitwirkender Daten steuern Gleiche Zugriffsebene auf die Steuerungsebene wie Besitzer, jedoch ohne die Fähigkeit, Rollen zuzuweisen oder Authentifizierungsoptionen zu ändern.

Auf der Datenebene verfügt diese Rolle über dieselben Zugriffsrechte wie die Rolle „Mitwirkender von Suchdienst“. Sie umfasst Zugriff auf alle Aktionen auf Datenebene, außer der Fähigkeit, Dokumente abzufragen oder zu indizieren.
Leser Daten steuern Lesezugriff auf den gesamten Dienst, einschließlich Suchmetriken, Inhaltsmetriken (belegter Speicher, Anzahl der Objekte) und die Objektdefinitionen von Datenebenenressourcen (Indizes, Indexer und so weiter) lesen. API-Schlüssel oder Inhalte in Indizes können jedoch nicht gelesen werden.
Mitwirkender von Suchdienst Daten steuern Lese-/Schreibzugriff auf Objektdefinitionen (Indizes, Aliase, Synonymzuordnungen, Indexer, Datenquellen und Skillsets). Diese Rolle ist für Entwickler, die Objekte erstellen, und Administratoren vorgesehen, die einen Suchdienst und seine Objekte verwalten, aber ohne Zugriff auf Indexinhalte. Verwenden Sie diese Rolle zum Erstellen, Löschen und Auflisten von Indizes, zum Abrufen von Indexdefinitionen, zum Abrufen von Dienstinformationen (Statistiken und Kontingente), zum Testen von Analysetools sowie zum Erstellen und Verwalten von Synonymzuordnungen, Indexern, Datenquellen und Skillsets. Besuchen Sie für die Berechtigungsliste Microsoft.Search/searchServices/*.
Mitwirkender an Suchindexdaten Daten Lese-/Schreibzugriff auf Inhalte in Indizes. Diese Rolle ist für Entwickler oder Indexbesitzer gedacht, die die Dokumentsammlung eines Index importieren, aktualisieren oder abfragen müssen. Diese Rolle unterstützt keine Indexerstellung oder -verwaltung. Diese Rolle ist standardmäßig für alle Indizes in einem Suchdienst vorgesehen. Weitere Informationen zum Eingrenzen des Bereichs finden Sie unter Gewähren des Zugriffs auf einen einzelnen Index.
Suchindexdatenleser Daten Schreibgeschützter Zugriff zum Abfragen von Suchindizes. Diese Rolle ist für Apps und Benutzer gedacht, die Abfragen ausführen. Diese Rolle unterstützt keinen Lesezugriff auf Objektdefinitionen. Sie können z. B. keine Suchindexdefinition lesen oder Suchdienststatistiken abrufen. Diese Rolle ist standardmäßig für alle Indizes in einem Suchdienst vorgesehen. Weitere Informationen zum Eingrenzen des Bereichs finden Sie unter Gewähren des Zugriffs auf einen einzelnen Index.

Hinweis

Wenn Sie den rollenbasierten Azure-Zugriff deaktivieren, stehen weiterhin integrierte Rollen für die Steuerungsebene (Besitzer, Mitwirkender, Leser) zur Verfügung. Durch das Deaktivieren des rollenbasierten Zugriffs werden nur die datenbezogenen Berechtigungen entfernt, die diesen Rollen zugeordnet sind. Wenn Datenebenenrollen deaktiviert werden, entspricht der Suchdienstmitwirkende dem Mitwirkenden der Steuerungsebene.

Begrenzungen

  • Die Einführung der rollenbasierten Zugriffssteuerung kann die Latenz einiger Anforderungen erhöhen. Jede eindeutige Kombination aus Dienstressource (Index, Indexer usw.) und Dienstprinzipal, die für eine Anforderung verwendet wird, löst eine Autorisierungsprüfung aus. Diese Autorisierungsprüfungen können einer Anforderung eine Latenz von bis zu 200 Millisekunden hinzufügen.

  • In seltenen Fällen, in denen Anforderungen von einer großen Anzahl unterschiedlicher Dienstprinzipale stammen, die alle auf verschiedene Dienstressourcen (Indizes, Indexer usw.) abzielen, ist es möglich, dass die Autorisierungsprüfungen zu einer Drosselung führen. Eine Drosselung würde nur dann passieren, wenn innerhalb einer Sekunde Hunderte eindeutiger Kombinationen aus Suchdienstressource und Dienstprinzipal verwendet würden.

Konfigurieren der rollenbasierten Zugriffssteuerung (Role Based Access Control, RBAC) für die Datenebene

Gilt für: Mitwirkender an Suchindexdaten, Suchindexdatenleser, Suchdienstmitwirkender

In diesem Schritt konfigurieren Sie Ihren Dienst so, dass er einen Autorisierungsheader bei Datenanforderungen erkennt, die ein OAuth2-Token für den Zugriff enthalten.

  1. Melden Sie sich am Azure-Portal an und öffnen Sie die Suchdienstseite.

  2. Wählen Sie im linken Navigationsbereich Schlüssel aus.

    Screenshot der Seite „Schlüssel“ mit Authentifizierungsoptionen.

  3. Wählen Sie eine API-Zugangskontrolle Option. Wir empfehlen beides, wenn Sie Flexibilität wünschen oder Apps migrieren müssen.

    Option Beschreibung
    API-Schlüssel (Standard). Erfordert zur Autorisierung einen Administrator- oder Abfrage-API-Schlüssel im Anforderungsheader. Es werden keine Rollen verwendet.
    Rollenbasierte Zugriffssteuerung Zur Ausführung der Aufgabe ist die Mitgliedschaft in einer Rollenzuweisung erforderlich, wie im nächsten Schritt beschrieben. Außerdem ist ein Autorisierungsheader erforderlich.
    Beides Anforderungen sind entweder mit einem API-Schlüssel oder einer rollenbasierten Zugriffssteuerung gültig.

Die Änderung ist sofort wirksam, warten Sie aber einige Sekunden vor dem Testen.

Alle Netzwerkaufrufe für Suchdienstvorgänge und Inhalte respektieren die von Ihnen ausgewählte Option: API-Schlüssel, Bearertoken oder eines von beiden, wenn Sie beide auswählen.

Wenn Sie die rollenbasierte Zugriffssteuerung im Portal aktivieren, lautet der Fehlermodus "http401WithBearerChallenge", wenn die Autorisierung fehlschlägt.

Zuweisen von Rollen

Rollenzuweisungen sind kumulativ und gelten in allen Tools und Clientbibliotheken. Sie können Rollen mit einer der in der Dokumentation zur rollenbasierten Zugriffssteuerung in Azure beschriebenen unterstützten Methode zuweisen.

Sie müssen Besitzer sein oder über die Berechtigung Microsoft.Authorization/roleAssignments/write verfügen, um Rollenzuweisungen zu verwalten.

Rollenzuweisungen im Portal gelten dienstweit. Wenn Sie einem einzelnen Index Berechtigungen erteilen möchten, verwenden Sie stattdessen PowerShell oder die Azure CLI.

  1. Melden Sie sich beim Azure-Portal an.

  2. Navigieren Sie zu Ihrem Suchdienst.

  3. Wählen Sie im linken Navigationsbereich Access Control (IAM) aus.

  4. Wählen Sie +Hinzufügen>Rollenzuweisung hinzufügen aus.

    Seite „Zugriffssteuerung (IAM)“ mit geöffnetem Menü „Rollenzuweisung hinzufügen“

  5. Wählen Sie eine entsprechende Rolle aus:

    • Besitzer
    • Mitwirkender
    • Leser
    • Mitwirkender von Suchdienst
    • Mitwirkender an Suchindexdaten
    • Suchindexdatenleser

  6. Wählen Sie auf der Registerkarte „Mitglieder“ die Microsoft Entra-Benutzer- oder Gruppenidentität aus.

  7. Wählen Sie auf der Registerkarte Überprüfen und zuweisen die Option Überprüfen und zuweisen aus, um die Rolle zuzuweisen.

Testen von Rollenzuweisungen

Verwenden Sie einen Client, um Rollenzuweisungen zu testen. Denken Sie daran, dass Rollen kumulativ sind und dass geerbte Rollen, die auf das Abonnement oder die Ressourcengruppe begrenzt sind, nicht auf Ressourcenebene (Suchdienst) gelöscht oder verweigert werden können.

Stellen Sie sicher, dass Sie Ihre Clientanwendung mit der Microsoft Entra-ID registrieren und Rollenzuweisungen vor dem Testen des Zugriffs eingerichtet haben.

  1. Melden Sie sich beim Azure-Portal an.

  2. Navigieren Sie zu Ihrem Suchdienst.

  3. Wählen Sie auf der Seite „Übersicht“ die Registerkarte Indizes aus:

    • Suchdienstmitwirkende können jedes Objekt anzeigen und erstellen, aber keine Dokumente laden und keinen Index abfragen. Um Berechtigungen zu überprüfen, erstellen Sie einen Suchindex.

    • Mitwirkende an Suchindexdaten können Dokumente laden und abfragen. Verwenden Sie zum Überprüfen von Berechtigungen den Suchexplorer, um Dokumente abzufragen. Es gibt keine Option zum Laden von Dokumenten im Portal außerhalb des Assistenten zum Importieren von Daten. Da der Assistent auch Objekte erstellt, benötigen Sie die Rolle für den Suchdienstmitwirkenden sowie für den Mitwirkenden an Suchindexdaten.

    • Suchindexdatenleser können den Index abfragen. Verwenden Sie zum Überprüfen von Berechtigungen den Suchexplorer. Sie sollten Abfragen senden und Ergebnisse anzeigen können, aber Sie können die Indexdefinition nicht anzeigen.

Als aktueller Benutzer testen

Wenn Sie bereits Mitwirkender oder Besitzer Ihres Suchdiensts sind, können Sie ein Bearertoken für Ihre Benutzeridentität für die Authentifizierung bei Azure KI Search präsentieren.

  1. Rufen Sie ein Bearertoken für den aktuellen Benutzer mithilfe der Azure CLI ab:

    az account get-access-token --scope https://search.azure.com/.default

    Oder mit PowerShell:

    Get-AzAccessToken -ResourceUrl https://search.azure.com

  2. Fügen Sie in einer neuen Textdatei in Visual Studio Code die folgenden Variablen ein:

    @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
@index-name = PASTE-YOUR-INDEX-NAME-HERE
@token = PASTE-YOUR-TOKEN-HERE

  3. Senden Sie nach dem Einfügen eine Anforderung, um den Zugriff zu bestätigen. Mit der folgenden Anforderung wird der hotels-quickstart-Index abgefragt:

    POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2023-11-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

    {
         "queryType": "simple",
         "search": "motel",
         "filter": "",
         "select": "HotelName,Description,Category,Tags",
         "count": true
     }

Gewähren des Zugriffs auf einen einzelnen Index

In einigen Szenarien könnte es sinnvoll sein, den Zugriff einer Anwendung auf eine einzelne Ressource zu beschränken, z. B. einen Index.

Das Portal unterstützt derzeit keine Rollenzuweisungen auf dieser Granularitätsebene, aber dies kann mit PowerShell oder dem Azure CLI erfolgen.

In PowerShell verwenden Sie dafür den Befehl New-AzRoleAssignment und geben den Namen des Azure-Benutzers oder der Azure-Gruppe sowie den Umfang der Zuweisung an.

  1. Laden Sie die Azure- und AzureAD-Module, und stellen Sie eine Verbindung mit Ihrem Azure-Konto her:

    Import-Module -Name Az
Import-Module -Name AzureAD
Connect-AzAccount

  2. Fügen Sie eine Rollenzuweisung hinzu, die einem einzelnen Index zugewiesen ist:

    New-AzRoleAssignment -ObjectId <objectId> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Erstellen einer benutzerdefinierten Rolle

Wenn integrierte Rollen nicht die richtige Kombination von Berechtigungen bereitstellen, können Sie eine benutzerdefinierte Rolle erstellen, um die erforderlichen Vorgänge zu unterstützen.

In diesem Beispiel wird der Suchindexdatenleser geklont und dann die Möglichkeit hinzugefügt, Indizes nach Namen auflisten zu können. Normalerweise wird das Auflisten der Indizes für einen Suchdienst als administratives Recht angesehen.

Diese Schritte werden von Erstellen oder Aktualisieren benutzerdefinierter Azure-Rollen mithilfe des Azure-Portals. Das Klonen von einer vorhandenen Rolle wird auf einer Suchdienstseite unterstützt.

Diese Schritte erstellen eine benutzerdefinierte Rolle, die Suchabfragerechte ergänzt, um das Auflisten von Indizes nach Namen einzuschließen. In der Regel wird das Auflisten von Indizes als Administratorfunktion angesehen.

  1. Navigieren Sie im Azure-Portal zu Ihrem Suchdienst.

  2. Wählen Sie im linken Navigationsbereich Zugriffssteuerung (IAM) aus.

  3. Wählen Sie auf der Aktionsleiste Rollen aus.

  4. Klicken Sie mit der rechten Maustaste auf Suchindexdatenleser (oder eine andere Rolle), und wählen Sie Klonen aus, um den Assistenten zum Erstellen einer benutzerdefinierten Rolle zu öffnen.

  5. Geben Sie auf der Registerkarte „Grundlagen“ einen Namen für die benutzerdefinierte Rolle an, z. B. „Suchindexdaten-Explorer“, und wählen Sie dann Weiter aus.

  6. Wählen Sie auf der Registerkarte „Berechtigungen“ die Option Berechtigung hinzufügen aus.

  7. Suchen Sie auf der Registerkarte „Berechtigungen hinzufügen“ nach der Kachel Microsoft Search, und wählen Sie sie aus.

  8. Legen Sie die Berechtigungen für Ihre benutzerdefinierte Rolle fest. Oben auf der Seite unter Verwendung der Standardauswahl Aktionen:

    • Wählen Sie unter „Microsoft.Search/operations“ Lesen: Alle verfügbaren Vorgänge auflisten aus.
    • Wählen Sie unter „Microsoft.Search/searchServices/indexes“ Lesen: Index lesen aus.

  9. Wechseln Sie auf derselben Seite zu Datenaktionen, und wählen Sie unter „Microsoft.Search/searchServices/indexes/documents“ Lesen: Dokumente lesen aus.

    Die JSON-Definition sieht wie im folgenden Beispiel aus:

    {
 "properties": {
     "roleName": "search index data explorer",
     "description": "",
     "assignableScopes": [
         "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
     ],
     "permissions": [
         {
             "actions": [
                 "Microsoft.Search/operations/read",
                 "Microsoft.Search/searchServices/indexes/read"
             ],
             "notActions": [],
             "dataActions": [
                 "Microsoft.Search/searchServices/indexes/documents/read"
             ],
             "notDataActions": []
         }
     ]
   }
 }

  10. Wählen Sie Überprüfen + erstellen aus, um die Rolle zu erstellen. Sie können der Rolle jetzt Benutzer und Gruppen zuweisen.

Deaktivieren der API-Schlüssel-Authentifizierung

Zugriff auf Schlüssel oder eine lokale Authentifizierung können für Ihren Dienst deaktiviert werden, wenn Sie die Rollen „Suchdienstmitwirkender“, „Mitwirkender an Suchindexdaten“ und „Suchindexdatenleser“ und Microsoft Entra-Authentifizierung verwenden. Das Deaktivieren von API-Schlüsseln führt dazu, dass der Suchdienst alle datenbezogenen Anforderungen ablehnt, die einen API-Schlüssel im Header übergeben.

Hinweis

Administrator-API-Schlüssel können nur deaktiviert und nicht gelöscht werden. Abfrage-API-Schlüssel können gelöscht werden.

Zum Deaktivieren von Features sind die Berechtigungen „Besitzer“ oder „Mitwirkender“ erforderlich.

Verwenden Sie das Azure-Portal oder die Verwaltungs-REST-API, um die schlüsselbasierte Authentifizierung zu deaktivieren.

  1. Navigieren Sie im Azure-Portal zu Ihrem Suchdienst.

  2. Wählen Sie im linken Navigationsbereich die Option Schlüssel aus.

  3. Wählen Sie Rollenbasierte Zugriffssteuerung aus.

Die Änderung ist sofort wirksam, warten Sie aber einige Sekunden vor dem Testen. Wenn Sie über die Berechtigung zum Zuweisen von Rollen als Mitglied der Rolle „Besitzer“, „Dienstadministrator“ oder „Co-Admin“ verfügen, können Sie Portalfeatures verwenden, um den rollenbasierten Zugriff zu testen.

Bedingter Zugriff

Wenn Sie Organisationsrichtlinien wie die Multi-Faktor-Authentifizierung erzwingen müssen, wird bedingter Microsoft Entra-Zugriff empfohlen.

Führen Sie die folgenden Schritte aus, um eine Richtlinie für bedingten Zugriff für Azure KI-Suche zu aktivieren:

  1. Melden Sie sich beim Azure-Portal an.

  2. Suchen Sie nach bedingten Zugriff von Microsoft Entra.

  3. Wählen Sie Richtlinien aus.

  4. Wählen Sie Neue Richtlinie.

  5. Fügen Sie im Abschnitt Cloud-Apps oder Aktionen der Richtlinie Azure KI Search als Cloud-App hinzu, je nachdem, wie Sie Ihre Richtlinie einrichten möchten.

  6. Aktualisieren Sie die verbleibenden Parameter der Richtlinie. Geben Sie beispielsweise an, für welche Benutzer und Gruppen diese Richtlinie gilt.

  7. Speichern Sie die Richtlinie.

Wichtig

Wenn Ihrem Suchdienst eine verwaltete Identität zugewiesen ist, wird der spezifische Suchdienst als Cloud-App angezeigt, die als Teil der Richtlinie für bedingten Zugriff eingeschlossen oder ausgeschlossen werden kann. Richtlinien für bedingten Zugriff können nicht für einen bestimmten Suchdienst erzwungen werden. Stellen Sie stattdessen sicher, dass Sie die allgemeine Cloud-App für Azure KI Search auswählen.

Behandlung von Problemen bei der rollenbasierten Zugriffssteuerung

Bei der Entwicklung von Anwendungen, die die rollenbasierte Zugriffssteuerung für die Authentifizierung verwenden, können einige häufige Probleme auftreten:

  • Wenn das Autorisierungstoken von einer verwalteten Identität stammt und die entsprechenden Berechtigungen kürzlich zugewiesen wurden, kann es mehrere Stunden dauern, bis diese Berechtigungszuweisungen wirksam werden.
  • Die Standardkonfiguration für einen Suchdienst ist nur die schlüsselbasierte Authentifizierung. Wenn Sie die Standardschlüsseleinstellung nicht in die Zugriffssteuerung sowohl als auch"Rollenbasierte Zugriffssteuerung“ geändert haben, werden alle Anforderungen, die die rollenbasierte Authentifizierung verwenden, unabhängig von den zugrunde liegenden Berechtigungen automatisch verweigert.