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 apps de búsqueda en Vertex AI Agent Builder.

El control de acceso para 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 identidad para identificar al usuario final que realiza una búsqueda y determinar si tener acceso a los documentos que se devuelven 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 y, luego, también puedes especificar ese grupo de trabajadores en Vertex AI Agent Builder. Ahora bien, si un empleado usa la aplicación, obtiene resultados de búsqueda solo de los documentos que sus ya tiene acceso a Confluence.

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 frameworks de autenticación:

  • Google Identity: Si usas Google Identity, todas las identidades grupos 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 externo, 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 debe asignarse al campo de dirección de correo electrónico en el un proveedor de identidad externo. Los siguientes son ejemplos google.subject y google.groups asignaciones de atributos para proveedores de identidad de uso común:

Limitaciones

El control de acceso tiene las siguientes limitaciones:

  • Se permiten 250 lectores por documento. Cada principal cuenta como un lector, y una principal puede ser un grupo o un usuario individual.
  • Puedes seleccionar un proveedor de identidad por cada proveedor de identidad compatible con Vertex AI Search ubicación.
  • El control de acceso se respeta solo para las identidades y los grupos que definido en tu proveedor de identidad. Identidades o grupos definidos 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 acceso de terceros debes acceder a la consola federada o usar la app web. Consulta Obtener vista previa de los resultados de las apps con acceso controlado.

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 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. Más información sobre los grupos de identidades de personal, consulta Administra grupos de identidades de personal proveedores en la documentación de IAM.

Conéctate con tu proveedor de identidad

Para especificar un proveedor de identidad para Vertex AI Agent Builder y activar los datos el control de acceso al código fuente, 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 un 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 estos pasos según el tipo de fuente de datos que estás configurando:

Datos no estructurados de Cloud Storage

Cuando configuras un almacén de datos para datos no estructurados de Cloud Storage, debes subir metadatos de la LCA y configurar los datos almacenar con control de acceso:

  1. Cuando prepares tus datos, incluye información de LCA en tus metadatos usando el 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 datos no estructurados con metadatos, consulta la Sección Datos no estructurados de Prepara datos para transferencia de texto.

  2. Cuando sigas los pasos para la creación del almacén de datos en Crea datos de búsqueda de Cloud Storage, puedes habilitar el control de acceso con a través de la consola o de la API:

    • Consola: Cuando crees un almacén de datos, selecciona Este almacén de datos contiene información del control de acceso durante la creación del almacén de datos.
    • 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 los metadatos con información de la LCA desde el mismo bucket que tu datos no estructurados
    • Si usas la API, configura GcsSource.dataSchema como 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 Crear 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 LCA como una columna en la 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 configuras un almacén de datos para datos estructurados de BigQuery, Debes configurar el almacén de datos como con acceso controlado y proporcionar metadatos de LCA. usando 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 LCA como una columna en la tabla de BigQuery.

  3. Si sigues los pasos detallados en Cómo crear datos de búsqueda en Cloud Storage, habilita el control de acceso en la consola 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 un 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, entonces, cuando especifiques el tipo de datos subiendo, selecciona JSONL para datos estructurados con metadatos
    • Si usas la API, configura BigQuerySource.dataSchema como document

Obtén 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:

Obtén una vista previa de los resultados en la consola de Federación de identidades de personal

Sigue estos pasos para usar la consola de 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 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 Obtén 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 miembros grupo único.

Google recomienda crear 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 para los recursos de Vertex AI Agent Builder mediante 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 Visualizador de Discovery Engine a los usuarios de tu dominio o personal que necesitan hacer llamadas a la API de búsqueda.

  2. Genera tokens de autorización para pasar 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 dedicado generado por Vertex AI Search en el que puedes y cualquier otro usuario con credenciales de acceso puede 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 quieres crear una app web.

  3. Ve a Integración > Pestaña IU.

  4. Haz clic en Habilitar la aplicación 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 aplicación 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. Si deseas configurar los resultados para la app web, ve a Configura los resultados de 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 Obtén resultados de la búsqueda.