Verwenden eines ADLS Gen2-Indexers zum Aufnehmen von Berechtigungsmetadaten und Filtern von Suchergebnissen basierend auf Benutzerzugriffsrechten (Vorschau)

Azure Data Lake Storage (ADLS) Gen2 unterstützt den benutzerbasierten Zugriff auf Verzeichnisse und Dateien über Access-Steuerelementlisten (ACLs) und role-based access control (Azure RBAC). Attributebasierte Zugriffssteuerung (Azure ABAC) wird nicht unterstützt.

Mithilfe einer Vorschau-REST-API kann Azure KI-Suche diese Berechtigungsmetadaten zusammen mit Dokumentinhalten erfassen (Vorschauversion). Benutzer, die keinen Zugriff auf ein Verzeichnis oder eine Datei im Speicher haben, werden die entsprechenden Dokumente in den Suchergebnissen nicht angezeigt. Dies ist eine von mehreren Strategien für die Zugriffssteuerung auf dokumentebene in Azure KI-Suche.

In diesem Artikel wird erläutert, wie Sie einen ADLS Gen2-Indexer oder eine ADLS Gen2-Blob-Wissensquelle konfigurieren, um Berechtigungsmetadaten automatisch in einen Suchindex abzurufen . Es ergänzt Indexdaten von ADLS Gen2 und Erstellen einer Blob-Wissensquelle für ADLS Gen2 mit Informationen, die speziell für die Berechtigungserfassung gelten. Informationen zum manuellen Pushen von Berechtigungsmetadaten finden Sie unter Indexdokument-ACLs mithilfe der Push-API.

Voraussetzungen

• Microsoft Entra ID Authentifizierung und Autorisierung. Dienste und Apps müssen sich im selben Mandanten befinden. Benutzer können in verschiedenen Mandanten sein, solange alle Mandanten Microsoft Entra ID verwenden. Rollenzuweisungen werden für jede authentifizierte Verbindung verwendet.

• Azure KI-Suche auf einer abrechnungsfähigen Ebene (Einfach oder höher) in einer beliebigen Region. Der Suchdienst muss rollenbasierten Zugriff aktiviert haben und eine vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identität.

• ADLS Gen2-Blobs in einem hierarchischen Namespace mit Benutzerberechtigungen, die über ACLs oder Rollen gewährt werden.

• REST API Version 2025-05-01-Preview oder höher für die Verarbeitung von Indexer-Berechtigungen. REST-API Version 2025-11-01-Preview oder höher für Knowledge Source Support. Verwenden Sie die neueste Vorschau-REST-API oder ein Vorschau-SDK-Paket, das Berechtigungsfilter unterstützt.

Einschränkungen

• Dieses Feature wird vom Azure-Portal nicht unterstützt.

• ADLS Gen2-Grenzwerte für Rollenzuweisungen und ACL-Einträge gelten.

• owning usersDie owning groupsOther und all () werden während der Vorschau nicht unterstützt. Verwenden Sie stattdessen named users- und named groups-Zuweisungen.

• Die folgenden Indexerfeatures unterstützen keine Berechtigungsvererbung in indizierten Dokumenten, die von ADLS Gen2 stammen. Wenn Sie eines dieser Features in einem Skillset oder Indexer verwenden, werden Berechtigungen auf Dokumentebene nicht in den indizierten Inhalt einbezogen.

  • Benutzerdefinierte Web-API-Fähigkeit

  • Wissensspeicher, einschließlich des Ressourcenspeichers, der für die Bildbereitstellung (Vorschau) im agentischen Abruf erforderlich ist. Daher wird die Bildbereitstellung für Wissensquellen, die ACLs oder RBAC-Bereiche erfassen, nicht unterstützt.

  • Indexeranreicherungscache

  • Debugsitzungen

Unterstützung für das Berechtigungsmodell

In diesem Abschnitt werden die Zugriffssteuerungsfeatures auf Dokumentebene zwischen ADLS Gen2 und Azure KI-Suche verglichen. Es wird erläutert, welche Azure Data Lake Storage (ADLS) Gen2-Zugriffssteuerungsmechanismen von AI Search unterstützt oder zugeordnet werden. Dies hilft Ihnen zu verstehen, wie Berechtigungen auf Dokumentebene erzwungen werden.

Zur Abfragezeit wertet Azure KI-Suche zuerst RBAC auf Containerebene aus und überprüft dann ACL-Einträge auf Dokumentebene. Der Zugriff wird gewährt, wenn irgendein Mechanismus dies zulässt.

Informationen zu hierarchischen ACL-Berechtigungen

Indexer und Wissensquellen können ACL-Zuordnungen aus dem angegebenen Container und allen Verzeichnissen abrufen, die zu jeder Datei führen, indem sie dem hierarchischen AdLS Gen2-Zugriffsauswertungsfluss folgen. Die endgültigen effektiven Zugriffslisten für jede Datei werden berechnet, und die verschiedenen Zugriffskategorien werden in die entsprechenden Indexfelder indiziert.

Beispiel: In allgemeinen ADLS Gen2-Szenarien im Zusammenhang mit Berechtigungen als Dateipfad /Oregon/Portland/Data.txt.

Der Indexer oder die Wissensquelle sammelt ACLs aus jedem Container und Verzeichnis. Anschließend wird der effektive Zugriff auf niedrigeren Ebenen ermittelt und fortgesetzt, bis die Berechtigungen für jede Datei aufgelöst werden.

/ assigned access vs Oregon/ assigned access
  => Oregon/ effective access vs Portland/ assigned access
    => Portland/ effective access vs Data.txt assigned access
      => Data.txt effective access

Konfigurieren von ADLS Gen2

Ein Indexer oder eine Wissensquelle kann ACLs für ein Speicherkonto abrufen, wenn die folgenden Kriterien erfüllt sind. Weitere Informationen zu ACL-Zuordnungen finden Sie unter ADLS Gen2 ACL-Zuordnungen.

Autorisierung

Für die Indizierung muss Ihre Suchdienstidentität über die Berechtigung "Storage Blob Data Reader " verfügen.

Wenn Sie lokal testen, sollten Sie auch über eine Rollenzuweisung für "Storage Blob Data Reader " verfügen. Weitere Informationen finden Sie unter Connect to Azure Storage using a managed identity.

Stammcontainerberechtigungen:

1. Weisen Sie alle Group und User Sätze (Sicherheitsprinzipale) im Stammcontainer / mit Read und Execute Berechtigungen zu.

2. Stellen Sie sicher, dass sowohl Read als auch Execute als "Standardberechtigungen" hinzugefügt werden, damit sie automatisch auf neu erstellte Dateien und Verzeichnisse übertragen werden.

Verteilen von Berechtigungen nach unten in der Dateihierarchie

Obwohl neue Verzeichnisse und Dateien Berechtigungen erben, erben vorhandene Verzeichnisse und Dateien diese Zuordnungen nicht automatisch.

Verwenden Sie das ADLS Gen2-Tool, um Zugriffssteuerlisten (ACLs) rekursiv anzuwenden und die Zuordnungen auf vorhandene Inhalte zu übertragen. Dieses Tool verteilt die ACL-Zuordnungen des Stammcontainers an alle zugrunde liegenden Verzeichnisse und Dateien.

Entfernen von übermäßigen Berechtigungen

Überprüfen Sie nach rekursivem Anwenden von ACLs die Berechtigungen für jedes Verzeichnis und jede Datei.

Entfernen Sie alle Group oder User Sätze, die keinen Zugriff auf bestimmte Verzeichnisse oder Dateien haben sollen. Entfernen Sie zum Beispiel User2 aus dem Ordner Portland/ und entfernen Sie zur weiteren Bearbeitung im Ordner IdahoGroup2 und User2 aus dessen Zuordnungen, und so weiter.

Beispielstruktur für ACL-Zuordnungen

Hier ist ein Diagramm der ACL-Zuordnungsstruktur für die fiktive Verzeichnishierarchie in der ADLS Gen2-Dokumentation.

Aktualisieren von ACL-Zuordnungen im Laufe der Zeit

Wiederholen Sie im Laufe der Zeit, wenn neue ACL-Zuweisungen hinzugefügt oder geändert werden, die vorherigen Schritte, um die ordnungsgemäße Verteilung und Berechtigungsausrichtung sicherzustellen. Aktualisierte Zugriffsrechte in ADLS Gen2 werden im Suchindex aktualisiert, wenn Sie den Inhalt mithilfe des Indexers oder einer Wissensquelle neu indizieren.

Konfigurieren von Azure KI-Suche

Erinnern Sie sich daran, dass der Suchdienst Folgendes haben muss:

• Rollenbasierter Zugriff aktiviert
• Verwaltete Identität konfiguriert

Autorisierung

Für die Indizierung muss der Client, der den API-Aufruf ausgibt, über die Berechtigung Suchdienstmitwirkender zum Erstellen von Objekten, die Berechtigung Indexdatenmitwirkender zum Importieren von Daten und die Berechtigung Suchindexdatenleser zum Abfragen eines Indexes verfügen.

Wenn Sie lokal testen, sollten Sie über die gleichen Rollenzuweisungen verfügen. Weitere Informationen finden Sie unter Mit Rollen zu Azure KI-Suche verbinden.

Konfigurieren einer Wissensquelle

Wenn Sie eine Wissensquelle verwenden, werden Definitionen in der Wissensquelle verwendet, um eine vollständige Indizierungspipeline (Indexer, Datenquelle und Index) zu generieren. ACL-Zuordnungen werden erkannt und automatisch in den generierten Index aufgenommen. Es ist nicht erforderlich, eines der generierten Objekte zu ändern, wenn Sie die Berechtigungsvererbung in Ihrem indizierten Inhalt wünschen.

Wichtige Punkte zu der Konfiguration, die für dieses Szenario geeignet ist:

• isADLSGen2 ist auf "true" festgelegt, soweit die Datenquellenanforderung für dieses Szenario erfüllt ist.
• ingestionPermissionOptions Gibt Benutzer- und Gruppen-IDs an.

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-01-preview
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": true,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
             "ingestionPermissionOptions": [
                "userIds","groupIds"
                           ],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}
###

Indexbasierte Indizierung konfigurieren

Wenn Sie einen Indexer verwenden, konfigurieren Sie ihn, die Datenquelle und den Index zum Abrufen von Berechtigungsmetadaten aus ADLS Gen2-Blobs.

Erstellen der Datenquelle

Dieser Abschnitt ergänzt Index-Daten aus ADLS Gen2 mit Informationen, die speziell für das Erfassen von Berechtigungen zusammen mit Dokumentinhalten in einem Azure KI-Suche Index spezifisch sind.

• Der Datenquellentyp muss sein adlsgen2.

• Die Datenquelle muss indexerPermissionOptions mit userIds, groupIdsund/oder rbacScopehaben.

  • Konfigurieren Sie für rbacScope die Verbindungszeichenfolge mit dem verwalteten Identitätsformat.

  • Für Verbindungszeichenfolgen mit einer vom Benutzer zugewiesenen verwalteten Identität müssen Sie auch die identity Eigenschaft angeben.

JSON-Beispiel mit vom System verwalteter Identität:

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    }
}

JSON-Schemabeispiel mit einer vom Benutzer verwalteten Identität im Verbindungszeichenfolge:

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    },
    "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

Erstellen von Berechtigungsfeldern im Index

Stellen Sie in Azure KI-Suche sicher, dass Ihr Index Felddefinitionen für die Berechtigungsmetadaten enthält. Berechtigungsmetadaten können indiziert werden, wenn indexerPermissionOptions in der Datenquellendefinition angegeben ist.

Empfohlene Schemaattribute für ACL (UserIds, GroupIds) und RBAC-Bereich:

• Benutzerkennung (ID)-Feld mit userIds Berechtigungsfilterwert.
• Gruppen-ID-Feld mit groupIds Erlaubnisfilterwert.
• RBAC-Bereichsfeld mit rbacScope permissionFilter-Wert.
• Eigenschaft permissionFilterOption zum Aktivieren der Filterung zur Abfragezeit.
• Verwenden von Zeichenfolgenfeldern für Berechtigungsmetadaten
• Setzen Sie filterable auf 'true' für alle Felder.

Beachten Sie, dass retrievable "false" lautet. Sie können die Einstellung während der Entwicklung auf "true" setzen, um zu überprüfen, ob Berechtigungen vorhanden sind. Denken Sie jedoch daran, die Einstellung auf "false" zurückzusetzen, bevor sie in die Produktionsumgebung eingebracht wird.

JSON-Schemabeispiel:

{
  ...
  "fields": [
    ...
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

Konfigurieren des Indexers

Feldzuweisungen in einem Indexer definieren den Datenpfad zu Feldern in einem Index. Ziel- und Zielfelder, die je nach Name oder Datentyp variieren, erfordern eine explizite Feldzuordnung. Die folgenden Metadatenfelder in ADLS Gen2 benötigen möglicherweise Feldzuordnungen, wenn Sie den Feldnamen variieren:

• metadata_user_ids (Collection(Edm.String)) – die ACL-Benutzer-IDs-Liste.
• metadata_group_ids (Collection(Edm.String)) – die Liste der ACL-Gruppen-IDs.
• metadata_rbac_scope (Edm.String) – der RBAC-Bereich des Containers.

Geben Sie fieldMappings im Indexer an, um die Berechtigungsmetadaten während der Indizierung an Zielfelder weiterzuleiten.

JSON-Schemabeispiel:

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Empfehlungen und bewährte Methoden

• Planen Sie die ADLS Gen2-Ordnerstruktur sorgfältig, bevor Sie Ordner erstellen.

• Organisieren Sie Identitäten nach Möglichkeit in Gruppen, und verwenden Sie Gruppen, anstatt den Zugriff direkt auf einzelne Benutzer zu gewähren. Das fortlaufende Hinzufügen einzelner Benutzer anstatt das Anwenden von Gruppen erhöht die Anzahl der Zugriffssteuerungseinträge, die nachverfolgt und ausgewertet werden müssen. Das Nichtbefolgen dieser bewährten Methode kann dazu führen, dass Sicherheits-Metadaten häufiger aktualisiert werden müssen, wenn sich diese Metadaten ändern, was zu erhöhten Verzögerungen und Ineffizienzen im Aktualisierungsprozess führt.

Berechtigungen zwischen indizierten und Quellinhalten synchronisieren

Das Aktivieren der ACL- oder RBAC-Anreicherung für einen Indexer funktioniert nur in zwei Situationen automatisch:

• Die erste vollständige Indizierungsausführung/Datendurchforstung: Alle Berechtigungsmetadaten, die zu diesem Zeitpunkt für jedes Dokument vorhanden sind, werden erfasst.

• Brandneue Dokumente, die nach Aktivierung der ACL/RBAC-Unterstützung hinzugefügt werden: Ihre ACL/RBAC-Informationen werden zusammen mit ihren Inhalten erfasst.

Wenn Sie Dokumentberechtigungen ändern, z. B. das Hinzufügen eines Benutzers zu einer ACL oder das Aktualisieren einer Rollenzuweisung, wird die Änderung nicht im Suchindex angezeigt, es sei denn, Sie weisen dem Indexer an, die Berechtigungsmetadaten des Dokuments erneut zu durchforsten.

Wählen Sie einen der folgenden Mechanismen aus, je nachdem, wie viele Elemente geändert wurden:

Beispiel für Resetdocs (Vorschau)-API:

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{ 
  "documentKeys": [ 
    "1001", 
    "4452" 
  ]
}

Beispiel für resync (Vorschau)-API:

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{ 
  "options": [ 
    "permissions" 
  ] 
} 

Nachverfolgung von Löschungen

Um blob-Löschung effektiv zu verwalten, stellen Sie sicher, dass die Löschnachverfolgung aktiviert ist, bevor der Indexer zum ersten Mal ausgeführt wird. Mit diesem Feature kann das System gelöschte Blobs in Ihrer Quelle erkennen und aus dem Index entfernen.

Verwandte Inhalte

• Verbindung zu Azure KI-Suche mit Rollen herstellen
• Abfragezeit ACL- und RBAC-Durchsetzung
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API