Teilen über

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-Suche können Sie Azure-Rollen für Folgendes zuweisen:

Benutzerbasierter Zugriff über Suchergebnisse – zuweilen als Sicherheit auf Zeilenebene oder Sicherheit auf Dokumentebene bezeichnet – wird nicht mit Rollenzuweisung 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. Sehen Sie sich dieses Enterprise-Chatbeispiel mit RAG für eine Demonstration an.

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.

Rollenbasierter Zugriff ist optional, wird jedoch empfohlen. Die Alternative ist die Standardeinstellung, die schlüsselbasierte Authentifizierung.

Voraussetzungen

Begrenzungen

  • Die rollenbasierte Zugriffssteuerung kann die Latenz einiger Anforderungen erhöhen. Jede eindeutige Kombination aus Dienstressource (Index, Indexer usw.) und Dienstprinzipal löst eine Autorisierungsprüfung aus. Diese Autorisierungsprüfungen können eine Latenz von bis zu 200 Millisekunden pro Anforderung erreichen.

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

Aktivieren des rollenbasierten Zugriffs für Datenebenenvorgänge

Rollen für die Dienstverwaltung (Steuerungsebene) sind obligatorisch. Rollen für Datenebenenvorgänge sind optional. Sie müssen rollenbasierten Zugriff aktivieren, bevor Sie die Rollen Suchdienstmitwirkender, Suchindexdatenmitwirkender oder Suchindexdatenleser für Datenvorgänge zuweisen können.

In diesem Schritt konfigurieren Sie Ihren Dienst so, dass er einen Autorisierungsheader bei Datenebenenanforderungen erkennt, die ein OAuth2-Zugriffstoken enthalten.

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.

  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 rollenbasiertes Steuerelement oder Beide aus, wenn Sie flexibel sein möchten.

    Option Beschreibung
    API-Schlüssel (Standard). Erfordert API-Schlüssel im Anforderungsheader für die Autorisierung
    Rollenbasierte Zugriffssteuerung Erfordert die Mitgliedschaft in einer Rollenzuweisung, um die Aufgabe abzuschließen. Außerdem ist ein Autorisierungsheader in der Anforderung erforderlich.
    Beides Anforderungen sind entweder mithilfe eines API-Schlüssels oder einer rollenbasierten Zugriffssteuerung gültig, aber wenn Sie beide in derselben Anforderung bereitstellen, wird der API-Schlüssel verwendet.

Die Änderung ist sofort wirksam, aber warten Sie ein paar Sekunden, bevor Sie Rollen zuweisen.

Wenn Sie die rollenbasierte Zugriffssteuerung im Portal aktivieren, lautet der Fehlermodus "http401WithBearerChallenge", wenn bei der Autorisierung ein Fehler auftritt.

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.

Zuweisen von Rollen

Weisen Sie in diesem Abschnitt Rollen für Folgendes zu:

Zuweisen von Rollen für die Dienstverwaltung

Als Dienstadministrator können Sie einen Suchdienst erstellen und konfigurieren und alle Steuerungsebenenvorgänge ausführen, die in der Verwaltungs-REST-API oder gleichwertigen Clientbibliotheken beschrieben sind. Abhängig von der Rolle können Sie auch die meisten Such-REST-API-Aufgaben auf Datenebene ausführen.

  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.

  5. Wählen Sie eine entsprechende Rolle aus:

    • Besitzer (Vollzugriff auf alle Vorgänge der Datenebene und der Steuerungsebene mit Ausnahme von Abfrageberechtigungen)
    • Mitwirkender (wie der Besitzer mit Ausnahme von Berechtigungen für das Zuweisen von Rollen)
    • Leser (für Überwachung und Anzeigemetriken)

  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.

Zuweisen von Rollen für die Entwicklung

Rollenzuweisungen sind global für den Suchdienst. Zum Berechtigungen für einen einzelnen Index zu untersuchen, verwenden Sie PowerShell oder die Azure CLI, um eine benutzerdefinierte Rolle zu erstellen.

Wichtig

Wenn Sie den rollenbasierten Zugriff für einen Dienst oder Index konfigurieren und auch einen API-Schlüssel für die Anforderung bereitstellen, verwendet der Suchdienst den API-Schlüssel zur Authentifizierung.

  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 Rolle aus:

    • Suchdienstmitwirkender (Vorgänge bei Indizes, Indexern, Skillsets und anderen Objekten auf höchster Ebene: Erstellen, Lesen, Updaten, Löschen)
    • Suchindexdatenmitwirkender (Laden von Dokumenten und Ausführen von Indizierungsaufträgen)
    • Suchindexdatenleser (Abfragen eines Index)

    Eine weitere Kombination aus Rollen, die Vollzugriff bieten, ist Mitwirkender oder Besitzer mit 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.

  8. Wiederholen Sie diesen Vorgang für die anderen Rollen. Die meisten Entwickler benötigen alle drei.

Zuweisen von Rollen für schreibgeschützte Abfragen

Verwenden Sie die Rolle Suchindexdatenleser für Apps und Prozesse, die nur Lesezugriff auf einen Index benötigen. Dies ist eine sehr spezifische Rolle. Sie gewährt GET- oder POST-Zugriff auf die Dokumentensammlung eines Suchindexes für das Suchen, AutoVervollständigen und Vorschläge.

Sie unterstützt keine GET- oder LIST-Vorgänge für einen Index oder andere Objekte auf oberster Ebene oder GET-Dienststatistiken.

  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.

  5. Wählen Sie die Rolle Suchindexdatenleser aus.

  6. Wählen Sie auf der Registerkarte „Mitglieder“ die Microsoft Entra-Benutzer- oder Gruppenidentität aus. Wenn Sie Berechtigungen für einen anderen Dienst einrichten, verwenden Sie möglicherweise eine system- oder benutzerseitig verwaltete Identität. Wählen Sie diese Option aus, wenn es sich um eine Rollenzuweisung für eine Dienstidentität handelt.

  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 (Suchdienstebene) 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.

    • Suchindexdatenmitwirkende können Dokumente laden. Es gibt keine Option zum Laden von Dokumenten im Portal außerhalb des Assistenten zum Importieren von Daten, aber Sie können einen Indexer zurücksetzen und ausführen, um die Dokumentladeberechtigungen zu bestätigen.

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

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

Der Schlüsselzugriff oder die lokale Authentifizierung kann für Ihren Dienst deaktiviert werden, wenn Sie die integrierten Rollen und die 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 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.