Filtres de sécurité pour découper les résultats de recherche Azure AI à l’aide d’Azure Active Directory

Article
02/15/2024

Cet article montre comment utiliser des identités de sécurité avec des filtres dans Recherche IA Azure pour réduire les résultats de la recherche en fonction de l’appartenance au groupe d’utilisateurs.

Cet article décrit les tâches suivantes :

Créer des groupes et des utilisateurs
Associer l’utilisateur au groupe que vous avez créé
Mettre en cache les nouveaux groupes
Indexer des documents avec des groupes associés
Émettre une demande de recherche avec un filtre d’identificateurs de groupe

Conditions préalables

Votre index dans Recherche IA Azure doit avoir un champ de sécurité pour stocker la liste des identités de groupe ayant accès en lecture au document. Ce cas d’usage suppose une correspondance un-à-un entre un élément sécurisable (tel que l’application collégiale d’une personne) et un champ de sécurité spécifiant qui a accès à cet élément (personnel d’admission).

Vous devez disposer d’autorisations d’administrateur client (propriétaire ou administrateur) pour créer des utilisateurs, des groupes et des associations.

Votre application doit également être inscrite en tant qu'application multilocataire, comme décrit dans la procédure suivante.

Inscrire votre application auprès d’Azure Active Directory

Cette étape intègre votre application à Azure Active Directory pour accepter les connexions des comptes d’utilisateur et de groupe. Si vous n’êtes pas administrateur de locataire dans votre organisation, vous devrez peut-être créer un nouveau locataire pour effectuer les étapes suivantes.

Dans portail Azure, recherchez le locataire Azure Active Directory.
Sur la gauche, sous Gérer, sélectionnez enregistrements d’applications, puis sélectionnez Nouvel enregistrement.
Donnez un nom à l’inscription, peut-être un nom similaire au nom de l’application de recherche. Reportez-vous à cet article pour plus d’informations sur d’autres propriétés facultatives.
Sélectionnez Inscrire.
Une fois l’inscription de l’application créée, copiez l’ID d’application (client). Vous devrez fournir cette chaîne à votre application.

Si vous parcourez pas à pas dotNetHowToSecurityTrimming, collez cette valeur dans le fichier app.config.
Copiez l’ID d'annuaire (tenant).
Sur la gauche, sélectionnez autorisations d’API, puis Ajouter une autorisation.
Sélectionnez Microsoft Graph, puis sélectionnez autorisations déléguées.
Recherchez, puis ajoutez les autorisations déléguées suivantes :
- Directory.ReadWrite.All
- Group.ReadWrite.All
- Utilisateur.LectureÉcriture.Tous
Microsoft Graph fournit une API qui autorise l’accès par programmation à Azure Active Directory via une API REST. L’exemple de code de cette procédure pas à pas utilise les autorisations permettant d’appeler l’API Microsoft Graph pour créer des groupes, des utilisateurs et des associations. Les API sont également utilisées pour mettre en cache les identificateurs de groupe pour accélérer le filtrage.
Sélectionnez Accorder le consentement de l’administrateur pour le locataire pour terminer le processus de consentement.

Créer des utilisateurs et des groupes

Si vous ajoutez une recherche à une application établie, vous pouvez avoir des identificateurs d’utilisateur et de groupe existants dans Azure Active Directory. Dans ce cas, vous pouvez ignorer les trois étapes suivantes.

Toutefois, si vous n’avez pas d’utilisateurs existants, vous pouvez utiliser les API Microsoft Graph pour créer les entités de sécurité. Les extraits de code suivants montrent comment générer des identificateurs, qui deviennent des valeurs de données pour le champ de sécurité dans votre index Recherche Azure AI. Dans notre demande hypothétique d’admission des collèges, il s’agirait des identificateurs de sécurité du personnel d’admission.

L’appartenance aux utilisateurs et aux groupes peut être très fluide, en particulier dans les grandes organisations. Le code qui génère des identités d’utilisateur et de groupe doit s’exécuter suffisamment souvent pour récupérer les modifications apportées à l’appartenance à l’organisation. De même, votre index Recherche Azure AI nécessite une planification de mise à jour similaire pour refléter l’état actuel des utilisateurs et ressources autorisés.

Étape 1 : créer un groupe

private static Dictionary<Group, List<User>> CreateGroupsWithUsers(string tenant)
{
    Group group = new Group()
    {
        DisplayName = "My First Prog Group",
        SecurityEnabled = true,
        MailEnabled = false,
        MailNickname = "group1"
    };

Étape 2 : Créer un utilisateur

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
};

Étape 3 : Associer un utilisateur et un groupe

List<User> users = new List<User>() { user1, user2 };
Dictionary<Group, List<User>> groups = new Dictionary<Group, List<User>>() { { group, users } };

Étape 4 : Mettre en cache les identificateurs de groupes

Si vous le souhaitez, pour réduire la latence du réseau, vous pouvez mettre en cache les associations de groupes d’utilisateurs afin que, lorsqu’une demande de recherche est émise, les groupes soient retournés à partir du cache, évitant un aller-retour supplémentaire. Vous pouvez utiliser 'API Batch pour envoyer une requête Http unique avec plusieurs utilisateurs et générer le cache.

Microsoft Graph est conçu pour gérer un volume élevé de requêtes. Si un nombre écrasant de requêtes se produit, Microsoft Graph échoue avec le code d’état HTTP 429. Pour plus d’informations, consultez de limitation Microsoft Graph.

Indexer le document avec les groupes autorisés

Les opérations de requête dans Recherche IA Azure sont exécutées sur un index Recherche IA Azure. Dans cette étape, une opération d’indexation importe des données pouvant faire l’objet d’une recherche dans un index, y compris les identificateurs utilisés comme filtres de sécurité.

Azure AI Search n’authentifie pas les identités utilisateur ou fournit une logique permettant d’établir le contenu qu’un utilisateur a l’autorisation d’afficher. Le cas d’usage du découpage de sécurité suppose que vous fournissez l’association entre un document sensible et l’identificateur de groupe ayant accès à ce document, importé intact dans un index de recherche.

Dans l’exemple hypothétique, le corps de la requête PUT d'un index Azure AI Search inclurait l’essai ou la transcription d’un candidat ainsi que l’identificateur de groupe ayant l’autorisation d’afficher ce contenu.

Dans l’exemple générique utilisé dans l’exemple de code pour cette procédure pas à pas, l’action d’index peut se présenter comme suit :

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);

Émettre une demande de recherche

À des fins de découpage de sécurité, les valeurs de votre champ de sécurité dans l’index sont des valeurs statiques utilisées pour inclure ou exclure des documents dans les résultats de recherche. Par exemple, si l’identificateur de groupe pour admissions est « A11B22C33D44-E55F66G77-H88I99JKK », tous les documents d’un index Recherche IA Azure ayant cet identificateur dans le champ de sécurité sont inclus (ou exclus) dans les résultats de recherche renvoyés à l’appelant.

Pour filtrer les documents retournés dans les résultats de recherche en fonction des groupes d’utilisateurs qui émettent la demande, passez en revue les étapes suivantes.

Étape 1 : Récupérer les identificateurs de groupe de l’utilisateur

Si les groupes de l'utilisateur n'ont pas déjà été mis en cache ou si le cache a expiré, effectuez la demande des groupes .

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);
}

Étape 2 : Composer la demande de recherche

En supposant que vous disposez de l’appartenance aux groupes de l’utilisateur, vous pouvez émettre la demande de recherche avec les valeurs de filtre appropriées.

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));
}

Étape 3 : Gérer les résultats

La réponse inclut une liste filtrée de documents, composée de ceux que l’utilisateur a l’autorisation d’afficher. Selon la façon dont vous construisez la page des résultats de recherche, vous pouvez inclure des indications visuelles pour refléter le jeu de résultats filtré.

Les points à emporter

Dans cette procédure pas à pas, vous avez appris un modèle d’utilisation des connexions utilisateur pour filtrer les documents dans les résultats de Recherche IA Azure, en réduisant les résultats des documents qui ne correspondent pas au filtre fourni sur la demande.

Partager via