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é.
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 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.
Lancez le processus de création d'un nouvel espace de code
main
GitHub sur la branche du référentiel GitHub Azure-Samples/azure-search-openai-demo.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.
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.
Attendez que l’espace de code démarre. Ce processus de démarrage peut prendre quelques minutes.
Dans le terminal en bas de l’écran, connectez-vous à Azure avec Azure Developer CLI.
azd auth login
Terminez le processus d’authentification.
Les tâches restantes de cet article se produisent 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
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
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.
Exécutez la commande Azure Developer CLI suivante pour provisionner les ressources Azure et déployer le code source.
azd up
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.
Une fois l’application déployée, une URL s’affiche dans le terminal.
Sélectionnez l’URL étiquetée
(✓) Done: Deploying service webapp
pour ouvrir l’application de conversation dans un navigateur.Acceptez la fenêtre contextuelle d’authentification de l’application.
Lorsque l’application de conversation s’affiche, notez dans le coin supérieur droit que votre utilisateur est connecté.
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
Sélectionnez la carte avec Que fait un responsable de produit ?.
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
Dans le dossier
.azure
à la racine du projet, recherchez le répertoire d’environnement et ouvrez le fichier.env
avec ce répertoire.Recherchez l’entrée
AZURE_STORAGE_ACCOUNT
et copiez sa valeur.Utilisez les commandes Azure CLI suivantes pour obtenir l’URL de l’objet blob
role_library.pdf
dans le conteneurcontent
.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
.Copiez l’URL de l’objet blob à utiliser ultérieurement.
Obtenir votre ID d’utilisateur
- Dans l'application de chat, sélectionnez Paramètres du développeur.
- Dans la section ID Token claims, copiez votre paramètre
objectidentifier
. Ce paramètre est connu dans la section suivante commeUSER_OBJECT_ID
.
Fournir un accès utilisateur à un document dans Recherche Azure
Utilisez le script suivant pour modifier le champ
oids
dans Recherche d’IA Azure pourrole_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_all
etlist
.--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.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
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 incluentremove
,remove_all
etlist
.--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.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
Sélectionnez votre ressource de recherche dans la liste.
Sélectionnez Rechercher index> de gestion.
Sélectionnez gptkbindex.
Sélectionnez Voir>Vue JSON.
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 champssourcefile
etoids
.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
.
Revenez à l’application de conversation. Vous devrez peut-être vous reconnecter.
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?
.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.
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.
Localisez vos codespaces en cours d'exécution qui proviennent du référentiel GitHub Azure-Samples/azure-search-openai-demo.
Ouvrez le menu contextuel de l’espace de code, puis sélectionnez Supprimer.
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.
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.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.