Utiliser le contrôle des accès aux sources de données

Cette page explique comment appliquer le contrôle des accès aux sources de données pour les applications de recherche dans Vertex AI Agent Builder.

Le contrôle des accès à vos sources de données dans Vertex AI Agent Builder limite les données que les utilisateurs peuvent voir dans les résultats de votre appli de recherche. Google utilise votre fournisseur d'identité pour identifier l'utilisateur final effectuant une recherche et déterminer s'il a accès aux documents renvoyés en tant que résultats.

Par exemple, supposons que les employés de votre entreprise effectuent une recherche dans Confluence des documents à l'aide de votre application de recherche. Cependant, vous devez vous assurer qu'ils ne peuvent pas voir du contenu via l'application auxquels il n'est pas autorisé à accéder. Si vous avez configuré un pool d'employés dans Google Cloud pour le fournisseur d'identité de votre organisation, puis vous pouvez également spécifier ce pool d'employés dans Vertex AI Agent Builder. Désormais, si un employé utilise votre application, il ne reçoit des résultats de recherche que pour les documents auxquels son compte a déjà accès dans Confluence.

À propos du contrôle des accès aux sources de données

L'activation du contrôle des accès est une procédure ponctuelle.

Le contrôle des accès est disponible pour Cloud Storage, BigQuery, Google Drive et toutes les sources de données tierces.

Pour activer le contrôle des accès aux sources de données pour Vertex AI Agent Builder, vous devez au fournisseur d'identité de votre organisation configuré dans Google Cloud. Les frameworks d'authentification suivants sont compatibles :

  • Identité Google : si vous utilisez l'identité Google, toutes les identités et tous les groupes d'utilisateurs sont présents et gérés via Google Cloud. Pour en savoir plus sur Google Identity, consultez la documentation Google Identity.

  • Fédération de fournisseurs d'identité tiers: si vous utilisez une identité externe (Okta ou Azure AD, par exemple), vous devez configurer fédération des identités des employés dans Google Cloud avant de pouvoir activer le contrôle des accès aux sources de données pour Vertex AI Agent Builder.

    Si vous utilisez des connecteurs tiers, l'attribut google.subject doit être mappé sur le champ d'adresse e-mail du fournisseur d'identité externe. Voici des exemples google.subject et google.groups Mappages d'attributs pour les fournisseurs d'identité couramment utilisés:

Limites

Le contrôle des accès présente les limites suivantes :

  • 250 lecteurs sont autorisés par document. Chaque compte principal est comptabilisé comme un lecteur, un compte principal peut être un groupe ou un utilisateur individuel.
  • Vous pouvez sélectionner un fournisseur d'identité par emplacement compatible avec Vertex AI Search.
  • Le contrôle des accès n'est respecté que pour les identités et les groupes définis explicitement dans votre fournisseur d'identité. Identités ou groupes définis en mode natif dans les applications tierces.
  • Pour définir une source de données comme contrôlée par l'accès, vous devez sélectionner ce paramètre lors de la création du magasin de données. Vous ne pouvez pas activer ou désactiver ce paramètre pour un magasin de données existant.
  • La section Données > L'onglet Documents de la console n'affiche pas de données pour des sources de données soumises à un contrôle d'accès, car ces données ne doivent être visibles que les utilisateurs ayant un accès en lecture.
  • Pour prévisualiser les résultats de l'interface utilisateur des applications de recherche qui utilisent le contrôle d'accès tiers, vous devez vous connecter à la console fédérée ou utiliser l'application Web. Consultez Aperçu des résultats pour les applications contrôlées par l'accès.

Avant de commencer

Cette procédure suppose que vous avez configuré un fournisseur d'identité dans votre projet Google Cloud.

  • Google Identity : si vous utilisez Google Identity, vous pouvez passer à la procédure Se connecter à votre fournisseur d'identité.
  • Fournisseur d'identité tiers: assurez-vous d'avoir configuré une équipe d'identités de votre fournisseur d'identité tiers. Assurez-vous d'avoir spécifié des mappages d'attributs d'objet et de groupe lorsque vous configurez le pool d'employés. Pour en savoir plus sur les mappages d'attributs, consultez la section Mappages d'attributs dans la documentation IAM. Pour en savoir plus sur les pools d'identités de personnel, consultez la section Gérer les fournisseurs de pools d'identités de personnel dans la documentation IAM.

Se connecter à votre fournisseur d'identité

Spécifier un fournisseur d'identité pour Vertex AI Agent Builder et activer les données contrôle des accès code source, procédez comme suit:

  1. Dans la console Google Cloud, accédez à la page Agent Builder.

    Agent Builder

  2. Accédez à Paramètres > Authentification.

  3. Cliquez sur Ajouter un fournisseur d'identité pour l'établissement que vous souhaitez mettre à jour.

  4. Sélectionnez votre fournisseur d'identité dans la boîte de dialogue Add identity provider (Ajouter un fournisseur d'identité). Si vous sélectionnez un fournisseur d'identité tiers, sélectionnez également le bassin de main-d'œuvre qui s'applique à vos sources de données.

  5. Cliquez sur Enregistrer les modifications.

Configurer une source de données avec contrôle des accès

Pour appliquer un contrôle d'accès à une source de données, procédez comme suit en fonction du type de source de données que vous configurez :

Données non structurées de Cloud Storage

Lorsque vous configurez un magasin de données pour des données non structurées à partir de Cloud Storage, vous devez également importer des métadonnées de LCA et définir le magasin de données comme contrôlé par accès :

  1. Lorsque vous préparez vos données, incluez des informations ACL dans vos métadonnées à l'aide du champ acl_info. Exemple :

    {
   "id": "<your-id>",
   "jsonData": "<JSON string>",
   "content": {
     "mimeType": "<application/pdf or text/html>",
     "uri": "gs://<your-gcs-bucket>/directory/filename.pdf"
   },
   "acl_info": {
     "readers": [
       {
         "principals": [
           { "group_id": "group_1" },
           { "user_id": "user_1" }
         ]
       }
     ]
   }
 }

    Pour en savoir plus sur les données non structurées avec des métadonnées, consultez la section "Données non structurées" de Préparer les données à l'ingestion.

  2. Lorsque vous suivez la procédure de création de data store de la section Créer des données de recherche , vous pouvez activer le contrôle des accès dans la console ou à l'aide de l'API:

    • Console : lorsque vous créez un data store, sélectionnez Ce data store contient des informations sur le contrôle des accès.
    • API: lors de la création d'un data store, incluez l'option "aclEnabled": "true". dans votre charge utile JSON.

  3. Lorsque vous suivez la procédure d'importation de données décrite dans l'article Créer des données de recherche Google Store, effectuez les opérations suivantes:

    • Importez vos métadonnées avec les informations de la liste de contrôle d'accès à partir du même bucket que votre données non structurées
    • Si vous utilisez l'API, définissez GcsSource.dataSchema sur document.

Données structurées de Cloud Storage

Lorsque vous configurez un data store pour des données structurées provenant de Cloud Storage, vous devez aussi importer des métadonnées de LCA et définir les données stocker en tant que contrôle d'accès:

  1. Lorsque vous préparez vos données, incluez des informations ACL dans vos métadonnées à l'aide du champ acl_info. Exemple :

    {
   "id": "<your-id>",
   "jsonData": "<JSON string>",
   "acl_info": {
     "readers": [
       {
         "principals": [
           { "group_id": "group_1" },
           { "user_id": "user_1" }
         ]
       }
     ]
   }
 }

  2. Lorsque vous suivez la procédure de création d'un magasin de données dans Créer un magasin de données de recherche, vous pouvez activer le contrôle des accès en procédant comme suit dans la console ou à l'aide de l'API :

    • Console: lors de la création d'un data store, sélectionnez Ce data store contient des informations sur le contrôle des accès lors de la création du data store.
    • API: lors de la création d'data store, incluez l'option "aclEnabled": "true". dans votre charge utile JSON.

  3. Lorsque vous suivez les étapes d'importation de données dans Créer un entrepôt de données de recherche, veillez à effectuer les opérations suivantes :

    • Importez vos métadonnées avec les informations de la liste de contrôle d'accès à partir du même bucket que votre données non structurées
    • Si vous utilisez l'API, définissez GcsSource.dataSchema sur document

Données non structurées de BigQuery

Lorsque vous configurez un datastore pour les données non structurées à partir de BigQuery, vous devez définir le datastore comme contrôlé par l'accès et fournir des métadonnées ACL à l'aide d'un schéma prédéfini pour Vertex AI Search :

  1. Lorsque vous préparez vos données, spécifiez le schéma suivant. Ne pas utiliser de du schéma.

    [
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "content",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "mimeType",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
  {
    "name": "acl_info",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "readers",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
          {
            "name": "principals",
            "type": "RECORD",
            "mode": "REPEATED",
            "fields": [
              {
                "name": "user_id",
                "type": "STRING",
                "mode": "NULLABLE"
              },
              {
                "name": "group_id",
                "type": "STRING",
                "mode": "NULLABLE"
              }
            ]
          }
        ]
      }
    ]
  }
]

  2. Incluez vos métadonnées d'ACL en tant que colonne dans votre table BigQuery.

  3. Suivez la procédure décrite dans la section Créer des données de recherche Google Store, activez le contrôle des accès dans la console ou à l'aide de l'API:

    • Console: lors de la création d'un data store, sélectionnez Ce data store contient des informations sur le contrôle des accès lors de la création du data store.
    • API : lorsque vous créez un entrepôt de données, incluez l'indicateur "aclEnabled": "true" dans votre charge utile JSON.

  4. Lorsque vous suivez la procédure d'importation de données décrite dans l'article Créer des données de recherche store. Si vous utilisez l'API, définissez BigQuerySource.dataSchema vers document.

Données structurées de BigQuery

Lorsque vous configurez un data store pour des données structurées à partir de BigQuery, vous devez définir le data store comme contrôle d'accès et fournir des métadonnées LCA à l'aide d'un schéma prédéfini pour Vertex AI Search:

  1. Lorsque vous préparez vos données, spécifiez le schéma suivant. N'utilisez pas de schéma personnalisé.

    [
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "acl_info",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "readers",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
          {
            "name": "principals",
            "type": "RECORD",
            "mode": "REPEATED",
            "fields": [
              {
                "name": "user_id",
                "type": "STRING",
                "mode": "NULLABLE"
              },
              {
                "name": "group_id",
                "type": "STRING",
                "mode": "NULLABLE"
              }
            ]
          }
        ]
      }
    ]
  }
]

  2. Incluez vos métadonnées d'ACL en tant que colonne dans votre table BigQuery.

  3. Lorsque vous suivez la procédure décrite dans Créer un magasin de données de recherche, activez le contrôle des accès dans la console ou à l'aide de l'API :

    • Console: lors de la création d'un data store, sélectionnez Ce data store contient des informations sur le contrôle des accès lors de la création du data store.
    • API: lors de la création d'un data store, incluez l'option "aclEnabled": "true". dans votre charge utile JSON.

  4. Lorsque vous suivez les étapes d'importation de données dans Créer un data store de recherche, veillez à effectuer les opérations suivantes :

    • Si vous utilisez la console, lorsque vous spécifiez le type de données que vous importez, sélectionnez JSONL pour les données structurées avec métadonnées.
    • Si vous utilisez l'API, définissez BigQuerySource.dataSchema sur document

Prévisualiser les résultats pour les applications avec contrôle d'accès tiers

Pour prévisualiser les résultats dans la console pour les applications avec contrôle des accès tiers, vous devez vous connecter avec les identifiants de votre organisation.

Vous pouvez prévisualiser les résultats de l'interface utilisateur de deux manières:

Prévisualiser les résultats dans la console de fédération des identités des employés

Pour afficher les résultats à l'aide de la console de fédération des identités des employés, procédez comme suit:

  1. Dans la console Google Cloud, accédez à la page Agent Builder.

    Agent Builder

  2. Cliquez sur le nom de l'application de recherche dont vous souhaitez prévisualiser les résultats.

  3. Accédez à la page Aperçu.

  4. Cliquez sur Prévisualiser les résultats avec l'identité fédérée pour accéder à la console de la fédération d'identité de personnel.

  5. Saisissez le fournisseur de votre pool d'employés et les identifiants de votre organisation.

  6. Prévisualisez les résultats de votre application sur la page Aperçu qui s'affiche.

    Pour en savoir plus sur l'aperçu des résultats de recherche, consultez la section Obtenir les résultats de recherche.

Pour en savoir plus sur la console de la fédération des identités des employés, consultez la section À propos de la console (fédération).

Accorder des autorisations de recherche à vos utilisateurs

Pour permettre à vos utilisateurs de rechercher des données contrôlées par l'accès à l'aide de votre application, vous devez accorder l'accès aux utilisateurs de votre domaine ou de votre pool de personnel. Google recommande d'attribuer un rôle IAM personnalisé à votre groupe d'utilisateurs.

  • Identité Google: si vous utilisez l'identité Google, Google vous recommande d'utiliser vous créez un groupe Google inclut tous les employés qui doivent effectuer des recherches. Si vous êtes administrateur Google Workspace, vous pouvez inclure tous les utilisateurs d'une organisation dans un groupe Google en suivant la procédure décrite dans Ajouter tous les utilisateurs de votre organisation à un groupe.
  • Fournisseur d'identité tiers: si vous utilisez un fournisseur d'identité externe, (Okta ou Azure AD, par exemple), puis ajoutez tous les membres de votre pool d'employés à un dans un seul groupe.

Google vous recommande de créer un rôle IAM personnalisé à attribuer à votre groupe d'utilisateurs, à l'aide des autorisations suivantes:

  • discoveryengine.answers.get
  • discoveryengine.servingConfigs.answer
  • discoveryengine.servingConfigs.search
  • discoveryengine.sessions.get

Pour en savoir plus sur les autorisations pour les ressources de l'outil de création d'agents Vertex AI à l'aide d'Identity and Access Management (IAM), consultez la section Contrôle des accès avec IAM.

Pour en savoir plus sur les rôles personnalisés, consultez la section Rôles personnalisés dans consultez la documentation IAM.

Autoriser le widget Recherche

Si vous souhaitez déployer un widget Recherche pour une application dont l'accès est contrôlé, suivez ces étapes:

  1. Attribuer le rôle Lecteur Discovery Engine aux utilisateurs de votre domaine ou de vos équipes qui doivent appeler l'API de recherche.

  2. Générez des jetons d'autorisation à transmettre à votre widget :

  3. Suivez la procédure décrite dans Ajouter un widget avec un jeton d'autorisation pour transmettre le jeton à votre widget.

Activer l'application Web

L'application Web est un site dédié généré par Vertex AI Search, dans lequel vous et tout autre utilisateur disposant d'identifiants de connexion peut utiliser votre application de recherche.

Pour fournir l'application de recherche aux utilisateurs sans avoir à intégrer le widget de recherche ou l'API de recherche dans votre propre application, vous pouvez fournir l'URL de l'application Web à vos utilisateurs.

Pour activer l'application Web, procédez comme suit:

  1. Dans la console Google Cloud, accédez à la page Agent Builder.

    Agent Builder

  2. Cliquez sur le nom de l'application de recherche pour laquelle vous souhaitez créer une application Web.

  3. Accédez à l'onglet Integration > UI (Intégration > Interface utilisateur).

  4. Cliquez sur Activer l'application Web.

  5. Si vous utilisez la fédération d'identité de personnel, sélectionnez un fournisseur de pool de personnel.

  6. Cliquez sur le lien vers votre application Web.

  7. Saisissez le fournisseur de votre pool d'employés et les identifiants de votre organisation.

  8. Prévisualisez les résultats de votre application.

  9. Pour configurer les résultats de l'application Web, consultez Configurer les résultats du widget Recherche. Toutes les configurations du widget s'appliquent également à l'application Web.

  10. Facultatif : Pour fournir l'application de recherche à vos utilisateurs via cette application Web dédiée, copiez l'URL et envoyez-la aux utilisateurs disposant d'identifiants de connexion. Ils peuvent ajouter l'URL de l'application Web à leurs favoris et y accéder pour utiliser votre application de recherche.

Pour en savoir plus sur l'obtention des résultats de recherche, consultez la section Obtenir les résultats de recherche.