Por lo general, las empresas administran identidades (usuarios y grupos de usuarios) con un proveedor de identidad (IDP). Sin embargo, las aplicaciones personalizadas que una empresa creó 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 conocen como identidades externas.
¿Por qué configurar la asignación de identidad?
Para asegurarte de que Google pueda aplicar el control de acceso correctamente, 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 fuente de información para determinar a qué datos tienen acceso tus usuarios. Las empresas suelen conectar su IDP a otras soluciones 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 aplicaciones personalizadas 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 asignaciones de identidad al almacén de datos del conector personalizado y, luego, actualizar los metadatos de LCA de tu almacén de datos con información sobre tus identidades externas.
Antes de comenzar
Antes de configurar la asignación de identidad, conecta tu proveedor de identidad a tu Google Cloud proyecto.
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 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. Este gráfico muestra una relación de ejemplo entre grupos externos y usuarios y grupos de IDP.
Este gráfico de membresía de grupo 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 estar aplanadas.
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 cambiar 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 identidad en Gemini Enterprise entre tu IDP y tus identidades externas. En los siguientes pasos, crearás un almacén de asignaciones de identidad y, luego, 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 asignaciones de identidad.
Crea un almacén de asignaciones de identidad
El primer paso es configurar un almacén de asignaciones de identidad. Este es el recurso superior en el que se almacenan todas las asignaciones de identidad.
Cuando creas el almacén de asignaciones de identidad, 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 identidad, ejecuta el siguiente comando con el
identityMappingStores.createmétodo: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: el ID único del almacén de asignaciones de identidad. 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 asignación de identidad 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 JSON Lines (.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 cantidad de asignaciones de identidad: Puedes importar hasta
500,000asignaciones de identidad externas en una operación de importación. - Restricciones de cantidad de archivos: Puedes especificar hasta
2,000archivos en la listainputUris. 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 una fuente intercalada
Para importar tus asignaciones de identidad con una fuente intercalada, ejecuta el siguiente comando con el
importIdentityMappingsmétodo: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 región múltiple para tu solicitud a la API. Especifica uno de los siguientes valores:uspara la multirregión de EE.UU.eupara la multirregión de la UEglobalpara la ubicación global
LOCATION: Es la multirregión de tu almacén de datos:global,usoeu.IDENTITY_MAPPING_STORE_ID: el ID único del almacén de asignaciones de identidad.IDENTITY_MAPPINGS_JSON: las asignaciones de identidad preparadas en formato JSON.
Si planeas compilar un conector personalizado y usar identidades externas, ve a Vincula almacenes de datos personalizados al almacén de asignaciones de identidad. De lo contrario, ve a Actualiza los metadatos de LCA.
Opción 2: Importa desde Cloud Storage
Para importar tus asignaciones de identidad desde Cloud Storage, ejecuta el siguiente comando con el
importIdentityMappingsmétodo: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 región múltiple para tu solicitud a la API. Especifica uno de los siguientes valores:uspara la multirregión de EE.UU.eupara la multirregión de la UEglobalpara la ubicación global
LOCATION: Es la multirregión de tu almacén de datos:global,usoeu.IDENTITY_MAPPING_STORE_ID: el ID único del almacén de asignaciones de identidad.BUCKET_NAME: el nombre de tu bucket de Cloud Storage.FILE_PATH: la ruta de acceso a tu archivo de asignaciones de identidad en Cloud Storage.ERROR_DIR: el directorio en Cloud Storage en el que se almacenarán los registros de errores.
Si planeas compilar un conector personalizado y usar identidades externas, ve a Vincula almacenes de datos personalizados al almacén de asignaciones de identidad. De lo contrario, ve a Actualiza los metadatos de LCA.
Vincula almacenes de datos personalizados al almacén de asignaciones de identidad
Este procedimiento solo es necesario si compilas un conector personalizado. Si no compilas un conector personalizado, omite este paso.
En el caso de los conectores personalizados, el almacén de asignaciones de identidad debe estar vinculado al almacén de datos antes de que se pueda asociar una identidad externa con sus documentos. La configuración de este campo solo se permite durante la creación del almacén de datos.
Para vincular un almacén de datos al almacén de asignaciones de identidad, especifica
identity_mapping_storedurante la creación del almacén de datos con elDatastores.createmétodo.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: 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: el nombre completo del recurso del almacén de asignaciones de identidad. 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 AclInfo objeto 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 de IDP, ciertos grupos de IDP y un rol de administrador pueden acceder a un problema de Jira determinado. Para permitir que esas personas puedan acceder a ese problema en los resultados de la búsqueda, puedes crear un almacén de asignaciones de identidad y asignar usuarios y grupos de IDP a identidades externas específicas de Jira. Vincula el almacén de asignaciones de identidad a tu almacén de datos de Jira. Luego, crea documentos en tus almacenes de datos de Jira con aclInfo configurado con los usuarios de IDP, los grupos de IDP y las identidades externas que deberían tener acceso a esos documentos.
Para actualizar tus metadatos de 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 la actualización de metadatos de LCA, consulta Configura una fuente de datos con control de acceso.
Administra asignaciones de identidad
Puedes enumerar las asignaciones de identidad en un almacén de identidad o purgar un almacén de identidad 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 identidad son las siguientes:
- Enumera las asignaciones de identidad
- Purga con una fuente intercalada
- Purga con una condición de filtro
Enumera las asignaciones de identidad
Para enumerar las asignaciones de identidad, ejecuta el siguiente comando con el
listIdentityMappingsmétodo: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: la cantidad máxima de almacenes de asignaciones 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 forzarán a 1,000.PAGE_TOKEN: un token de página, recibido de una llamadaListIdentityMappingStoresanterior. Proporciónalo para recuperar la página siguiente.
Purga con una fuente intercalada
Puedes purgar las entradas especificadas de un almacén de asignaciones de identidad si proporcionas 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
purgeIdentityMappingsmétodo: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: el ID único del almacén de asignaciones de identidad.IDENTITY_MAPPING_STORE_NAME: el nombre del almacén de asignaciones de identidad.IDENTITY_MAPPINGS_JSON: las asignaciones de identidad que se purgarán.
Purga con una condición de filtro
Puedes purgar las entradas especificadas de un almacén de asignaciones de identidad si filtras 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
purgeIdentityMappingsmétodo: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: el ID único del almacén de asignaciones de identidad.IDENTITY_MAPPING_STORE_NAME: el nombre del almacén de asignaciones de identidad.FILTER_CONDITION: uno de los siguientes tipos de filtro:- 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 almacenes de asignaciones de identidad
Puedes obtener, borrar, enumerar y purgar almacenes de asignaciones de identidad.
Obtén el almacén de asignaciones de identidad
Para obtener un almacén de asignaciones de identidad, ejecuta el siguiente comando con el
identityMappingStores.getmétodo: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: el ID único del almacén de asignaciones de identidad.IDENTITY_MAPPING_STORE_NAME: el nombre del almacén de asignaciones de identidad.
Enumera los almacenes de asignaciones de identidad
Para enumerar los almacenes de asignaciones de identidad, ejecuta el siguiente comando con el
identityMappingStores.listmétodo: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: la cantidad máxima de almacenes de asignaciones 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 forzarán a 1,000.PAGE_TOKEN: un token de página, recibido de una llamadaListIdentityMappingStoresanterior. Proporciónalo para recuperar la página siguiente.
Borra almacenes de asignaciones de identidad
Para borrar un almacén de asignaciones de identidad, 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.
Para borrar un almacén de asignaciones de identidad, ejecuta el siguiente comando con el
identityMappingStores.deletemétodo: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: el ID único del almacén de asignaciones de identidad.IDENTITY_MAPPING_STORE_NAME: el nombre del almacén de asignaciones de identidad.