Asigna identidades externas

Por lo general, las empresas administran las identidades (usuarios y grupos de usuarios) con un proveedor de identidad (IdP). Sin embargo, las aplicaciones personalizadas que una empresa haya creado de forma interna pueden permitir que los clientes creen grupos de usuarios nuevos que se definan de forma local dentro de esa aplicación. Estos grupos de usuarios específicos de la aplicación o los IDs de usuario secundarios se denominan identidades externas.

¿Por qué configurar la asignación de identidades?

Para asegurarte de que Google pueda aplicar el control de acceso de forma correcta, asigna tus identidades de IdP a cualquier identidad externa de las aplicaciones personalizadas que planeas usar con Gemini Enterprise.

Para aplicar el control de acceso a los resultados de la app, Google usa el IdP como la fuente de verdad para determinar a qué datos tienen acceso tus usuarios. Las empresas suelen conectar su IdP a otras soluciones de SaaS para que un empleado pueda usar un solo conjunto de credenciales corporativas para acceder a todos los recursos de la empresa.

Si tienes identidades externas definidas a través de aplicaciones que planeas conectar a tu app, como aplicaciones personalizadas, tu IDP no es la única fuente de información para el control de acceso.

Por ejemplo, supongamos que "JaneDoe" existe dentro de la organización de ejemplo, con el dominio "example.com". El ID en el IdP se define como "JaneDoe@example.com". El mismo usuario tiene un ID independiente dentro de una aplicación personalizada como "JDoe". Es posible que el IdP no conozca este ID. Por este motivo, Gemini Enterprise no recibe información sobre los IDs de aplicación personalizados a través del IDP.

En Gemini Enterprise, las asignaciones de identidad se almacenan en un almacén de asignaciones de identidad que creas y en el que importas las asignaciones. Si planeas usar un conector personalizado, puedes vincular el almacén de asignación de identidades al almacén de datos del conector personalizado y, luego, actualizar los metadatos de la LCA de tu almacén de datos con información sobre tus identidades externas.

Antes de comenzar

Antes de configurar la asignación de identidades, conecta tu proveedor de identidad a tu proyecto de Google Cloud .

Prepara las entradas de asignación de identidad

Prepara las entradas de asignación de identidad para la importación. Las asignaciones de identidad deben tener el formato que se muestra en el siguiente ejemplo:

{
  "identity_mapping_entries": [
    {
      "external_identity": "u1",
      "user_id": "user1@example.com"
    },
    {
      "external_identity": "u2",
      "user_id": "user2@example.com"
    },
    {
      "external_identity": "gABC",
      "group_id": "groupABC@example.com"
    }
  ]
}

Por ejemplo, en el siguiente gráfico, se representa una membresía de grupo de usuarios de ejemplo, en la que Ext representa grupos externos. En este gráfico, se muestra un ejemplo de relación entre los grupos externos y los usuarios y grupos del IdP.

Relación de identidad externa con los usuarios y grupos del IdP.

Este gráfico de pertenencia de usuarios a grupos tendría la siguiente asignación:

{
  "identity_mapping_entries": [
    {
      "external_identity": "Ext1",
      "user_id": "IDPUser1@example.com"
    },
    {
      "external_identity": "Ext2",
      "user_id": "IDPUser1@example.com"
    },
    {
      "external_identity": "Ext2",
      "user_id": "IDPUser2@example.com"
    },
    {
      "external_identity": "Ext3",
      "user_id": "IDPUser2@example.com"
    },
    {
      "external_identity": "Ext3",
      "group_id": "IDPGroup1@example.com"
    },
    {
      "external_identity": "Ext3",
      "group_id": "IDPGroup2@example.com"
    }
  ]
}

Las membresías de identidad anidadas, en las que las identidades externas tienen identidades secundarias, deben aplanarse.

Google supone que el conector envía un ID principal para una identidad externa. Por ejemplo, importa el ID del grupo en lugar del nombre del grupo, ya que el nombre podría cambiarse durante la vida útil del grupo dentro de la aplicación personalizada.

Configura la asignación de identidad

Usa los siguientes procedimientos para configurar la asignación de identidades en Gemini Enterprise entre tu IDP y tus identidades externas. En los siguientes pasos, crearás un almacén de asignaciones de identidad e importarás las asignaciones de identidad que preparaste. Si planeas usar un conector personalizado, también crearás un almacén de datos nuevo que esté vinculado al almacén de asignación de identidades.

Crea un almacén de asignación de identidades

El primer paso es configurar un almacén de asignación de identidades. Este es el recurso superior en el que se almacenan todas las asignaciones de identidad.

Cuando creas el almacén de asignación de identidades, este recupera automáticamente la configuración del IdP desde el IdP que conectaste a tu proyecto de Gemini Enterprise.

  1. Para crear un almacén de asignación de identidades, ejecuta el siguiente comando con el método identityMappingStores.create:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores?identityMappingStoreId=IDENTITY_MAPPING_STORE_ID" \
    -d '{
      "name": "projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"
    }'
    

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto.
    • IDENTITY_MAPPING_STORE_ID: Es el ID único del almacén de asignación de identidades. Por ejemplo:test-id-mapping-store

Importa asignaciones de identidad

Después de crear el almacén de asignación de identidades, importa las entradas de asignación de identidades que preparaste. Puedes importar asignaciones de identidad con una fuente intercalada (opción 1) o desde Cloud Storage (opción 2).

Cuando importas desde Cloud Storage, se aplican los siguientes formatos y restricciones:

  • Formatos permitidos: Los archivos de entrada deben estar en formato NDJSON (.ndjson) o líneas JSON (.jsonl), y cada línea debe representar una sola entrada de asignación de identidad.
  • Restricciones de tamaño de archivo: Cada archivo no debe superar los 2 GB.
  • Restricciones de la cantidad de asignaciones de identidad: Puedes importar hasta 500,000 asignaciones de identidad externas en una operación de importación.
  • Restricciones de recuento de archivos: Puedes especificar hasta 2,000 archivos en la lista inputUris. Si usas comodines, el límite se aplica a la cantidad total de archivos después de la expansión de comodines.

Opción 1: Importa con la fuente directa

  1. Para importar tus asignaciones de identidad con una fuente intercalada, ejecuta el siguiente comando con el método importIdentityMappings:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" \
    "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/identityMappingStores/IDENTITY_MAPPING_STORE_ID:importIdentityMappings" \
    -d '{"inline_source" : IDENTITY_MAPPINGS_JSON}'
    

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto.
    • ENDPOINT_LOCATION: Es la multirregión para tu solicitud a la API. Especifica uno de los siguientes valores:
      • us para la multirregión de EE.UU.
      • eu para la multirregión de la UE
      • global para la ubicación global
      Para obtener más información, consulta Cómo especificar una multirregión para tu almacén de datos.
    • LOCATION: Es la multirregión de tu almacén de datos: global, us o eu.
    • IDENTITY_MAPPING_STORE_ID: Es el ID único del almacén de asignación de identidades.
    • IDENTITY_MAPPINGS_JSON: Son las asignaciones de identidad preparadas en formato JSON.
  2. Si planeas compilar un conector personalizado y usar identidades externas, ve a Vincula almacenes de datos personalizados al almacén de asignación de identidades. De lo contrario, continúa con Actualiza los metadatos de LCA.

Opción 2: Importa desde Cloud Storage

  1. Para importar tus asignaciones de identidad desde Cloud Storage, ejecuta el siguiente comando con el método importIdentityMappings:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" \
    "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/identityMappingStores/IDENTITY_MAPPING_STORE_ID:importIdentityMappings" \
    -d '{
      "gcsSource": {
        "inputUris": ["gs://BUCKET_NAME/FILE_PATH"]
      },
      "errorConfig": {
        "gcsPrefix": "gs://BUCKET_NAME/ERROR_DIR"
      },
      "reconciliationMode": "FULL"
    }'
    

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto.
    • ENDPOINT_LOCATION: Es la multirregión para tu solicitud a la API. Especifica uno de los siguientes valores:
      • us para la multirregión de EE.UU.
      • eu para la multirregión de la UE
      • global para la ubicación global
      Para obtener más información, consulta Cómo especificar una multirregión para tu almacén de datos.
    • LOCATION: Es la multirregión de tu almacén de datos: global, us o eu.
    • IDENTITY_MAPPING_STORE_ID: Es el ID único del almacén de asignación de identidades.
    • BUCKET_NAME: Es el nombre de tu bucket de Cloud Storage.
    • FILE_PATH: Es la ruta de acceso al archivo de asignaciones de identidad en Cloud Storage.
    • ERROR_DIR: Es el directorio de Cloud Storage en el que se almacenarán los registros de errores.
  2. Si planeas compilar un conector personalizado y usar identidades externas, ve a Vincula almacenes de datos personalizados al almacén de asignación de identidades. De lo contrario, continúa con Actualiza los metadatos de LCA.

Vincula almacenes de datos personalizados al almacén de asignación de identidades

Este procedimiento solo es necesario si compilas un conector personalizado. Si no estás creando un conector personalizado, omite este paso.

En el caso de los conectores personalizados, el almacén de asignación de identidades debe estar vinculado al almacén de datos antes de que se pueda asociar una identidad externa con sus documentos. Este campo solo se puede configurar durante la creación del almacén de datos.

  1. Para vincular un almacén de datos al almacén de asignación de identidades, especifica identity_mapping_store durante la creación del almacén de datos con el método Datastores.create.

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json"  \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID \
    -d '{
        ...
        "identity_mapping_store": "IDENTITY_MAPPING_STORE_NAME"
    }'
    

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto.
    • DATA_STORE_ID: Es el ID del almacén de datos que deseas crear. Este ID solo puede contener letras minúsculas, dígitos, guiones bajos y guiones.
    • IDENTITY_MAPPING_STORE_NAME: Es el nombre completo del recurso del almacén de asignación de identidades. Por ejemplo:projects/exampleproject/locations/global/identityMappingStores/test-id-mapping-store Después de crear un almacén de datos, no se puede actualizar este nombre.

Agrega metadatos de LCA

Incluye metadatos de LCA en el objeto AclInfo de tus documentos.

Cuando un usuario envía una solicitud de búsqueda y se recuperan documentos cuyos metadatos de LCA incluyen identidades externas, se evalúan esas identidades externas. Si la identidad del usuario (groupID o userID) se asigna a una identidad externa (externalEntityId) asociada con un documento, el usuario obtiene acceso a ese documento.

Por ejemplo, supongamos que creaste un conector personalizado para Jira. Ciertos usuarios y grupos del IdP, y un rol de administrador, pueden acceder a un problema de Jira determinado. Para permitir que esas personas accedan a ese problema en los resultados de la búsqueda, puedes crear un almacén de asignación de identidades y asignar usuarios y grupos del IdP a identidades externas específicas de Jira. Vincula el almacén de asignación de identidades a tu almacén de datos de Jira. Luego, crea documentos en tus almacenes de datos de Jira con aclInfo configurado con los usuarios del IdP, los grupos del IdP y las identidades externas que deberían tener acceso a esos documentos.

Para actualizar los metadatos de tu ACL con información sobre tus identidades externas, usa el siguiente formato para especificar las identidades externas y los IDs de usuario y grupo asociados.

{
  "aclInfo": {
    "readers": [
      {
        "principals": [
          {
            "groupId": "group_1"
          },
          {
            "userId": "user_1"
          },
          {
            "externalEntityId": "external_id1"
          }

        ]
      }
    ]
  }
}

Para obtener más información sobre cómo actualizar los metadatos de las LCA, consulta Configura una fuente de datos con control de acceso.

Administra las asignaciones de identidad

Puedes enumerar las asignaciones de identidad en un almacén de identidades o puedes borrar un almacén de identidades definiéndolas a través de una fuente intercalada o usando una condición de filtro.

Las tareas de administración disponibles para la asignación de identidades son las siguientes:

Enumera las asignaciones de identidad

  1. Para enumerar las asignaciones de identidad, ejecuta el siguiente comando con el método listIdentityMappings:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H  "Content-Type: application/json" \
    -H "x-goog-user-project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:listIdentityMappings?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"
    

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto.
    • PAGE_SIZE: Es la cantidad máxima de almacenes de asignación de identidad que se mostrarán. Si no se especifica, el valor predeterminado es 100. El valor máximo permitido es 1,000. Los valores superiores a 1,000 se convertirán en 1,000.
    • PAGE_TOKEN: Es un token de página, recibido desde una llamada a ListIdentityMappingStores anterior. Proporciona esto para recuperar la página siguiente.

Cómo borrar contenido con una fuente intercalada

Puedes borrar entradas específicas de un almacén de asignación de identidades proporcionando un archivo JSON con las identidades que se borrarán.

  1. Para borrar las asignaciones de identidad con la fuente intercalada, ejecuta el siguiente comando con el método purgeIdentityMappings:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "x-goog-user-project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:purgeIdentityMappings" \
    -d '{"inline_source" : IDENTITY_MAPPINGS_JSON}'
    

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto.
    • IDENTITY_MAPPING_STORE_ID: Es el ID único del almacén de asignación de identidades.
    • IDENTITY_MAPPING_STORE_NAME: Es el nombre del almacén de asignación de identidades.
    • IDENTITY_MAPPINGS_JSON: Son las asignaciones de identidad que se borrarán.

Cómo borrar definitivamente con una condición de filtro

Puedes borrar entradas específicas de un almacén de asignación de identidades filtrando las entradas por hora de actualización, identidad externa o todas las entradas.

  1. Para borrar las asignaciones de identidad con una condición de filtro, ejecuta el siguiente comando con el método purgeIdentityMappings:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "x-goog-user-project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:purgeIdentityMappings" \
    -d '{"identity_mapping_store":"IDENTITY_MAPPING_STORE_NAME", "filter": "FILTER_CONDITION"}'
    

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto.
    • IDENTITY_MAPPING_STORE_ID: Es el ID único del almacén de asignación de identidades.
    • IDENTITY_MAPPING_STORE_NAME: Es el nombre del almacén de asignación de identidades.
    • FILTER_CONDITION: Es uno de los siguientes tipos de filtro:
      • Fecha y hora de actualización. Por ejemplo, update_time > "2012-04-23T18:25:43.511Z" AND update_time < "2012-04-23T18:30:43.511Z">
      • Identidad externa. Por ejemplo, external_id = "id1"
      • Todas las asignaciones de identidad. Por ejemplo, *

Administra los almacenes de asignación de identidades

Puedes obtener, borrar, enumerar y limpiar almacenes de asignación de identidad.

Obtén el almacén de asignación de identidades

  1. Para obtener un almacén de asignación de identidades, ejecuta el siguiente comando con el método identityMappingStores.get:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"
    

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto.
    • IDENTITY_MAPPING_STORE_ID: Es el ID único del almacén de asignación de identidades.
    • IDENTITY_MAPPING_STORE_NAME: Es el nombre del almacén de asignación de identidades.

Enumera los almacenes de asignación de identidad

  1. Para enumerar los almacenes de asignación de identidades, ejecuta el siguiente comando con el método identityMappingStores.list:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H  "Content-Type: application/json" \
    -H "x-goog-user-project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"
    

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto.
    • PAGE_SIZE: Es la cantidad máxima de almacenes de asignación de identidad que se mostrarán. Si no se especifica, el valor predeterminado es 100. El valor máximo permitido es 1,000. Los valores superiores a 1,000 se convertirán en 1,000.
    • PAGE_TOKEN: Es un token de página, recibido desde una llamada a ListIdentityMappingStores anterior. Proporciona esto para recuperar la página siguiente.

Borra los almacenes de asignación de identidad

Para borrar un almacén de asignaciones de identidad, este no debe estar vinculado a un almacén de datos, y no puede haber asignaciones de identidad en el almacén de asignaciones de identidad.

  1. Para borrar un almacén de asignación de identidades, ejecuta el siguiente comando con el método identityMappingStores.delete:

    curl -X DELETE \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"
    

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto.
    • IDENTITY_MAPPING_STORE_ID: Es el ID único del almacén de asignación de identidades.
    • IDENTITY_MAPPING_STORE_NAME: Es el nombre del almacén de asignación de identidades.