Usa el control de acceso a la fuente de datos

En esta página, se describe cómo aplicar el control de acceso a las fuentes de datos para las apps de búsqueda en AI Applications.

El control de acceso a tus fuentes de datos en las aplicaciones basadas en IA limita los datos que los usuarios pueden ver en los resultados de la 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, también puedes especificar ese grupo de trabajadores en AI Applications. Ahora, si un empleado usa tu app, solo obtendrá resultados de búsqueda para los documentos a los que su cuenta ya tiene acceso en Confluence.

Acerca del control de acceso a la fuente de datos

Activar el control de acceso es un procedimiento que se realiza una sola vez.

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 para AI Applications, debes tener configurado el proveedor de identidad de tu organización en Google Cloud. Se admiten los siguientes frameworks de autenticación:

  • Google Identity:

    • Caso 1: Si usas Google Identity, 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.

    • Caso 2: Usas un proveedor de identidad externo y sincronizaste las identidades con Google Identity. Tus usuarios finales usan la identidad de Google para autenticarse antes de acceder a los recursos de Google o Google Workspace.

    • Caso 3: Usas un proveedor de identidad externo y sincronizaste las identidades con la Identidad de Google. Sin embargo, sigues usando tu proveedor de identidad externo existente para realizar la autenticación. Configuraste el SSO con Google Identity de modo que tus usuarios comiencen su acceso con Google Identity y, luego, se los dirija a tu proveedor de identidad externo. (Es posible que ya hayas realizado esta sincronización cuando configuraste otros recursos Google Cloud o Google Workspace).

  • Federación de proveedores de identidad externos: Si usas un proveedor de identidad externo, por ejemplo, Azure AD, Okta o Ping, pero no quieres sincronizar tus identidades en Cloud Identity de Google Cloud, debes configurar la federación de identidades de personal en Google Cloudantes de poder activar el control de acceso a la fuente de datos para las aplicaciones basadas en IA.

    Si usas conectores de terceros, el atributo google.subject debe asignarse al campo de dirección de correo electrónico en el proveedor de identidad externo. A continuación, se muestran ejemplos de asignaciones de atributos google.subject y google.groups para proveedores de identidad de uso común:

Limitaciones

El control de acceso tiene las siguientes limitaciones:

  • Se permiten 3,000 lectores por documento. Cada principal se cuenta como lector, y un principal puede ser un grupo o un usuario individual.
  • Puedes seleccionar un proveedor de identidad por ubicación compatible con Vertex AI Search.
  • 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 ni desactivar este parámetro de configuración para un almacén de datos existente.
  • En la pestaña Datos > Documentos de la consola, no se muestran datos de las fuentes de datos con acceso controlado, ya que estos datos solo deben ser visibles para los usuarios que tienen acceso de visualización.
  • 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 Cómo obtener 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 deGoogle 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 identidades de personal para tu proveedor de identidad de terceros. Verifica que hayas especificado asignaciones de atributos de grupo y asunto cuando configures el grupo de personal. 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 identidad de personal, consulta Administra proveedores de grupos de identidad de personal en la documentación de IAM.

Conéctate a tu proveedor de identidad

Para especificar un proveedor de identidad para las aplicaciones basadas en IA 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 AI Applications.

    Aplicaciones basadas en IA

  2. Ve a la página Configuración > Autenticación.

  3. Haz clic en el ícono de edición de la ubicación que deseas actualizar.

  4. Selecciona tu proveedor de identidad en el diálogo Agregar proveedor de identidad. Si seleccionas un proveedor de identidad externo, también debes seleccionar 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 configures un almacén de datos para datos no estructurados de 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 tus 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 siguiendo estos pasos 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 la creación del almacén de datos.
    • API: Cuando crees el almacén de datos, incluye la marca "aclEnabled": "true" en tu carga útil de JSON.

  3. Cuando sigas los pasos para importar datos en Crea un almacén de datos de búsqueda, asegúrate de hacer lo siguiente:

    • Sube tus metadatos con información de 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 de 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 tus 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 siguiendo estos pasos 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 la creación del almacén de datos.
    • API: Cuando crees el almacén de datos, incluye la marca "aclEnabled": "true" en tu carga útil de JSON.

  3. Cuando sigas los pasos para importar datos en Crea un almacén de datos de búsqueda, asegúrate de hacer lo siguiente:

    • Sube tus metadatos con información de 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, deberás 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 tu tabla de BigQuery.

  3. Cuando sigas los pasos en Crea 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 la creación del almacén de datos.
    • API: Cuando crees el almacén de datos, incluye la marca "aclEnabled": "true" en tu carga útil de JSON.

  4. Cuando sigas los pasos para importar 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, deberás establecer el almacén de datos como controlado por acceso y proporcionar metadatos de LCA 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 LCA como una columna en tu tabla de BigQuery.

  3. Cuando sigas los pasos en Crea 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 la creación del almacén de datos.
    • API: Cuando crees el almacén de datos, incluye la marca "aclEnabled": "true" en tu carga útil de JSON.

  4. Cuando sigas los pasos para importar datos en Crea 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.

Vista previa de los resultados para 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 Workforce Identity Federation

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 AI Applications.

    Aplicaciones basadas en IA

  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 Preview.

  4. Haz clic en Vista previa con identidad federada para ir a la consola de Workforce Identity Federation.

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

  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 federación de identidades de personal, consulta Acerca de la consola (federada).

Cómo otorgar permisos de búsqueda a tus usuarios

Para que los usuarios puedan buscar datos con control de acceso a través de tu app, debes otorgarles acceso en 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 la 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 siguiendo los pasos que se indican en Cómo agregar a todos los usuarios de tu organización a un grupo.
  • Proveedor de identidad externo: Si usas un proveedor de identidad externo, por ejemplo, Okta o Azure AD, agrega a todos los miembros 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
  • discoveryengine.widgetConfigs.get

Para obtener más información sobre los permisos de los recursos de AI Applications 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 Search.

  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 exclusivo generado por 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 o la API de búsqueda en tu propia aplicación, puedes proporcionarles la URL de la app web.

Sigue estos pasos para activar la app web:

  1. En la consola de Google Cloud , ve a la página AI Applications.

    Aplicaciones basadas en IA

  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 Integración > IU.

  4. Haz clic en Habilitar la app web.

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

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

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

  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 marcar 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.