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 consulter dans les résultats de votre application 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, imaginons que les employés de votre entreprise effectuent des recherches dans les documents Confluence à l'aide de votre application de recherche. Toutefois, vous devez vous assurer qu'ils ne peuvent pas afficher du contenu via l'application auquel ils n'ont pas accès. Si vous avez configuré un pool de personnel dans Google Cloud pour le fournisseur d'identité de votre organisation, vous pouvez également spécifier ce pool de personnel 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 configurer le fournisseur d'identité de votre organisation 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 un fournisseur d'identité externe, par exemple Okta ou Azure AD, vous devez configurer la 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. Vous trouverez ci-dessous des exemples de mappages d'attributs google.subject et google.groups pour des 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 entité principale est comptabilisée comme un lecteur, et 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é. Les identités ou groupes définis de manière native dans des applications tierces ne sont pas acceptés.
  • 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 data store. Vous ne pouvez pas activer ou désactiver ce paramètre pour un data store existant.
  • L'onglet Données > Documents de la console n'affiche pas les données des sources de données contrôlées par l'accès, car ces données ne doivent être visibles que par les utilisateurs disposant d'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é un pool d'identités de personnel pour 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 de personnel. 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é

Pour spécifier un fournisseur d'identité pour Vertex AI Agent Builder et activer le contrôle des accès sources de données, procédez comme suit:

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

    Agent Builder

  2. Accédez à la page Settings (Paramètres) > Authentication (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 pool de travailleurs 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 data store 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 l'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 d'un data store dans Créer un entrepôt 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: lorsque vous créez un data store, sélectionnez Ce data store contient des informations sur le contrôle des accès.
    • API: lorsque vous créez data store, incluez l'indicateur "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 des informations de LCA à partir du même bucket que vos 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 à 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 l'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 data store dans Créer un entrepôt 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: lorsque vous créez un data store, sélectionnez Ce data store contient des informations sur le contrôle des accès.
    • API: lorsque vous créez data store, incluez l'indicateur "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 des informations de LCA à partir du même bucket que vos 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 data store pour les données non structurées à partir de BigQuery, vous devez définir le data store 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. N'utilisez pas de schéma personnalisé.

    [
  {
    "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. 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: lorsque vous créez un data store, sélectionnez Ce data store contient des informations sur le contrôle des accès.
    • API: lorsque vous créez data store, incluez l'indicateur "aclEnabled": "true" dans votre charge utile JSON.

  4. Lorsque vous suivez la procédure d'importation de données dans Créer un entrepôt de données de recherche, si vous utilisez l'API, définissez BigQuerySource.dataSchema sur document.

Données structurées de BigQuery

Lorsque vous configurez un data store pour les données structurées à partir de BigQuery, vous devez définir le data store comme contrôlé par 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. 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: lorsque vous créez un data store, sélectionnez Ce data store contient des informations sur le contrôle des accès.
    • API: lorsque vous créez data store, incluez l'indicateur "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 des 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'UI de deux manières:

Aperçu des résultats dans la console de la fédération d'identité des employés

Pour afficher les résultats à l'aide de la console Workforce Identity Federation, 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 Preview (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 vous recommande d'attribuer un rôle IAM personnalisé à votre groupe d'utilisateurs.

  • Identité Google: si vous utilisez l'identité Google, Google vous recommande de créer un groupe Google incluant 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, par exemple Okta ou Azure AD, ajoutez tous les membres de votre pool de personnel à un seul groupe.

Google vous recommande de créer un rôle IAM personnalisé à accorder à votre groupe d'utilisateurs, en utilisant les 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 de la documentation IAM.

Autoriser le widget Recherche

Si vous souhaitez déployer un widget de recherche pour une application contrôlée par accès, procédez comme suit:

  1. Accordez le rôle de lecteur du moteur de découverte aux utilisateurs de votre domaine ou de votre pool de collaborateurs qui doivent effectuer des appels d'API de recherche.

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

  3. Suivez la procédure décrite dans la section 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 sur lequel vous et tous les autres utilisateurs disposant d'identifiants de connexion peuvent 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.

    L'application de recherche doit être associée à au moins une source de données avec contrôle des accès. Pour en savoir plus, consultez Configurer une source de données avec contrôle des accès.

  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.