Abfragezeit-ACL- und RBAC-Erzwingung in Azure KI-Suche (Vorschau)

Die Abfragezeit-Zugriffssteuerung (Vorschau) stellt sicher, dass Benutzer nur Suchergebnisse abrufen, auf die sie basierend auf ihrer Identität, Gruppenmitgliedschaften, Rollen oder Attributen zugreifen dürfen. Diese Funktionalität ist für sichere Unternehmenssuche und compliancegesteuerte Workflows unerlässlich.

Autorisierter Zugriff hängt von Berechtigungsmetadaten ab, die während der Indizierung aufgenommen werden. Für Indizierungsdatenquellen mit integrierten Zugriffsmodellen wie Azure Data Lake Storage (ADLS) Gen2 und SharePoint in Microsoft 365 kann ein Indexer die Berechtigungsmetadaten für jedes Dokument automatisch abrufen. Für andere Datenquellen müssen Sie die Dokumentnutzlast selbst zusammenstellen, und die Nutzlast muss sowohl Inhalt als auch die zugehörigen Berechtigungsmetadaten enthalten. Anschließend verwenden Sie die Push-APIs , um den Index zu laden.

In diesem Artikel wird erläutert, wie Abfragen eingerichtet werden, die Berechtigungsmetadaten zum Filtern von Ergebnissen verwenden.

Voraussetzungen

• Berechtigungsmetadaten müssen sich in filterable Zeichenfolgenfeldern befinden. Sie verwenden den Filter nicht in Ihren Abfragen, aber die Suchmaschine erstellt intern einen Filter, um nicht autorisierte Inhalte auszuschließen.

• Berechtigungsmetadaten müssen entweder aus POSIX-Stilberechtigungen bestehen, die die Zugriffsebene sowie die Gruppen- oder Benutzer-ID identifizieren, oder aus der Ressourcen-ID des Containers in ADLS Gen2, wenn Sie den RBAC-Bereich verwenden.

• Für eine ACL-basierte Erzwingung mit benutzerdefinierter Erfassung speichern Sie userIds und groupIds als Microsoft Entra-Objekt-IDs (GUIDs) in filterbaren Feldern. Zum Abfragezeitpunkt gleicht der Dienst die Identitäten in x-ms-query-source-authorization mit den gespeicherten IDs ab. Einzelheiten zum Schema finden Sie unter Indizieren von Dokumentzugriffssteuerungslisten (ACLs) mithilfe der Push-REST-APIs (Vorschau).

• Abhängig von der Datenquelle:

  • Für ADLS Gen2-Datenquellen müssen Sie Zugriffssteuerungslisten (Access Control Lists, ACLs) und/oder Azure rollenbasierte Zugriffssteuerungsrollen (Role-Based Access Control, RBAC) auf Containerebene konfiguriert haben.
  • Für Azure Blob-Datenquellen müssen Rollenzuweisungen für den Container vorhanden sein. Sie können einen integrierten Indexer, eine Wissensquelle oder Push-APIs verwenden, um Berechtigungsmetadaten in Ihrem Index zu indizieren.
  • Für SharePoint Datenquellen müssen Sie Zugriffssteuerungslisten (Access Control Lists, ACLs) konfigurieren. Sie können einen integrierten SharePoint-Indexer verwenden und mit ACL-Aufnahmefunktionen konfigurieren. Sie können auch eine indizierte SharePoint Wissensquelle verwenden und konfigurieren, um Berechtigungen auf Dokumentebene zu erzwingen. Gruppenbasierte Berechtigungen, einschließlich Microsoft 365-Gruppen, werden unterstützt, wenn sie als Entra-Objekt-IDs aufgenommen werden. Die Gruppenerweiterung erfolgt zum Zeitpunkt der Abfrage über Microsoft Graph.

• Verwenden Sie die latest preview REST API oder ein Vorschaupaket eines Azure SDK, um den Index oder die Wissensquelle abzufragen. Diese API-Version unterstützt interne Abfragen, die nicht autorisierte Ergebnisse herausfiltern.

Einschränkungen

• Wenn die ACL-Auswertung fehlschlägt (z. B. ist die Graph-API nicht verfügbar), gibt der Dienst 5xx zurück und gibt not einen teilweise gefilterten Resultset zurück.

• Die ACL-Aktualität hängt von der Methode der Datenerfassung ab. Um veraltete Autorisierungsentscheidungen zu vermeiden, planen Sie, wie jede Quelle Berechtigungsänderungen an den Index weiterverbreitet:

  • Ein geplanter SharePoint Indexer aktualisiert Berechtigungsänderungen auf Elementebene für jede Ausführung. Änderungen an einem übergeordneten Bereich (Website, Bibliothek, Liste oder Ordner), die von untergeordneten Elementen geerbt werden, erfordern eine erneute Synchronisierung.
  • Ein ADLS Gen2-Indexer erfordert eine erneute Synchronisierung zum Aktualisieren von ACLs.
  • Die benutzerdefinierte oder Push-Erfassung erfordert, dass Sie die betroffenen Dokumente erneut erfassen.

• Für die Dokumentsichtbarkeit sind beides erforderlich:

  • Die RBAC-Rolle der aufrufenden Anwendung (Autorisierungsheader).
  • Die von x-ms-query-source-authorization übermittelte Benutzeridentität.

• Anfängliche ACL-basierte Abfragen können im Vergleich zu nachfolgenden Anforderungen aufgrund von Zwischenspeicherung und Berechtigungsauflösung eine höhere Latenz aufweisen.

• Bei indizierten SharePoint-Inhalten wird eine Microsoft Entra-Gruppe, die in einer SharePoint-Gruppe enthalten ist, nicht erweitert. Die transitive Auflösung von Gruppen in Microsoft Entra unterstützt diese gemischte Relation nicht. Siehe Unterstützte Gruppenbeziehungen.

ACL-Eintragsbeschränkungen pro Datenquelle

Einträge in einer Zugriffssteuerungsliste (Access Control List, ACL) definieren, wie viele unterschiedliche Berechtigungseinträge einer Datei, einem Ordner oder einem Element in einer verbundenen Datenquelle zugeordnet werden können. Jeder Eintrag stellt eine einzelne Benutzer- oder Gruppenidentität und die Zugriffsrechte dar, die dieser Identität gewährt werden (z. B. "Lesen", "Schreiben" oder "Execute").

Die maximale Anzahl von ACL-Einträgen, die von Azure KI-Suche Funktionalität unterstützt werden, variiert je nach Datenquellentyp:

Azure Data Lake Storage Gen2 (ADLS Gen2): Jede Datei oder jedes Verzeichnis kann bis zu 32 ACL-Eintragsberechtigungen haben. In diesem Kontext bedeutet ein Eintrag einen einzelnen Benutzer oder eine Gruppe mit einem spezifischen Satz festgelegter Berechtigungen. Beispiel: Das Zuweisen des Lesezugriffs für "Jeder" und des Ausführungszugriffs für "Azure-Benutzer" wird als zwei ACL-Einträge gezählt.

SharePoint in Microsoft 365: SharePoint Datenquelle in der Suche unterstützt bis zu 1.000 Berechtigungseinträge pro Datei. Jeder Eintrag stellt eine eindeutige Benutzer- oder Gruppenzuweisung in der Berechtigungsliste des Elements dar. Dies unterscheidet sich von den allgemeinen eindeutigen Berechtigungsbereichen pro Liste oder Bibliothek, die bestimmt, wie viele Elemente über eindeutige Berechtigungen verfügen können.

Diese Grenzwerte bestimmen, wie präzise Azure KI-Suche Berechtigungen auf Elementebene beim Indizieren oder Filtern von Suchergebnissen berücksichtigen können. Wenn ein Element diese ACL-Eintragsgrenzwerte überschreitet, werden Berechtigungen, die über den Grenzwert hinausgehen, möglicherweise zur Abfragezeit nicht erzwungen.

Wie die Erzwingung von Abfragen zur Laufzeit funktioniert

In diesem Abschnitt wird die Reihenfolge der Vorgänge für die ACL-Erzwingung zur Abfragezeit aufgeführt. Vorgänge variieren je nachdem, ob Sie entweder den Azure RBAC-Geltungsbereich oder Microsoft Entra ID-Gruppen oder Benutzer-IDs verwenden.

1. Eingabe von Benutzerberechtigungen

Die Endbenutzeranwendung enthält ein Abfragezugriffstoken als Teil der Suchabfrageanforderung, und dieses Zugriffstoken ist in der Regel die Identität des Benutzers. Die folgende Tabelle enthält die Quelle der benutzerberechtigungen, die von Azure KI-Suche für die ACL-Erzwingung unterstützt werden:

2. Konstruktion von Sicherheitsfiltern

Intern erstellt Azure KI-Suche sicherheitsfilter dynamisch basierend auf den bereitgestellten Benutzerberechtigungen. Diese Sicherheitsfilter werden automatisch an alle Filter angefügt, die in der Abfrage enthalten sind, wenn der Index die Berechtigungsfilteroption aktiviert hat.

Für Azure RBAC sind Berechtigungen Listen mit Ressourcen-ID-Zeichenfolgen. Es muss eine Azure-Rollenzuweisung (Storage Blob Data Reader) für die Daten der Quelle vorhanden sein, die Zugriff auf das Sicherheitsprinzipaltoken im Autorisierungsheader gewährt. Der Filter schließt Dokumente aus, wenn es keine Rollenzuweisung für den Prinzipal hinter dem Zugriffstoken für die Anforderung gibt.

3. Ergebnisfilterung

Der Sicherheitsfilter gleicht effizient die userIds, die groupIds und den rbacScope aus der Anfrage mit jeder Liste der ACLs in jedem Dokument im Suchindex ab, um die zurückgegebenen Ergebnisse auf diejenigen zu beschränken, auf die der Benutzer Zugriff hat. Es ist wichtig zu beachten, dass jeder Filter unabhängig angewendet wird und ein Dokument als autorisiert betrachtet wird, wenn ein Filter erfolgreich ist. Wenn ein Benutzer beispielsweise Zugriff auf ein Dokument über Benutzer-IDs, aber nicht über GroupIds hat, wird das Dokument weiterhin als gültig betrachtet und an den Benutzer zurückgegeben.

SharePoint Gruppen zur Abfragezeit

Ab der REST-API-Version 2026-05-01-preview kann Azure KI-Suche Mitgliedschaften in SharePoint-Websitegruppen wie Besitzer, Mitglieder, Besucher und benutzerdefinierte Websitegruppen zur Abfragezeit berücksichtigen. Um dieses Szenario zu aktivieren, muss der Index Folgendes enthalten:

• Eine sharePointConnectorAppRegistration-Eigenschaft, die auf die Verbundidentitätsanmeldeinformationen der Microsoft Entra Anwendung verweist, die zum Aufrufen von SharePoint im Namen des Benutzers verwendet wird.
• Ein Feld, das mit dem Attribut sharepointSiteUrl: true gekennzeichnet ist und die URL der SharePoint-Website für jedes indizierte Element speichert (normalerweise SharePointSiteUrl genannt und aus dem Quellfeld metadata_spo_site_url befüllt).

Zum Abfragezeitpunkt verwendet Azure KI-Suche die registrierte Anwendung und die URL der Website jedes Kandidatendokuments, um die SharePoint-Gruppenmitgliedschaften des aufrufenden Benutzers auf der betreffenden Website zu ermitteln. Die aufgelösten Gruppen werden mit den Werten mit spg:-Präfix abgeglichen, die im Berechtigungsfilterfeld groupIds gespeichert sind. Das Präfix spg: unterscheidet SharePoint Websitegruppen von Microsoft Entra Gruppenobjekt-IDs, die ohne Präfix gespeichert werden.

Informationen zu Konfigurationsdetails und Einschränkungen finden Sie unter Configure SharePoint-Gruppenunterstützung.

Wenn SharePoint Berechtigungsfilterung fehlende oder unerwartete Ergebnisse zurückgibt, lesen Sie die Problembehandlung SharePoint Berechtigungsfilterung.

Beispiel: Abfrage mit Durchsetzung von SharePoint-Websitegruppen

Die Anforderung ist identisch mit der standardmäßigen ACL-erzwungenen Abfrage. Der Suchdienst verwendet das sharePointConnectorAppRegistration des Index, um die SharePoint-Gruppenmitgliedschaft im Auftrag des Aufrufers aufzulösen. Fügen Sie GroupIds in die select-Klausel ein, um mit spg: präfixierte Werte in der Antwort anzuzeigen.

POST {{endpoint}}/indexes/{index}/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: {{query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,SharePointSiteUrl,GroupIds",
    "orderby": "name asc"
}

Abfragebeispiel

Hier ist ein Beispiel für eine Abfrageanforderung aus sample-Code. Das Abfragetoken ist ein Microsoft Entra Zugriffstoken für den Abfragebenutzer.

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: {{query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

Erhöhte Berechtigungen zum Untersuchen falscher Ergebnisse (Vorschau)

Das Debuggen von Abfragen, die Berechtigungsmetadaten enthalten, kann problematisch sein, da Suchergebnisse für jeden Benutzer spezifisch sind. Als Entwickler oder Administrator benötigen Sie möglicherweise erhöhte Berechtigungen, um Ergebnisse zurückzugeben, unabhängig von den Berechtigungsmetadaten, damit Sie Probleme mit Abfragen untersuchen können, die nicht autorisierte Inhalte zurückgeben.

Um dies zu untersuchen, müssen Sie folgende Möglichkeiten haben:

• Zeigen Sie die Gruppe von Dokumenten an, die der Endbenutzer basierend auf den Berechtigungen dieses Benutzers anzeigen kann.

• Zeigen Sie alle Dokumente im Index an, um zu untersuchen, warum einige für den Endbenutzer möglicherweise nicht sichtbar sind.

Sie können diese Aufgaben ausführen, indem Sie einen benutzerdefinierten Header, x-ms-enable-elevated-read: true, zu einer Abfrage hinzufügen.

Berechtigungen für Anforderungen für erweiterte Lesezugriffe

Sie benötigen die Berechtigung Mitwirkender an Suchindexdaten oder eine benutzerdefinierte Rolle, die die Berechtigung „Lesen erhöhen“ enthält.

Abfragen sind ein Datenebenenvorgang, sodass die benutzerdefinierte Rolle nur aus Berechtigungen für atome Datenebenen bestehen kann. Fügen Sie für eine benutzerdefinierte Rolle die Berechtigung Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read hinzu.

Hinzufügen eines Headers mit erhöhtem Lesezugriff zu einer Abfrage

Nachdem Sie Berechtigungen eingerichtet haben, können Sie die Abfrage ausführen. Das folgende Beispiel ist eine Abfrageanforderung für einen Suchindex.

POST {endpoint}/indexes('{indexName}')/search.post.search?api-version=2026-08-01-preview
Authorization: Bearer {AUTH_TOKEN}
x-ms-query-source-authorization: {TOKEN}
x-ms-enable-elevated-read: true

{
    "search": "prototype tests",
    "select": "filename, author, date",
    "count": true
}

Wichtige Verhaltensänderung der ACL-Funktionalität in bestimmten Vorschau-API-Versionen

Vor der REST-API-Version 2025-11-01-previewhaben frühere Vorschauversionen 2025-05-01-preview und 2025-08-01-preview alle Dokumente bei Verwendung eines Dienst-API-Schlüssels oder autorisierter Entra-Rollen zurückgegeben, auch wenn kein Benutzertoken bereitgestellt wurde. Anwendungen, die das Vorhandensein eines Benutzertokens nicht überprüft haben, könnten versehentlich Ergebnisse für Endbenutzer verfügbar machen, wenn sie nicht ordnungsgemäß implementiert oder bewährte Methoden befolgt werden.

Ab November 2025 hat sich dieses Verhalten geändert:

• ACL-Berechtigungsfilter gelten jetzt auch dann, wenn nur Dienst-API-Schlüssel oder Entra-Authentifizierung für alle Versionen verwendet werden, die ACL unterstützen.
• Wenn das Benutzertoken nicht angegeben wird, werden ACL-geschützte Inhalte nicht zurückgegeben.
• Um alle Dokumente zur Fehlerbehebung anzuzeigen, müssen Sie bei Verwendung der REST-API-Version 2026-05-01-preview oder höher den Header für erweiterten Lesezugriff explizit angeben.

Dieses Update trägt dazu bei, dass Inhalte geschützt bleiben, wenn Anwendungen keine bewährten Methoden für die Tokenüberprüfung erzwingen.

Verwandte Inhalte

• Lernprogramm: Indizierung von Berechtigungsmetadaten aus ADLS Gen2 und Abfrage mit durch Berechtigungen gefilterten Ergebnissen (Vorschau)
• Indizieren von Dokumentzugriffssteuerungslisten (ACLs) mithilfe der Push-REST-APIs (Vorschau)
• Verwenden eines ADLS Gen2-Indexers zum Aufnehmen von Berechtigungsmetadaten und Filtern von Suchergebnissen basierend auf Benutzerzugriffsrechten (Vorschau)
• Verwenden Sie einen Blob-Indexer oder eine Wissensquelle, um RBAC-Scope-Metadaten zu erfassen
• Verwenden eines SharePoint Indexers zum Aufnehmen von Berechtigungsmetadaten und Filtern von Suchergebnissen basierend auf Benutzerzugriffsrechten (Vorschau)