Herstellen einer Verbindung mit Azure KI Search unter Verwendung der rollenbasierten Zugriffssteuerung (Azure RBAC)

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 Zeilen- oder 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

In Azure KI Search bezieht sich „Steuerungsebene“ auf Vorgänge, die von der Verwaltungs-REST-API oder entsprechenden Clientbibliotheken unterstützt werden. Die „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.

Bei der Suche verwendete integrierte Rollen

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, Synonymzuordnungen, Indexer, Datenquellen und Skillsets). Besuchen Sie für die Berechtigungsliste Microsoft.Search/searchServices/*. Diese Rolle kann nicht auf Inhalte in einem Index zugreifen, weshalb keine Abfrage oder Indizierung möglich ist, aber sie kann Indizes erstellen, löschen und listen, Indexdefinitionen und Statistiken zurückgeben und Analysetools testen. Diese Rolle ist für Suchdienstadministratoren gedacht, die den Suchdienst und seine Objekte verwalten müssen, jedoch ohne Inhaltszugriff.
Mitwirkender an Suchindexdaten	Daten	Lese- und Schreibzugriff auf Inhalte in allen Indizes des Suchdiensts. Diese Rolle ist für Entwickler oder Indexbesitzer gedacht, die die Dokumentsammlung eines Index importieren, aktualisieren oder abfragen müssen.
Suchindexdatenleser	Daten	Schreibgeschützter Zugriff auf alle Suchindizes im Suchdienst. Diese Rolle ist für Apps und Benutzer gedacht, die Abfragen ausführen.

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 von Azure RBAC werden nur die datenbezogenen Berechtigungen entfernt, die diesen Rollen zugeordnet sind. In einem Szenario mit deaktivierter RBAC 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.

Azure portal

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

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

   

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.

REST-API

Verwenden Sie die Verwaltungs-REST-API Erstellen oder Aktualisieren des Dienstes, um Ihren Dienst für die rollenbasierte Zugriffssteuerung zu konfigurieren.

Alle Aufrufe der Verwaltungs-REST-API werden über die Microsoft Entra-ID mit Mitwirkenden- oder Besitzerberechtigungen authentifiziert. Hilfe bei der Einrichtung von authentifizierten Anfragen finden Sie unter Verwalten von Azure AI Search über REST.

1. Rufen Sie Diensteinstellungen ab, damit Sie die aktuelle Konfiguration überprüfen können.

   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
   

2. Verwenden Sie PATCH, um die Dienstkonfiguration zu aktualisieren. Die folgenden Änderungen ermöglichen sowohl Schlüssel als auch rollenbasierten Zugriff. Wenn Sie eine reine Rollenkonfiguration wünschen, siehe API-Schlüssel deaktivieren.

   Setzen Sie unter „Eigenschaften“ „authOptions“ auf „aadOrApiKey“. Die Eigenschaft "disableLocalAuth" muss falsch sein, um "authOptions" zu setzen.

   Legen Sie optional AadAuthFailureMode fest, um anzugeben, ob 401 anstelle von 403 zurückgegeben wird, wenn die Authentifizierung fehlschlägt. Gültige Werte sind "http401WithBearerChallenge" oder "http403".

   PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
   {
       "properties": {
           "disableLocalAuth": false,
           "authOptions": {
               "aadOrApiKey": {
                   "aadAuthFailureMode": "http401WithBearerChallenge"
               }
           }
       }
   }
   

3. Folgen Sie den Anweisungen im nächsten Schritt, um Rollen für Datenebenenvorgänge zuzuweisen.

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.

Azure portal

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.

   

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.

PowerShell

Wenn Sie PowerShell zum Zuweisen von Rollen verwenden, rufen Sie New-AzRoleAssignment auf, und geben Sie den Namen des Azure-Benutzers oder der Azure-Gruppe sowie den Geltungsbereich der Zuweisung an.

Stellen Sie vor Beginn sicher, dass Sie die Module Az und Azure-AD geladen und eine Verbindung mit Azure hergestellt haben:

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

In diesem Beispiel wird eine Rollenzuweisung für einen Suchdienst erstellt:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

In diesem Beispiel wird eine Rollenzuweisung erstellt, die auf einen bestimmten Index festgelegt ist:

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

Denken Sie daran, dass Sie den Zugriff nur auf Ressourcen der obersten Ebene beschränken können, wie z. B. Indizes, Synonymzuordnungen, Indizierungsfunktionen, Datenquellen und Skillsets. Mit Azure-Rollen können Sie den Zugriff auf Suchdokumente (Indexinhalte) nicht beschränken.

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.

Azure portal

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:

   • Mitwirkende können jedes Objekt anzeigen und erstellen, aber keinen Index mithilfe des Suchexplorers abfragen.

   • Suchindexdatenleser können über den Such-Explorer den Index abfragen. Sie können jede API-Version verwenden, um den Zugriff zu überprüfen. Sie sollten Abfragen senden und Ergebnisse anzeigen können, aber Sie können die Indexdefinition nicht anzeigen.

   • Mitwirkende an Suchindexdaten könnenNeuer Index auswählen, um einen neuen Index zu erstellen. Durch das Speichern eines neuen Indexes wird der Schreibzugriff auf den Dienst überprüft.

REST-API

Für diesen Ansatz wird Visual Studio Code mit einer REST-Clienterweiterung vorausgesetzt.

1. Öffnen Sie eine Befehlsshell für die Azure CLI, und melden Sie sich bei Ihrem Azure-Abonnement an.

   az login
   

2. Rufen Sie Ihre Mandanten-ID und Abonnement-ID ab. Die ID wird in einem zukünftigen Schritt als Variable verwendet.

   az account show
   

3. Rufe ein Zugriffstoken ab.

   az account get-access-token --query accessToken --output tsv
   

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

5. Senden Sie nach dem Einfügen eine Anforderung, die die angegebenen Variablen verwendet. Für die Rolle „Suchindexdatenleser“ können Sie eine Abfrage senden. Sie können jede unterstützte API-Versionverwenden.

   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
        }
   

Weitere Informationen zum Abrufen eines Tokens für eine bestimmte Umgebung finden Sie unter Verwalten eines Azure KI-Suche-Diensts mit REST-APIs und Microsoft Identity Platform-Authentifizierungsbibliotheken.

.NET

1. Verwenden Sie das Paket Azure.Search.Documents.

2. Verwenden Sie Azure.Identity für .NET für die Tokenauthentifizierung. Microsoft empfiehlt DefaultAzureCredential() für die meisten Szenarien.

   • Beim Abrufen des OAuth-Tokens ist der Bereich "https://search.azure.com/.default". Das SDK erfordert, dass die Zielgruppe "https://search.azure.com" ist. Die Endung ".default" ist eine Microsoft Entra-Konvention.

   • Das SDK überprüft, ob der Benutzer über den Bereich „user_impersonation“ verfügt, der von Ihrer App gewährt werden muss, aber das SDK selbst fragt lediglich nach "https://search.azure.com/.default".

3. Hier ist ein Beispiel für eine Clientverbindung mit DefaultAzureCredential().

   // Create a SearchIndexClient to send create/delete index commands
   SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
   
   // Create a SearchClient to load and query documents
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());
   

4. Hier ist ein weiteres Beispiel der Verwendung von Anmeldeinformationen für geheimen Clientschlüssel:

   var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);
   

Python

1. Verwenden Sie azure.search.documents (Azure SDK für Python).

2. Verwenden Sie Azure.Identity für Python für die Tokenauthentifizierung.

3. Verwenden Sie DefaultAzureCredential, wenn der Python-Client eine Anwendung ist, die serverseitig ausgeführt wird. Aktivieren Sie die interaktive Authentifizierung, wenn die App in einem Browser ausgeführt wird.

4. Hier sehen Sie ein Beispiel:

   from azure.search.documents import SearchClient
   from azure.identity import DefaultAzureCredential
   
   credential = DefaultAzureCredential()
   endpoint = "https://<mysearch>.search.windows.net"
   index_name = "myindex"
   client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)
   

JavaScript

1. Verwenden Sie @azure/search-documents (Azure SDK für JavaScript), Version 11.3.

2. Verwenden Sie Azure.Identity für JavaScript für die Tokenauthentifizierung.

3. Wenn Sie React verwenden, verwenden InteractiveBrowserCredential Sie die Microsoft Entra-Authentifizierung für die Suche. Besuchen Sie Wann @azure/identity benutzen für Einzelheiten.

Java

1. Verwenden Sie azure-search-documents (Azure SDK für Java).

2. Verwenden Sie Azure.Identity für Java für die Tokenauthentifizierung.

3. Microsoft empfiehlt DefaultAzureCredential für Apps, die in Azure ausgeführt werden.

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://graph.microsoft.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.

Azure portal

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/a5b1ca8b-bab3-4c26-aebe-4cf7ec4791a0/resourceGroups/heidist-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.

Azure PowerShell

Das PowerShell-Beispiel zeigt die JSON-Syntax zum Erstellen einer benutzerdefinierten Rolle, die ein Klon von Suchindexdatenleser ist, aber mit der Möglichkeit, alle Indizes nach Namen auflisten zu können.

1. Überprüfen Sie die Liste der atomischen Berechtigungen, um zu bestimmen, welche Berechtigungen Sie benötigen. In diesem Beispiel benötigen Sie Folgendes:

   "Microsoft.Search/operations/read",
   "Microsoft.Search/searchServices/read",
   "Microsoft.Search/searchServices/indexes/read"
   

2. Richten Sie eine PowerShell-Sitzung ein, um die benutzerdefinierte Rolle zu erstellen. Ausführliche Anweisungen finden Sie unter Azure PowerShell.

3. Geben Sie die Rollendefinition als JSON-Dokument an. Das folgende Beispiel zeigt die Syntax zum Erstellen einer benutzerdefinierten Rolle mit PowerShell.

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

Hinweis

Wenn sich der zuweisbare Bereich auf Indexebene befindet, sollte die Datenaktion "Microsoft.Search/searchServices/indexes/documents/read" lauten.

REST-API

1. Überprüfen Sie die Liste der atomischen Berechtigungen, um zu bestimmen, welche Berechtigungen Sie benötigen.

2. Wie Sie dabei vorgehen, erfahren Sie unter Erstellen oder Aktualisieren von benutzerdefinierten Rollen in Azure über die REST-API.

3. Klonen oder erstellen Sie eine Rolle, oder verwenden Sie JSON, um die benutzerdefinierte Rolle anzugeben (json-Syntax finden Sie auf der Registerkarte PowerShell).

Azure-Befehlszeilenschnittstelle

1. Überprüfen Sie die Liste der atomischen Berechtigungen, um zu bestimmen, welche Berechtigungen Sie benötigen.

2. Wie Sie dabei vorgehen, erfahren Sie unter Erstellen oder Aktualisieren von benutzerdefinierten Rollen in Azure mithilfe der Azure-Befehlszeilenschnittstelle.

3. Klonen oder erstellen Sie eine Rolle, oder verwenden Sie JSON, um die benutzerdefinierte Rolle anzugeben (json-Syntax finden Sie auf der Registerkarte PowerShell).

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.

Portal

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.

REST-API

Um die schlüsselbasierte Authentifizierung zu deaktivieren, stellen Sie "disableLocalAuth" auf "true".

1. Rufen Sie Diensteinstellungen ab, damit Sie die aktuelle Konfiguration überprüfen können.

   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
   

2. Verwenden Sie PATCH, um die Dienstkonfiguration zu aktualisieren. Die folgende Änderung stellt "authOptions" auf null.

   PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
   {
       "properties": {
           "disableLocalAuth": true
       }
   }
   

Anforderungen, die nur einen API-Schlüssel enthalten, ohne Bearertoken, schlagen mit HTTP 401 fehl.

Um die Schlüsselauthentifizierung erneut zu aktivieren, müssen Sie die letzte Anforderung erneut ausführen und disableLocalAuth auf FALSE festlegen. Der Suchdienst akzeptiert API-Schlüssel in Anforderungen automatisch erneut (vorausgesetzt, diese Schlüssel sind angegeben).

Bedingter Zugriff

Mit dem Tool Bedingter Zugriff erzwingt Microsoft Entra ID Organisationsrichtlinien. Mithilfe von Richtlinien für den bedingten Zugriff können Sie bei Bedarf die richtigen Zugriffssteuerungen anwenden, um die Sicherheit Ihrer Organisation zu gewährleisten. Beim Zugriff auf einen Azure KI Search-Dienst mithilfe der rollenbasierten Zugriffssteuerung kann der bedingte Zugriff Organisationsrichtlinien erzwingen.

Führen Sie die folgenden Schritte aus, um eine Richtlinie für bedingten Zugriff für Azure KI Search 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 aus.

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.