Prise en main de la sécurité des documents de conversation pour Python

Lorsque vous générez une application de conversation à l’aide du modèle RAG (Récupération augmentée de génération augmentée) avec vos propres données, assurez-vous que chaque utilisateur reçoit une réponse en fonction de ses autorisations. Suivez le processus de cet article pour ajouter le contrôle d’accès aux documents à votre application de conversation.

• Utilisateur autorisé: cette personne doit avoir accès aux réponses contenues dans les documents de l’application de messagerie.

  

• Utilisateur non autorisé: cette personne ne doit pas avoir accès aux réponses de documents sécurisés qu'elle n'est pas autorisée à voir.

  

Remarque

Cet article utilise un ou plusieurs modèles d’application IA comme base pour les exemples et les conseils de l’article. Les modèles d’application IA vous fournissent des implémentations de référence bien gérées qui sont faciles à déployer. Ils aident à garantir un point de départ de haute qualité pour vos applications IA.

Vue d’ensemble de l’architecture

Sans fonctionnalité de sécurité de document, l’application de conversation d’entreprise a une architecture simple à l’aide d’Azure AI Search et d’Azure OpenAI. Une réponse est déterminée à partir de requêtes adressées à Recherche Azure AI où les documents sont stockés, en combinaison avec une réponse d'un modèle Azure OpenAI GPT. Aucune authentification utilisateur n’est utilisée dans ce flux simple.

Pour ajouter la sécurité des documents, vous devez mettre à jour l’application de conversation d’entreprise :

• Ajoutez l’authentification du client à l’application de conversation avec Microsoft Entra.
• Ajoutez une logique côté serveur pour remplir un index de recherche avec l’accès utilisateur et groupe.

Recherche Azure AI ne fournit pas de permissions natives au niveau des documents et ne peut pas faire varier les résultats de recherche à partir d'un index en fonction des permissions de l'utilisateur. Au lieu de cela, votre application peut utiliser des filtres de recherche pour vous assurer qu’un document est accessible à un utilisateur spécifique ou par un groupe spécifique. Dans votre index de recherche, chaque document doit avoir un champ filtrable qui stocke les informations d’identité d’utilisateur ou de groupe.

Étant donné que l’autorisation n’est pas contenue en mode natif dans Recherche IA Azure, vous devez ajouter un champ pour contenir les informations d’utilisateur ou de groupe, puis filtrer tous les documents qui ne correspondent pas. Pour implémenter cette technique, vous devez :

• Créez un champ de contrôle d’accès au document dans votre index dédié au stockage des détails des utilisateurs ou des groupes disposant d’un accès au document.
• Remplissez le champ de contrôle d’accès du document avec les détails pertinents de l’utilisateur ou du groupe.
• Mettez à jour ce champ de contrôle d’accès chaque fois qu’il y a des modifications apportées aux autorisations d’accès utilisateur ou de groupe.

Si vos mises à jour d’index sont planifiées avec un indexeur, les modifications sont récupérées lors de l’exécution suivante de l’indexeur. Si vous n’utilisez pas d’indexeur, vous devez réindexer manuellement.

Dans cet article, le processus de sécurisation des documents dans Azure AI Search est rendu possible grâce aux exemples de scripts , que vous pouvez exécuter en tant qu’administrateur de recherche. Les scripts associent un document unique à une identité d’utilisateur unique. Vous pouvez prendre ces scripts et appliquer vos propres exigences de sécurité et de production pour répondre à vos besoins.

Déterminer la configuration de la sécurité

La solution fournit des variables d’environnement booléennes pour activer les fonctionnalités nécessaires à la sécurité des documents dans cet exemple.

Paramètre	Objectif
AZURE_USE_AUTHENTICATION	Lorsqu’il est défini sur true, permet à l’utilisateur de se connecter à l’application de conversation et à l’authentification Azure App Service. Active Use oid security filter dans les paramètres de développement de l'application de chat.
AZURE_ENFORCE_ACCESS_CONTROL	Lorsqu’il est défini sur true, nécessite l’authentification pour tout accès au document. Les paramètres développeur pour l’ID d’objet (OID) et la sécurité de groupe sont activés et désactivés afin qu’ils ne puissent pas être désactivés à partir de l’interface utilisateur.
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS	Lorsqu’il est défini sur true, ce paramètre permet aux utilisateurs authentifiés de rechercher sur des documents qui n’ont aucun contrôle d’accès affecté, même lorsque le contrôle d’accès est requis. Ce paramètre ne doit être utilisé que lorsque AZURE_ENFORCE_ACCESS_CONTROL est activé.
AZURE_ENABLE_UNAUTHENTICATED_ACCESS	Lorsqu’il est défini sur true, ce paramètre permet aux utilisateurs non authentifiés d’utiliser l’application, même lorsque le contrôle d’accès est appliqué. Ce paramètre ne doit être utilisé que lorsque AZURE_ENFORCE_ACCESS_CONTROL est activé.

Utilisez les sections suivantes pour comprendre les profils de sécurité pris en charge dans cet exemple. Cet article configure le profil d'entreprise .

Entreprise : Compte requis + filtre de document

Chaque utilisateur du site doit se connecter. Le site contient du contenu public pour tous les utilisateurs. Le filtre de sécurité au niveau du document est appliqué à toutes les requêtes.

Variables d’environnement :

• AZURE_USE_AUTHENTICATION=true
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
• AZURE_ENFORCE_ACCESS_CONTROL=true

Utilisation mixte : compte facultatif + filtre de document

Chaque utilisateur du site peut se connecter. Le site contient du contenu public pour tous les utilisateurs. Le filtre de sécurité au niveau du document est appliqué à toutes les requêtes.

Variables d’environnement :

• AZURE_USE_AUTHENTICATION=true
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
• AZURE_ENFORCE_ACCESS_CONTROL=true
• AZURE_ENABLE_UNAUTHENTICATED_ACCESS=true

Conditions préalables

Un environnement de conteneur de développement est disponible avec toutes les dépendances requises pour compléter cet article. Vous pouvez exécuter le conteneur de développement dans GitHub Codespaces (dans un navigateur) ou localement à l’aide de Visual Studio Code.

Pour utiliser cet article, vous avez besoin des prérequis suivants :

• Un abonnement Azure. Créez-en un gratuitement.
• Autorisations de compte Azure : votre compte Azure doit avoir :
  • Permission de gérer des applications dans Microsoft Entra ID.
  • Autorisations Microsoft.Authorization/roleAssignments/write, telles que Administrateur de l’accès utilisateur ou Propriétaire.

Vous avez besoin de prérequis supplémentaires en fonction de votre environnement de développement préféré.

GitHub Codespaces (recommandé)

• compte GitHub

Visual Studio Code

• Azure Developer CLI.
• Docker Desktop. Démarrez Docker Desktop s’il n’est pas déjà en cours d’exécution.
• Visual Studio Code.
• Extension des conteneurs de développement.

Ouvrir un environnement de développement

Commencez maintenant par un environnement de développement sur lequel toutes les dépendances sont installées pour terminer cet article.

GitHub Codespaces (recommandé)

GitHub Codespaces exécute un conteneur de développement géré par GitHub avec Visual Studio Code pour le web comme interface utilisateur. Pour l’environnement de développement le plus simple, utilisez GitHub Codespaces afin que vous disposiez des outils de développement et des dépendances appropriés préinstallés pour terminer cet article.

Important

Tous les comptes GitHub peuvent utiliser GitHub Codespaces pour jusqu’à 60 heures gratuites chaque mois avec deux instances principales. Pour plus d’informations, consultez Le stockage mensuel inclus et les heures de cœur GitHub Codespaces.

1. Lancez le processus de création d'un nouvel espace de code mainGitHub sur la branche du référentiel GitHub Azure-Samples/azure-search-openai-demo.

2. Cliquez avec le bouton droit sur le bouton suivant, puis sélectionnez lien Ouvrir dans les nouvelles fenêtres pour que l’environnement de développement et la documentation soient disponibles en même temps.

   

3. Dans la page Créer un espace de code, passez en revue les paramètres de configuration de l’espace de code, puis sélectionnez Créer un espace de code.

   

4. Attendez que l’espace de code démarre. Ce processus de démarrage peut prendre quelques minutes.

5. Dans le terminal en bas de l’écran, connectez-vous à Azure avec Azure Developer CLI.

   azd auth login
   

6. Terminez le processus d’authentification.

7. Les tâches restantes de cet article se produisent dans le contexte de ce conteneur de développement.

Visual Studio Code

L’extension Dev Containers pour Visual Studio Code nécessite l’installation de Docker sur votre ordinateur local. L’extension héberge le conteneur de développement localement à l’aide de l’hôte Docker avec les outils de développement et les dépendances appropriés préinstallés pour terminer cet article.

1. Créez un répertoire local sur votre ordinateur pour le projet.

   mkdir my-intelligent-app && cd my-intelligent-app
   

2. Ouvrez Visual Studio Code dans ce répertoire.

   code .
   

3. Ouvrez un nouveau terminal dans Visual Studio Code.

4. Exécutez la commande AZD suivante pour placer le dépôt GitHub sur votre ordinateur local.

   azd init -t azure-search-openai-demo
   

5. Ouvrez la palette de commandes, puis recherchez et sélectionnez Dev Containers: Open Folder in Container (Conteneurs de développement : Ouvrir un dossier dans un conteneur) pour ouvrir le projet dans un conteneur de développement. Attendez que le conteneur de développement s’ouvre avant de continuer.

6. Connectez-vous à Azure avec Azure Developer CLI.

   azd auth login
   

   Copiez le code à partir du terminal, puis collez-le dans un navigateur. Suivez les instructions pour vous authentifier auprès de votre compte Azure.

7. Les autres exercices de ce projet ont lieu dans le contexte de ce conteneur de développement.

Obtenir les informations requises avec Azure CLI

Obtenez votre ID d’abonnement et votre ID de locataire avec la commande Azure CLI suivante. Copiez la valeur à utiliser comme valeur de AZURE_TENANT_ID.

az account list --query "[].{subscription_id:id, name:name, tenantId:tenantId}" -o table

Si vous obtenez une erreur concernant la stratégie d’accès conditionnel de votre locataire, vous avez besoin d’un deuxième locataire sans stratégie d’accès conditionnel.

• Votre première instance, associée à votre compte utilisateur, est utilisée pour la variable d'environnement AZURE_TENANT_ID.
• Votre deuxième locataire, sans accès conditionnel, est utilisé pour la variable d'environnement AZURE_AUTH_TENANT_ID afin d'accéder à Microsoft Graph. Pour les locataires avec une stratégie d’accès conditionnel, recherchez l’ID d’un deuxième locataire sans stratégie d’accès conditionnel ou créez un nouveau locataire.

Définir des variables d’environnement

1. Exécutez les commandes suivantes pour configurer l’application pour le profil Entreprise .

   azd env set AZURE_USE_AUTHENTICATION true
   azd env set AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS true
   azd env set AZURE_ENFORCE_ACCESS_CONTROL true
   

2. Exécutez la commande suivante pour définir le locataire, qui autorise la connexion de l’utilisateur à l’environnement d’application hébergé. Remplacez <YOUR_TENANT_ID> par l’ID de locataire.

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

Remarque

Si vous avez une stratégie d'accès conditionnel sur votre locataire utilisateur, vous devez spécifier un locataire d'authentification.

Déployer l’application de conversation sur Azure

Le déploiement se compose des étapes suivantes :

• Créez les ressources Azure.
• Chargez les documents.
• Créez les applications d’identité Microsoft Entra (client et serveur).
• Activez l’identité pour la ressource d’hébergement.

1. Exécutez la commande Azure Developer CLI suivante pour provisionner les ressources Azure et déployer le code source.

   azd up
   

2. Utilisez le tableau suivant pour répondre aux questions de déploiement AZD.

   Prompt	Répondre
   Nom de l’environnement	Utilisez un nom court avec des informations d’identification telles que votre alias et votre application. Par exemple, tjones-secure-chat.
   Abonnement	Sélectionnez un abonnement dans lequel créer les ressources.
   Emplacement des ressources Azure	Sélectionnez un emplacement près de vous.
   Emplacement de documentIntelligentResourceGroupLocation	Sélectionnez un emplacement près de vous.
   Emplacement de openAIResourceGroupLocation	Sélectionnez un emplacement près de vous.

   Attendez 5 ou 10 minutes après le déploiement de l’application pour permettre à l’application de démarrer.

3. Une fois l’application déployée, une URL s’affiche dans le terminal.

4. Sélectionnez l’URL étiquetée (✓) Done: Deploying service webapp pour ouvrir l’application de conversation dans un navigateur.

   

5. Acceptez la fenêtre contextuelle d’authentification de l’application.

6. Lorsque l’application de conversation s’affiche, notez dans le coin supérieur droit que votre utilisateur est connecté.

7. Ouvrez paramètres du développeur et notez que les deux options suivantes sont sélectionnées et désactivées pour modification :

   • Utiliser le filtre de sécurité OID
   • Utiliser un filtre de sécurité de groupes

8. Sélectionnez la carte avec Que fait un responsable de produit ?.

9. Vous obtenez une réponse telle que : Les sources fournies ne contiennent pas d’informations spécifiques sur le rôle d’un gestionnaire de produits chez Contoso Electronics.

   

Ouvrir l’accès à un document pour un utilisateur

Activez vos permissions pour le document exact afin que vous puissiez obtenir la réponse. Vous avez besoin de plusieurs informations :

• Azure Storage
  • Nom du compte
  • Nom du conteneur
  • URL du blob/document pour role_library.pdf
• ID de l’utilisateur dans l’ID Microsoft Entra

Lorsque ces informations sont connues, mettez à jour le champ oids d’index Recherche d’IA Azure pour le document role_library.pdf.

Obtenir l’URL d’un document dans le stockage

1. Dans le dossier .azure à la racine du projet, recherchez le répertoire d’environnement et ouvrez le fichier .env avec ce répertoire.

2. Recherchez l’entrée AZURE_STORAGE_ACCOUNT et copiez sa valeur.

3. Utilisez les commandes Azure CLI suivantes pour obtenir l’URL de l’objet blob role_library.pdf dans le conteneur content.

   az storage blob url \
       --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \
       --container-name 'content' \
       --name 'role_library.pdf' 
   

   Paramètre	Objectif
   --nom-du-compte	Nom du compte stockage Azure.
   --container-name	Le nom du conteneur dans cet exemple est content.
   --name	Le nom du blob dans cette étape est role_library.pdf.

4. Copiez l’URL de l’objet blob à utiliser ultérieurement.

Obtenir votre ID d’utilisateur

1. Dans l'application de chat, sélectionnez Paramètres du développeur.
2. Dans la section ID Token claims, copiez votre paramètre objectidentifier. Ce paramètre est connu dans la section suivante comme USER_OBJECT_ID.

Fournir un accès utilisateur à un document dans Recherche Azure

1. Utilisez le script suivant pour modifier le champ oids dans Recherche d’IA Azure pour role_library.pdf afin de pouvoir y accéder.

   ./scripts/manageacl.sh \
       -v \
       --acl-type oids \
       --acl-action add \
       --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
       --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Paramètre	Objectif
   -v	Sortie détaillée.
   --acl-type	OID de groupe ou d’utilisateur : oids.
   --acl-action	Ajouter à un champ d’index de recherche. D’autres options incluent remove, remove_allet list.
   --acl	Groupe ou utilisateur USER_OBJECT_ID.
   --url	Emplacement du fichier dans stockage Azure, tel que https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. N’entourez pas l’URL par des guillemets dans la commande CLI.

2. La sortie de la console pour cette commande ressemble à ceci :

   Loading azd .env file from current environment...
   Creating Python virtual environment "app/backend/.venv"...
   Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
   Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action add --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
   Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
   Adding acl 00000000-0000-0000-0000-000000000000 to 58 search documents
   

3. Si vous le souhaitez, utilisez la commande suivante pour vérifier que votre autorisation est répertoriée pour le fichier dans Recherche IA Azure.

   ./scripts/manageacl.sh \
       -v \
       --acl-type oids \
       --acl-action list \
       --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
       --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Paramètre	Objectif
   -v	Sortie détaillée.
   --acl-type	OID de groupe ou d’utilisateur : oids.
   --acl-action	Lister un champ d'index de recherche oids. D’autres options incluent remove, remove_allet list.
   --acl	Paramètre USER_OBJECT_ID du groupe ou de l’utilisateur.
   --url	L'emplacement du fichier dans cette émission, par exemple https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf N’entourez pas l’URL par des guillemets dans la commande CLI.

4. La sortie de la console pour cette commande ressemble à ceci :

   Loading azd .env file from current environment...
   Creating Python virtual environment "app/backend/.venv"...
   Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
   Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action view --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
   Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
   [00000000-0000-0000-0000-000000000000]
   

   Le tableau à la fin de la sortie inclut votre paramètre USER_OBJECT_ID et est utilisé pour déterminer si le document est utilisé dans la réponse avec Azure OpenAI.

Vérifiez qu’Azure AI Search contient votre USER_OBJECT_ID

1. Ouvrez le portail Azure et recherchez AI Search.

2. Sélectionnez votre ressource de recherche dans la liste.

3. Sélectionnez Rechercher index> de gestion.

4. Sélectionnez gptkbindex.

5. Sélectionnez Voir>Vue JSON.

6. Remplacez le JSON par le code JSON suivant :

   {
     "search": "*",
     "select": "sourcefile, oids",
     "filter": "oids/any()"
   }
   

   Ce fichier JSON recherche tous les documents où le champ oids a n’importe quelle valeur et retourne les champs sourcefile et oids.

7. Si le role_library.pdf n’a pas votre OID, revenez à la Fournir à l’utilisateur l’accès à un document dans la section Recherche Azure et effectuez les étapes.

Vérifier l’accès utilisateur au document

Si vous avez effectué les étapes mais que vous n’avez pas vu la réponse correcte, vérifiez que votre paramètre de USER_OBJECT_ID est correctement défini dans Recherche d’IA Azure pour role_library.pdf.

1. Revenez à l’application de conversation. Vous devrez peut-être vous reconnecter.

2. Entrez la même requête afin que le contenu role_library soit utilisé dans la réponse Azure OpenAI : What does a product manager do?.

3. Affichez le résultat, qui inclut désormais la réponse appropriée du document de bibliothèque de rôles.

   

Nettoyer les ressources

Les étapes suivantes vous guident tout au long du processus de nettoyage des ressources que vous avez utilisées.

Nettoyer les ressources Azure

Les ressources Azure créées dans cet article sont facturées à votre abonnement Azure. Si vous ne vous attendez pas à avoir besoin de ces ressources à l’avenir, supprimez-les pour éviter d’entraîner davantage de frais.

Exécutez la commande AZURE Developer CLI suivante pour supprimer les ressources Azure et supprimer le code source.

azd down --purge

Nettoyer GitHub Codespaces et Visual Studio Code

Les étapes suivantes vous guident tout au long du processus de nettoyage des ressources que vous avez utilisées.

GitHub Codespaces

La suppression de l'environnement GitHub Codespaces garantit que vous pouvez maximiser le nombre d'heures gratuites par cœur auxquelles vous avez droit pour votre compte.

Important

Pour plus d’informations sur les droits associés à votre compte GitHub, consultez Stockage et heures par cœur inclus chaque mois avec GitHub Codespaces.

1. Connectez-vous au tableau de bord GitHub Codespaces .

2. Localisez vos codespaces en cours d'exécution qui proviennent du référentiel GitHub Azure-Samples/azure-search-openai-demo.

   

3. Ouvrez le menu contextuel de l’espace de code, puis sélectionnez Supprimer.

   

Visual Studio Code

Vous n’êtes pas nécessairement obligé de nettoyer votre environnement local, mais vous pouvez arrêter le conteneur de développement en cours d’exécution et revenir à l’exécution de Visual Studio Code dans le contexte d’un espace de travail local.

1. Ouvrez la palette de commandes et recherchez les commandes des Dev Containers.

2. Sélectionnez Dev Containers : rouvrez le dossier localement.

   

Conseil

Visual Studio Code arrête le conteneur de développement en cours d’exécution, mais le conteneur existe toujours dans Docker dans un état arrêté. Vous avez toujours la possibilité de supprimer l’instance de conteneur, l’image conteneur et les volumes de Docker pour libérer davantage d’espace sur votre ordinateur local.

Obtenir de l’aide

Cet exemple de référentiel propose des informations de résolution des problèmes.

Dépannage

Cette section propose la résolution des problèmes spécifiques à cet article.

Fournir l'authentification du locataire

Lorsque votre authentification se trouve dans un locataire distinct de votre application d’hébergement, vous devez définir ce locataire d’authentification avec le processus suivant.

1. Exécutez la commande suivante pour configurer l’exemple afin d’utiliser un deuxième client pour le tenant d’authentification.

   azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
   

   Paramètre	Objectif
   AZURE_AUTH_TENANT_ID	Si AZURE_AUTH_TENANT_ID est défini, il s’agit du locataire qui héberge l’application.

2. Redéployez la solution avec la commande suivante :

   azd up
   

Contenu connexe

• Construisez une application de chat avec Azure OpenAI architecture de solution selon les bonnes pratiques.
• Découvrez le contrôle d'accès dans les applications d'IA générative avec Azure AI Search.
• Créez une solution Azure OpenAI prête à l'emploi pour l'entreprise avec Azure API Management.
• Découvrez Azure AI Search : surpasser la recherche vectorielle avec des capacités de récupération et de classement hybrides.