Sicherheitsfilter zum Einschränken von Azure AI Search-Ergebnissen mithilfe von Microsoft Entra-Mandanten und -Identitäten
Dieser Artikel zeigt, wie Sie mithilfe von Microsoft Entra-Sicherheitsidentitäten und Filtern in Azure AI Search Suchergebnisse basierend auf der Benutzergruppenmitgliedschaft einschränken.
In diesem Artikel werden die folgenden Aufgaben behandelt:
- Erstellen von Microsoft Entra-Gruppen und -Benutzern
- Zuordnen des Benutzers zur erstellten Gruppe
- Zwischenspeichern der neuen Gruppen
- Indizieren von Dokumenten mit zugeordneten Gruppen
- Ausgeben einer Suchanfrage mit Gruppenbezeichnerfilter
Voraussetzungen
Ihr Index in Azure AI Search muss ein Sicherheitsfeld zum Speichern der Liste mit Gruppenidentitäten enthalten, die über Lesezugriff auf das Dokument verfügen. Dieser Anwendungsfall geht von einer 1:1-Zuordnung zwischen einem sicherungsfähigen Objekt (z.B. der Hochschulbewerbung einer Einzelperson) und einem Sicherheitsfeld aus, in dem festgelegt ist, wer Zugriff auf dieses Objekt hat (Zulassungspersonal).
Sie müssen über Microsoft Entra-Administratorberechtigungen (Besitzer oder Administrator) verfügen, um Benutzer, Gruppen und Zuordnungen zu erstellen.
Ihre Anwendung muss außerdem als mehrinstanzenfähige App bei Microsoft Entra ID registriert werden, wie im folgenden Verfahren beschrieben.
Registrieren Ihrer Anwendung mit Microsoft Entra ID
In diesem Schritt wird Ihre Anwendung in Microsoft Entra ID integriert, um Anmeldungen von Benutzer- und Gruppenkonten zu akzeptieren. Wenn Sie nicht als Mandantenadministrator in Ihrer Organisation fungieren, müssen Sie möglicherweise einen neuen Mandanten erstellen, um die folgenden Schritte auszuführen.
Suchen Sie im Azure-Portal den Microsoft Entra ID-Mandanten.
Suchen Sie auf der linken Seite unter Verwalten nach App-Registrierungen, und klicken Sie dann auf New registration (Neue Registrierung).
Benennen Sie die Registrierung. Verwenden Sie dabei beispielsweise einen Namen, der dem Namen der Suchanwendung ähnelt. Informationen zu anderen optionalen Eigenschaften finden Sie in diesem Artikel.
Wählen Sie Registrieren aus.
Sobald die App-Registrierung erstellt wurde, kopieren Sie die Anwendungs-ID (die ID des Clients). Sie müssen diese Zeichenfolge für Ihre Anwendung bereitstellen.
Wenn Sie DotNetHowToSecurityTrimming durchlaufen, fügen Sie diesen Wert in die Datei app.config ein.
Kopieren Sie den Wert unter Verzeichnis-ID (Mandant).
Wählen Sie auf der linken Seite API-Berechtigungen und dann Berechtigung hinzufügen aus.
Wählen Sie Microsoft Graph und dann Delegierte Berechtigungen aus.
Suchen Sie nach den folgenden delegierten Berechtigungen, und fügen Sie sie hinzu:
- Directory.ReadWrite.All
- Group.ReadWrite.All
- User.ReadWrite.All
Microsoft Graph stellt eine API bereit, die über eine REST-API programmgesteuerten Zugriff auf Microsoft Entra ID bietet. Das Codebeispiel für diese exemplarische Vorgehensweise verwendet die Berechtigungen zum Aufrufen der Microsoft Graph-API, um Gruppen, Benutzer und Zuordnungen zu erstellen. Die APIs werden außerdem zum Zwischenspeichern von Gruppenbezeichnern für eine schnellere Filterung verwendet.
Wählen Sie Administratoreinwilligung für Mandant erteilen aus, um den Einwilligungsprozess abzuschließen.
Erstellen von Benutzern und Gruppen
Wenn Sie einer vorhandenen Anwendung eine Suchfunktion hinzufügen, liegen in Microsoft Entra ID möglicherweise bereits Benutzer- und Gruppenbezeichner vor. In diesem Fall können Sie die nächsten drei Schritte überspringen.
Wenn Sie jedoch über keine vorhandenen Benutzer verfügen, können Sie die Sicherheitsprinzipale mithilfe der Microsoft Graph-APIs erstellen. Die folgenden Codeschnipsel veranschaulichen, wie Sie Bezeichner generieren, die zu Datenwerten für das Sicherheitsfeld in Ihrem Azure AI Search-Index werden. In unserer hypothetischen Anwendung für die Hochschulzulassung entspräche dies den Sicherheitsbezeichnern für das Zulassungspersonal.
Die Benutzer- und Gruppenmitgliedschaft kann sich – besonders in großen Organisationen – häufig ändern. Code zum Erstellen von Benutzer- und Gruppenidentitäten muss häufig genug ausgeführt werden, um Änderungen in der Organisationsmitgliedschaft zu erfassen. Ebenso erfordert Ihr Azure AI Search-Index einen ähnlichen Updateplan, um den aktuellen Status der zugelassenen Benutzer und Ressourcen widerzuspiegeln.
Schritt 1: Erstellen einer Gruppe
private static Dictionary<Group, List<User>> CreateGroupsWithUsers(string tenant)
{
Group group = new Group()
{
DisplayName = "My First Prog Group",
SecurityEnabled = true,
MailEnabled = false,
MailNickname = "group1"
};
Schritt 2: Erstellen eines Benutzers
User user1 = new User()
{
GivenName = "First User",
Surname = "User1",
MailNickname = "User1",
DisplayName = "First User",
UserPrincipalName = String.Format("user1@{0}", tenant),
PasswordProfile = new PasswordProfile() { Password = "********" },
AccountEnabled = true
};
Schritt 3: Zuordnen von Benutzer und Gruppe
List<User> users = new List<User>() { user1, user2 };
Dictionary<Group, List<User>> groups = new Dictionary<Group, List<User>>() { { group, users } };
Schritt 4: Zwischenspeichern der Gruppenbezeichner
Um die Netzwerklatenz zu verringern, können Sie optional die Benutzer-Gruppen-Zuordnungen zwischenspeichern, sodass bei einer Suchanfrage Gruppen aus dem Cache zurückgegeben werden und ein Roundtrip zu Microsoft Entra ID entfällt. Sie können mit der Microsoft Entra-Batch-API eine einzelne HTTP-Anforderung mit mehreren Benutzern senden und den Cache erstellen.
Microsoft Graph ist für die Verarbeitung einer großen Anzahl von Anforderungen konzipiert. Wenn die Anzahl von Anforderungen zu hoch ist, gibt Microsoft Graph einen Fehler mit dem HTTP-Statuscode 429 aus. Weitere Informationen finden Sie unter Microsoft Graph-Drosselung.
Indizieren von Dokumenten mit den zugelassenen Gruppen
Abfragevorgänge in Azure AI Search werden über einen Azure AI Search-Index ausgeführt. In diesem Schritt importiert ein Indizierungsvorgang durchsuchbare Daten in einen Index, die als Sicherheitsfilter verwendeten Bezeichner eingeschlossen.
Azure AI Search führt keine Authentifizierung von Benutzeridentitäten durch und stellt keine Logik zur Verfügung, um festzustellen, welche Inhalte ein Benutzer anzeigen darf. Im Anwendungsfall für die Sicherheitskürzung wird davon ausgegangen, dass Sie für die Zuordnung zwischen einem sensiblen Dokument und dem Gruppenbezeichner sorgen, der Zugriff auf dieses Dokument hat, und dass diese Informationen vollständig in einen Suchindex importiert wurden.
Im hypothetischen Beispiel würde der Textkörper der PUT-Anforderung in einem Azure AI Search-Index den Aufsatz oder die Aufzeichnung eines Bewerbers für eine Hochschule sowie den Gruppenbezeichner enthalten, der die Berechtigung zur Anzeige dieses Inhalts erteilt.
Im generischen Beispiel, das im Codebeispiel für diese exemplarische Vorgehensweise verwendet wird, könnte die Indexaktion wie folgt aussehen:
private static void IndexDocuments(string indexName, List<string> groups)
{
IndexDocumentsBatch<SecuredFiles> batch = IndexDocumentsBatch.Create(
IndexDocumentsAction.Upload(
new SecuredFiles()
{
FileId = "1",
Name = "secured_file_a",
GroupIds = new[] { groups[0] }
}),
...
};
IndexDocumentsResult result = searchClient.IndexDocuments(batch);
Ausgeben einer Suchanfrage
Zum Zweck der Sicherheitskürzung sind die Werte im Sicherheitsfeld des Index statische Werte, die zum Ein- oder Ausschließen von Dokumenten in Suchergebnissen verwendet werden. Wenn der Gruppenbezeichner für Zulassungen beispielsweise „A11B22C33D44-E55F66G77-H88I99JKK“ lautet, werden alle Dokumente in einem Azure AI Search-Index, die diesen Bezeichner im Sicherheitsfeld enthalten, in die an den Aufrufer gesendeten Suchergebnissen eingeschlossen (oder aus diesen ausgeschlossen).
Um die in Suchergebnissen zurückgegebenen Dokumente basierend nach Gruppen von Benutzern zu filtern, die die Anforderung ausgeben, führen Sie die folgenden Schritte aus.
Schritt 1: Abrufen der Gruppenbezeichner des Benutzers
Wenn die Gruppen des Benutzers nicht bereits zwischengespeichert wurden oder der Cache abgelaufen ist, geben Sie die groups-Anforderung aus.
private static async void RefreshCache(IEnumerable<User> users)
{
HttpClient client = new HttpClient();
var userGroups = await _microsoftGraphHelper.GetGroupsForUsers(client, users);
_groupsCache = new ConcurrentDictionary<string, List<string>>(userGroups);
}
Schritt 2: Erstellen der Suchanfrage
Vorausgesetzt, dass Sie über die Gruppenmitgliedschaft des Benutzers verfügen, können Sie die Suchanfrage mit den geeigneten Filterwerten ausgeben.
private static void SearchQueryWithFilter(string user)
{
// Using the filter below, the search result will contain all documents that their GroupIds field
// contain any one of the Ids in the groups list
string filter = String.Format("groupIds/any(p:search.in(p, '{0}'))", string.Join(",", String.Join(",", _groupsCache[user])));
SearchOptions searchOptions =
new SearchOptions()
{
Filter = filter
};
searchOptions.Select.Add("name");
SearchResults<SecuredFiles> results = searchClient.Search<SecuredFiles>("*", searchOptions);
Console.WriteLine("Results for groups '{0}' : {1}", _groupsCache[user], results.GetResults().Select(r => r.Document.Name));
}
Schritt 3: Verarbeiten der Ergebnisse
Die Antwort umfasst eine gefilterte Liste mit Dokumenten, für die der Benutzer über Anzeigeberechtigungen verfügt. Je nachdem, wie Sie die Seite mit den Suchergebnissen aufbauen, können Sie visuelle Hinweise zum gefilterten Resultset einschließen.
Nächste Schritte
In dieser exemplarischen Vorgehensweise haben Sie ein Muster zur Verwendung von Microsoft Entra-Anmeldungen zum Filtern von Dokumenten in Azure AI Search-Ergebnissen kennengelernt, um Dokumente aus den Ergebnissen auszuschließen, die nicht mit den Filtern der Anforderung übereinstimmen. Um ein alternatives, womöglich einfacheres Muster anzuzeigen oder erneut auf andere Sicherheitsfeatures zuzugreifen, verwenden Sie die folgenden Links: