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

Article
06/15/2024

Lorsque vous générez une application de conversation à l’aide du modèle RAG 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.

Un utilisateur autorisé doit avoir accès aux réponses contenues dans les documents de l’application de conversation.

Capture d’écran de l’application de conversation avec réponse avec accès d’authentification requis.

Un utilisateur non autorisé ne doit pas avoir accès aux réponses à partir de documents sécurisés qu’il n’a pas l’autorisation de voir.

Capture d’écran de l’application de conversation avec réponse indiquant que l’utilisateur n’a pas accès aux données.

Remarque

Cet article utilise un ou plusieurs modèles d’application IA comme base pour les exemples et les conseils qu’il contient. Les modèles d’application IA vous fournissent des implémentations de référence bien gérées et faciles à déployer, qui constituent un point de départ de 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 vers Recherche IA Azure 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.

Diagramme architectural montrant une réponse déterminée à partir de requêtes vers Recherche IA Azure où les documents sont stockés, en combinaison avec une réponse rapide d’Azure OpenAI.

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.

Diagramme architectural montrant une utilisation de l’authentification avec l’ID Microsoft Entra, puis en passant cette authentification à Recherche IA Azure.

Azure AI Search ne fournit pas d’autorisations au niveau du document natif et ne peut pas varier les résultats de recherche à partir d’un index par les autorisations 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 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 Recherche IA Azure est rendu possible avec des exemples de scripts que vous exécutez 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 effectuer une mise à l’échelle à 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 `true`sur , permet à l’utilisateur de se connecter à l’application de conversation et à l’authentification App Service. `Use oid security filter` Active dans les paramètres du développeur de l’application de conversation.
`AZURE_ENFORCE_ACCESS_CONTROL`	Lorsqu’il est défini `true`sur , nécessite l’authentification pour tout accès au document. Les paramètres du développeur pour la sécurité d’oid et 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 `true`sur , 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é qu’en cas `AZURE_ENFORCE_ACCESS_CONTROL` d’activation.
`AZURE_ENABLE_UNAUTHENTICATED_ACCESS`	Lorsqu’il est défini `true`sur , 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é qu’en cas `AZURE_ENFORCE_ACCESS_CONTROL` d’activation.

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

Entreprise : Compte requis + filtre de document

Chaque utilisateur du site doit se connecter et 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 et le site contient du contenu public à 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

Prérequis

Un environnement de conteneur de développement est disponible avec toutes les dépendances requises pour terminer 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 :

Abonnement Azure. Créez-en un gratuitement
Autorisations de compte Azure : votre compte Azure doit avoir
- Autorisation de gestion des applications dans l’ID Microsoft Entra.
- Autorisations Microsoft.Authorization/roleAssignments/write, telles que l’administrateur d’accès utilisateur ou le propriétaire.
Accès accordé à Azure OpenAI dans l’abonnement Azure souhaité. L’accès à ce service n’est accordé qu’à l’application. Vous pouvez demander l’accès à Azure OpenAI en complétant le formulaire à l’adresse https://aka.ms/oai/access.

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

Codespaces (recommandé)
Visual Studio Code

Compte GitHub

Environnement de développement ouvert

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

GitHub Codespaces (recommandé)
Visual Studio Code

GitHub Codespaces exécute un conteneur de développement géré par GitHub avec Visual Studio Code pour le web comme interface utilisateur. Pour un environnement de développement le plus simple, utilisez GitHub Codespaces pour disposer 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 codespaces pendant jusqu’à 60 heures gratuites chaque mois avec 2 instances principales. Pour plus d’informations, consultez Le stockage mensuel inclus et les heures de cœur GitHub Codespaces.

Démarrez le processus pour créez un environnement GitHub Codespace sur la branche main du référentiel GitHub Azure-Samples/azure-search-openai-demo.
Cliquez avec le bouton droit sur le bouton suivant, puis sélectionnez Ouvrir le lien 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 codespace , passez en revue les paramètres de configuration du codespace, puis sélectionnez Créer un codespace
Attendez que le codespace 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 s’effectuent dans ce conteneur de développement.

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.

Créez un répertoire local sur votre ordinateur pour le projet.
```
mkdir my-intelligent-app && cd my-intelligent-app
```
Ouvrez Visual Studio Code dans ce répertoire :
```
code .
```
Ouvrez un nouveau terminal dans Visual Studio Code.
Exécutez la commande AZD suivante pour placer le dépôt GitHub sur votre ordinateur local.
```
azd init -t azure-search-openai-demo
```
Ouvrez la palette de commandes, recherchez et sélectionnez Conteneurs de développement : ouvrez le dossier dans le conteneur pour ouvrir le projet dans un conteneur de développement. Attendez que le conteneur de développement s’ouvre avant de continuer.
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 avec votre compte Azure.
Les exercices restants 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 votre 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 premier locataire, associé à votre compte d’utilisateur, est utilisé pour la variable d’environnement AZURE_TENANT_ID .
Votre deuxième locataire, sans accès conditionnel, est utilisé pour la AZURE_AUTH_TENANT_ID variable d’environnement pour 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 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 l’utilisateur à se connecter à l’environnement d’application hébergée. Remplacez <YOUR_TENANT_ID> par l’ID de locataire.
```
azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
```

Remarque

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

Déployer une application de conversation sur Azure

Le déploiement inclut la création des ressources Azure, le chargement des documents, la création des applications d’identité Microsoft Entra (client &serveur) et l’activation de 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 invites de déploiement AZD :

Prompt	Réponse
Nom de l’environnement	Utilisez un nom court avec des informations d’identification telles que votre alias et votre application : `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 chez vous.
Emplacement pour `documentIntelligentResourceGroupLocation`	Sélectionnez un emplacement près de chez vous.
Emplacement pour `openAIResourceGroupLocation`	Sélectionnez un emplacement près de chez 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 avec succès, une URL s’affiche dans le terminal.
Sélectionnez cette 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 les paramètres du développeur et notez que ces deux options sont sélectionnées et grisées (désactivées pour modification).
- Utiliser le filtre de sécurité oid
- Utiliser le filtre de sécurité des groupes
Sélectionnez la carte avec What does a product manager do?.
Vous obtenez une réponse comme suit : The provided sources do not contain specific information about the role of a Product Manager at Contoso Electronics.

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

Activez vos autorisations pour le document exact afin d’obtenir la réponse. Ces éléments nécessitent plusieurs informations :

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

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

Obtenir l’URL d’un document dans le stockage

Dans le .azure dossier à la racine du projet, recherchez le répertoire d’environnement et ouvrez le .env fichier 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 conteneur de contenu .

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

Paramètre	Objectif
--account-name	Nom du compte de stockage Azure
--container-name	Le nom du conteneur dans cet exemple est `content`
--name	Le nom de l’objet 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 chap, sélectionnez Paramètres du développeur.
Dans la section revendications du jeton d’ID, copiez votre objectidentifierfichier . Ceci est connu dans la section suivante sous le USER_OBJECT_IDnom de .

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

Utilisez le script suivant pour modifier le oids champ dans Recherche 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	ID d’objet de groupe ou d’utilisateur (OID) : `oids`
--acl-action	Ajouter à un champ d’index de recherche. D’autres options incluent `remove`, `remove_all`. `list`
--ACL	Groupe ou utilisateur `USER_OBJECT_ID`
--URL	Emplacement du fichier dans le stockage Azure, par `https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf`exemple . N’entourez pas l’URL avec 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	Groupe ou utilisateur (oids) : `oids`
--acl-action	Répertorier un champ `oids`d’index de recherche . D’autres options incluent `remove`, `remove_all`. `list`
--ACL	Groupe ou utilisateur `USER_OBJECT_ID`
--URL	Emplacement du fichier dans le stockage Azure, par `https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf`exemple . N’entourez pas l’URL avec 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 USER_OBJECT_ID et est utilisé pour déterminer si le document est utilisé dans la réponse avec Azure OpenAI.

Vérifier qu’Azure AI Search contient votre USER_OBJECT_ID

Ouvrez le Portail Azure et recherchez votre AI Search.
Sélectionnez votre ressource de recherche dans la liste.
Sélectionnez Gestion de la recherche -> Index.
Sélectionnez le gptkbindex.
Sélectionnez Affichage -> Vue JSON.
Remplacez le JSON par le code JSON suivant.
```
{
  "search": "*",
  "select": "sourcefile, oids",
  "filter": "oids/any()"
}
```
Cette opération recherche tous les documents dans lesquels le oids champ a une valeur et retourne les champs et oids les sourcefilechamps.
Si votre role_library.pdf oid n’est pas défini, revenez à l’utilisateur Fournir l’accès utilisateur à 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 USER_OBJECT_ID est correctement défini dans Recherche d’IA Azure pour cela role_library.pdf.

Revenez à l’application de conversation. Vous devrez peut-être vous reconnecter.
Entrez la même requête afin que le role_library contenu 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

Nettoyage des ressources Azure

Les ressources Azure créées dans cet article sont facturées dans votre abonnement Azure. Si vous pensez ne plus avoir besoin de ces ressources, supprimez-les pour éviter des frais supplémentaires.

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

azd down --purge

La suppression de l’environnement GitHub Codespaces vous permet d’optimiser le nombre d’heures gratuites par cœur que vous obtenez pour votre compte.

Important

Pour plus d’informations sur les droits de votre compte GitHub, consultez GitHub Codespaces mensuel inclus stockage et heures principales.

Connectez-vous au tableau de bord GitHub Codespaces (https://github.com/codespaces).
Localisez vos codespaces en cours d’exécution provenant du référentiel GitHub Azure-Samples/azure-search-openai-demo.
Ouvrez le menu contextuel du codespace, 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 un locataire d’authentification

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 locataire pour le locataire 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 elle est définie, il s’agit du locataire qui héberge l’application.
Redéployez la solution avec la commande suivante.
```
azd up
```

Partager via