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 creó internamente 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 o IDs de usuario secundarios específicos de la aplicación se denominan identidades externas.
¿Por qué configurar la asignación de identidades?
Para asegurarte de que Google pueda aplicar el control de acceso correctamente, asigna las identidades de tu IDP a las identidades externas 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 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 verdad 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 al 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 ACL 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 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 siguiente formato:
{
"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, el siguiente gráfico 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 la relación entre los grupos externos y los usuarios y grupos del IdP.
Este grafo de membresía de grupos de usuarios 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, ya que el nombre podría cambiar durante la vida útil del grupo en la aplicación personalizada.
Configura la asignación de identidad
Sigue los procedimientos que se indican a continuación 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 identidades y, luego, importarás las asignaciones de identidades 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 principal en el que se almacenan todas las asignaciones de identidad.
Cuando creas el almacén de asignación de identidades, se recupera automáticamente la configuración del IDP que conectaste a tu proyecto de Gemini Enterprise.
Para crear un almacén de asignaciones 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 asignaciones de identidades. Por ejemplo:test-id-mapping-store
Importa asignaciones de identidad
Después de crear el almacén de asignaciones de identidad, importa las entradas de asignaciones de identidad que preparaste.
Para importar tus asignaciones de identidad, 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://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:importIdentityMappings" \ -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 asignaciones de identidades.IDENTITY_MAPPINGS_JSON: Son las asignaciones de identidad preparadas en formato JSON.
A continuación, si planeas compilar un conector personalizado y usar identidades externas, consulta Cómo vincular almacenes de datos personalizados al almacén de asignación de identidades. De lo contrario, ve a Actualiza los metadatos de la 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. Solo se permite configurar este campo durante la creación del almacén de datos.
Para vincular un almacén de datos al almacén de asignación de identidades, especifica
identity_mapping_storedurante la creación del almacén de datos con el métodoDatastores.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 en minúscula, dígitos, guiones bajos y guiones.IDENTITY_MAPPING_STORE_NAME: Es el nombre completo del recurso del almacén de asignaciones de identidad. Por ejemplo:projects/exampleproject/locations/global/identityMappingStores/test-id-mapping-storeDespué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 a un documento, el usuario obtiene acceso a ese documento.
Por ejemplo, supongamos que creaste un conector personalizado para Jira. Se puede acceder a un problema de Jira determinado a través de ciertos usuarios y grupos del IDP, y un rol de administrador. Para permitir que esas personas accedan al 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 LCA 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 la 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 purgar 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
- Purgar con fuente intercalada
- Cómo purgar con una condición de filtro
Enumera las asignaciones de identidad
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 identidades que se devolverá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 a 1,000.PAGE_TOKEN: Es un token de página, recibido de una llamadaListIdentityMappingStoresanterior. Proporciona esto para recuperar la página siguiente.
Purgar con fuente intercalada
Puedes purgar las entradas especificadas de un almacén de asignación de identidades proporcionando un archivo JSON de las identidades que se purgarán.
Para purgar las asignaciones de identidad con una 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 asignaciones de identidades.IDENTITY_MAPPING_STORE_NAME: Es el nombre del almacén de asignación de identidades.IDENTITY_MAPPINGS_JSON: Es la asignación de identidades que se borrará.
Borra definitivamente con una condición de filtro
Puedes purgar las entradas especificadas de un almacén de asignación de identidades filtrando las entradas por hora de actualización, identidad externa o todas las entradas.
Para purgar 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 asignaciones de identidades.IDENTITY_MAPPING_STORE_NAME: Es el nombre del almacén de asignación de identidades.FILTER_CONDITION: Uno de los siguientes tipos de filtro:- Fecha de actualización. Por ejemplo,
update_time > "2012-04-23T18:25:43.511Z" AND update_time < "2012-04-23T18:30:43.511Z"> - Es la identidad externa. Por ejemplo,
external_id = "id1" - Son todas las asignaciones de identidad. Por ejemplo,
*
Administra almacenes de asignación de identidades
Puedes obtener, borrar, enumerar y purgar almacenes de asignación de identidades.
Obtén el almacén de asignación de identidad
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 asignaciones de identidades.IDENTITY_MAPPING_STORE_NAME: Es el nombre del almacén de asignación de identidades.
Enumera los almacenamientos de asignación de identidad
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 identidades que se devolverá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 a 1,000.PAGE_TOKEN: Es un token de página, recibido de una llamadaListIdentityMappingStoresanterior. 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, no debe estar vinculado a un almacén de datos y no debe haber asignaciones de identidad en el almacén de asignaciones de identidad.
Para borrar un almacén de asignaciones 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 asignaciones de identidades.IDENTITY_MAPPING_STORE_NAME: Es el nombre del almacén de asignación de identidades.