Usa el control de acceso a la fuente de datos

En esta página, se describe cómo aplicar el control de acceso a la fuente de datos para las apps de búsqueda en Vertex AI Agent Builder.

El control de acceso de tus fuentes de datos en Vertex AI Agent Builder limita los datos que los usuarios pueden ver en los resultados de tu app de búsqueda. Google usa tu proveedor de identidad para identificar al usuario final que realiza una búsqueda y determinar si tiene acceso a los documentos que se muestran como resultados.

Por ejemplo, supongamos que los empleados de tu empresa buscan en documentos de Confluence con tu app de búsqueda. Sin embargo, debes asegurarte de que no puedan ver contenido a través de la app al que no tienen permitido acceder. Si configuraste un grupo de trabajadores en Google Cloud para el proveedor de identidad de tu organización, entonces también puedes especificar ese grupo de trabajadores en Vertex AI Agent Builder. Ahora, si un empleado usa tu app, obtiene resultados de la búsqueda solo para los documentos a los que su cuenta ya tiene acceso en Confluence.

Información acerca del control de acceso a las fuentes de datos

Activar el control de acceso es un procedimiento único.

El control de acceso está disponible para Cloud Storage, BigQuery, Google Drive y todas las fuentes de datos de terceros.

Para activar el control de acceso a la fuente de datos de Vertex AI Agent Builder, debes tener configurado el proveedor de identidad de tu organización en Google Cloud. Se admiten los siguientes marcos de trabajo de autenticación:

  • Identidad de Google: Si usas Identidad de Google, todas las identidades de usuario y los grupos de usuarios están presentes y se administran a través de Google Cloud. Para obtener más información sobre Google Identity, consulta la documentación de Google Identity.

  • Federación de proveedores de identidad externos: Si usas un proveedor de identidad external, por ejemplo, Okta o Azure AD, debes configurar la federación de identidades de personal en Google Cloud antes de poder activar el control de acceso a la fuente de datos para Vertex AI Agent Builder.

    Si usas conectores de terceros, el atributo google.subject se debe asignar al campo de dirección de correo electrónico en el proveedor de identidad externo. Los siguientes son ejemplos de asignaciones de atributos google.subject y google.groups para proveedores de identidad de uso general:

Limitaciones

El control de acceso tiene las siguientes limitaciones:

  • Se permiten 250 lectores por documento. Cada principal cuenta como lector, en el que un principal puede ser un grupo o un usuario individual.
  • Puedes seleccionar un proveedor de identidad por ubicación compatible con Vertex AI Search.
  • El control de acceso se respeta solo para las identidades y los grupos que se definen de forma explícita en tu proveedor de identidad. No se admiten identidades ni grupos que se definan de forma nativa en apps de terceros.
  • Para establecer una fuente de datos como controlada por acceso, debes seleccionar este parámetro de configuración durante la creación del almacén de datos. No puedes activar o desactivar este parámetro de configuración para un almacén de datos existente.
  • La pestaña Datos > Documentos de la consola no muestra datos de las fuentes de datos con acceso controlado, ya que estos datos solo deben ser visibles para los usuarios que tienen acceso de lectura.
  • Para obtener una vista previa de los resultados de la IU de las apps de búsqueda que usan el control de acceso de terceros, debes acceder a la consola federada o usar la app web. Consulta Obtén una vista previa de los resultados de las apps con control de acceso.

Antes de comenzar

En este procedimiento, se supone que configuraste un proveedor de identidad en tu proyecto de Google Cloud.

  • Google Identity: Si usas Google Identity, puedes continuar con el procedimiento para conectarte a tu proveedor de identidad.
  • Proveedor de identidad de terceros: Asegúrate de haber configurado un grupo de identidad del personal para tu proveedor de identidad de terceros. Asegúrate de haber especificado las asignaciones de atributos de sujeto y grupo cuando configures el grupo de trabajadores. Para obtener información sobre las asignaciones de atributos, consulta Asignaciones de atributos en la documentación de IAM. Para obtener más información sobre los grupos de identidades de personal, consulta Administra los proveedores de grupos de identidades de personal en la documentación de IAM.

Cómo conectarte a tu proveedor de identidad

Para especificar un proveedor de identidad para Vertex AI Agent Builder y activar el control de acceso a la fuente de datos, sigue estos pasos:

  1. En la consola de Google Cloud, ve a la página Agent Builder.

    Agent Builder

  2. Ve a la página Settings > Authentication.

  3. Haz clic en Agregar proveedor de identidad para la ubicación que deseas actualizar.

  4. Selecciona tu proveedor de identidad en el cuadro de diálogo Agregar proveedor de identidad. Si seleccionas un proveedor de identidad de terceros, también selecciona el grupo de personal que se aplica a tus fuentes de datos.

  5. Haz clic en Guardar cambios.

Configura una fuente de datos con control de acceso

Para aplicar el control de acceso a una fuente de datos, sigue los pasos que se indican a continuación según el tipo de fuente de datos que configures:

Datos no estructurados de Cloud Storage

Cuando configures un almacén de datos para datos no estructurados desde Cloud Storage, también deberás subir metadatos de LCA y configurar el almacén de datos como controlado por acceso:

  1. Cuando prepares tus datos, incluye la información de la ACL en los metadatos con el campo acl_info. Por ejemplo:

    {
   "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" }
         ]
       }
     ]
   }
 }

    Para obtener más información sobre los datos no estructurados con metadatos, consulta la sección Datos no estructurados de Prepara los datos para la transferencia.

  2. Cuando sigas los pasos para crear un almacén de datos en Crea un almacén de datos de búsqueda, puedes habilitar el control de acceso haciendo lo siguiente en la consola o con la API:

    • Consola: Cuando crees un almacén de datos, selecciona Este almacén de datos contiene información del control de acceso durante el proceso de creación.
    • API: Cuando crees el almacén de datos, incluye la marca "aclEnabled": "true" en la carga útil de JSON.

  3. Cuando sigas los pasos para la importación de datos en Cómo crear un almacén de datos de búsqueda, asegúrate de hacer lo siguiente:

    • Sube tus metadatos con la información de la LCA desde el mismo bucket que tus datos no estructurados
    • Si usas la API, establece GcsSource.dataSchema en document.

Datos estructurados de Cloud Storage

Cuando configures un almacén de datos para datos estructurados desde Cloud Storage, también deberás subir metadatos de LCA y establecer el almacén de datos como controlado por acceso:

  1. Cuando prepares tus datos, incluye la información de la ACL en los metadatos con el campo acl_info. Por ejemplo:

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

  2. Cuando sigas los pasos para crear un almacén de datos en Crea un almacén de datos de búsqueda, puedes habilitar el control de acceso haciendo lo siguiente en la consola o con la API:

    • Consola: Cuando crees un almacén de datos, selecciona Este almacén de datos contiene información del control de acceso durante el proceso de creación.
    • API: Cuando crees el almacén de datos, incluye la marca "aclEnabled": "true" en la carga útil de JSON.

  3. Cuando sigas los pasos para la importación de datos en Cómo crear un almacén de datos de búsqueda, asegúrate de hacer lo siguiente:

    • Sube tus metadatos con la información de la LCA desde el mismo bucket que tus datos no estructurados
    • Si usas la API, establece GcsSource.dataSchema en document.

Datos no estructurados de BigQuery

Cuando configures un almacén de datos para datos no estructurados de BigQuery, debes establecer el almacén de datos como controlado por acceso y proporcionar metadatos de ACL con un esquema predefinido para Vertex AI Search:

  1. Cuando prepares tus datos, especifica el siguiente esquema. No uses un esquema personalizado.

    [
  {
    "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. Incluye los metadatos de la ACL como una columna en tu tabla de BigQuery.

  3. Cuando sigas los pasos que se indican en Cómo crear un almacén de datos de búsqueda, habilita el control de acceso en la consola o con la API:

    • Consola: Cuando crees un almacén de datos, selecciona Este almacén de datos contiene información del control de acceso durante el proceso de creación.
    • API: Cuando crees el almacén de datos, incluye la marca "aclEnabled": "true" en la carga útil de JSON.

  4. Cuando sigas los pasos para la importación de datos en Crea un almacén de datos de búsqueda, si usas la API, establece BigQuerySource.dataSchema en document.

Datos estructurados de BigQuery

Cuando configures un almacén de datos para datos estructurados de BigQuery, debes configurarlo como controlado por acceso y proporcionar metadatos de ACL con un esquema predefinido para Vertex AI Search:

  1. Cuando prepares tus datos, especifica el siguiente esquema. No uses un esquema personalizado.

    [
  {
    "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. Incluye los metadatos de la ACL como una columna en tu tabla de BigQuery.

  3. Cuando sigas los pasos que se indican en Cómo crear un almacén de datos de búsqueda, habilita el control de acceso en la consola o con la API:

    • Consola: Cuando crees un almacén de datos, selecciona Este almacén de datos contiene información del control de acceso durante el proceso de creación.
    • API: Cuando crees el almacén de datos, incluye la marca "aclEnabled": "true" en la carga útil de JSON.

  4. Cuando sigas los pasos para la importación de datos en Cómo crear un almacén de datos de búsqueda, asegúrate de hacer lo siguiente:

    • Si usas la consola, cuando especifiques el tipo de datos que subirás, selecciona JSONL para datos estructurados con metadatos.
    • Si usas la API, establece BigQuerySource.dataSchema en document.

Cómo obtener una vista previa de los resultados de las apps con control de acceso de terceros

Para obtener una vista previa de los resultados en la consola de las apps con control de acceso de terceros, debes acceder con las credenciales de tu organización.

Puedes obtener una vista previa de los resultados de la IU de dos maneras:

Cómo obtener una vista previa de los resultados en la consola de la federación de identidades del personal

Sigue estos pasos para usar la consola de la federación de identidades de personal y ver los resultados:

  1. En la consola de Google Cloud, ve a la página Agent Builder.

    Agent Builder

  2. Haz clic en el nombre de la app de búsqueda cuyos resultados deseas obtener una vista previa.

  3. Ve a la página Vista previa.

  4. Haz clic en Vista previa con identidad federada para ir a la consola de la federación de identidades de personal.

  5. Ingresa el proveedor del grupo de trabajadores y las credenciales de la organización.

  6. Obtén una vista previa de los resultados de tu app en la página Vista previa que aparece.

    Para obtener más información sobre cómo obtener una vista previa de los resultados de la búsqueda, consulta Cómo obtener resultados de la búsqueda.

Para obtener más información sobre la consola de la federación de identidades de personal, consulta Acerca de la consola (federada).

Otorga permisos de búsqueda a tus usuarios

Para permitir que los usuarios busquen datos controlados por acceso con tu app, debes otorgarles acceso a los usuarios de tu dominio o grupo de personal. Google recomienda que otorgues un rol de IAM personalizado a tu grupo de usuarios.

  • Identidad de Google: Si usas Identidad de Google, Google recomienda que crees un Grupo de Google que incluya a todos los empleados que necesiten realizar búsquedas. Si eres administrador de Google Workspace, puedes incluir a todos los usuarios de una organización en un Grupo de Google. Para ello, sigue los pasos que se indican en Cómo agregar a un grupo a todos los usuarios de tu organización.
  • Proveedor de identidad de terceros: Si usas un proveedor de identidad externo, por ejemplo, Okta o Azure AD, agrega a todos los usuarios de tu grupo de personal a un solo grupo.

Google recomienda que crees un rol de IAM personalizado para otorgar a tu grupo de usuarios con los siguientes permisos:

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

Para obtener más información sobre los permisos de los recursos de Vertex AI Agent Builder con Identity and Access Management (IAM), consulta Control de acceso con IAM.

Para obtener más información sobre las funciones personalizadas, consulta Funciones personalizadas en la documentación de IAM.

Autoriza el widget de búsqueda

Si quieres implementar un widget de búsqueda para una app con control de acceso, sigue estos pasos:

  1. Otorga el rol de Visualizador de Discovery Engine a los usuarios de tu dominio o grupo de trabajo que necesiten realizar llamadas a la API de búsqueda.

  2. Genera tokens de autorización para pasarlos a tu widget:

  3. Sigue los pasos que se indican en Cómo agregar un widget con un token de autorización para pasar el token a tu widget.

Activa la app web

La app web es un sitio exclusivo que genera Vertex AI Search en el que tú y cualquier otro usuario con credenciales de acceso pueden usar tu app de búsqueda.

Para proporcionar la app de búsqueda a los usuarios sin necesidad de integrar el widget de búsqueda o la API de búsqueda en tu propia aplicación, puedes proporcionar la URL de la app web a tus usuarios.

Sigue estos pasos para activar la app web:

  1. En la consola de Google Cloud, ve a la página Agent Builder.

    Agent Builder

  2. Haz clic en el nombre de la app de búsqueda para la que deseas crear una app web.

    La app de búsqueda debe estar asociada con, al menos, una fuente de datos con control de acceso. Para obtener más información, consulta Configura una fuente de datos con control de acceso.

  3. Ve a la pestaña Integration > UI.

  4. Haz clic en Habilitar la app web.

  5. Si usas la federación de Workforce Identity, selecciona un proveedor de grupos de personal.

  6. Haz clic en el vínculo a tu app web.

  7. Ingresa el proveedor del grupo de trabajadores y las credenciales de la organización.

  8. Obtén una vista previa de los resultados de tu app.

  9. Para configurar los resultados de la app web, consulta Cómo configurar los resultados para el widget de búsqueda. Cualquier configuración del widget también se aplica a la app web.

  10. Opcional: Para proporcionar la app de búsqueda a tus usuarios a través de esta app web dedicada, copia la URL y envíala a los usuarios que tengan credenciales de acceso. Pueden agregar a favoritos la URL de la app web y acceder a ella para usar tu app de búsqueda.

Para obtener más información sobre cómo obtener resultados de la búsqueda, consulta Cómo obtener resultados de la búsqueda.