Incrustación#

La incrustación muestra documentos publicados y plantillas del portal de Empowerment Center dentro de otra aplicación, como una intranet, un ERP o un portal de clientes, sin que el usuario tenga que volver a iniciar sesión. La aplicación que enmarca el contenido se llama aplicación anfitriona, y esta página explica cómo darla de alta y administrarla.

Antes de empezar#

Hace falta Administración del Sistema para administrar las aplicaciones anfitrionas.
Lo que se incrusta tiene que estar publicado en el portal: un documento publicado o una plantilla con sus páginas (véase el portal en el manual de usuario).
Cada lector tiene que ser un usuario de ECenter. No hay invitados anónimos.
La incrustación viene activada (ecenter.embedding.enabled: true). Con false no se emiten tokens y /embed/{clave} no se puede enmarcar.

Cómo funciona#

El principio es: el token nombra, el servidor decide y el token solo quita.

El servidor de la aplicación anfitriona, con su credencial de ámbito Incrustación, pide a ECenter un token para el usuario que ha entrado en ella. El token vive 5 minutos y sirve una sola vez.
La página anfitriona tiene un iframe con la dirección /embed/{clave} de ECenter. ECenter solo deja que la enmarquen los orígenes dados de alta en la aplicación (Content-Security-Policy: frame-ancestors).
La página da el token al iframe, que lo canjea por una sesión incrustada.
El iframe enseña el contenido con la identidad del usuario nombrado: sus universos y su seguridad por columnas, igual que en su sesión.

El token puede añadir restricciones (una segmentación, impedir la exportación…), pero nunca dar más de lo que el usuario puede ver. Cómo se programa la página y el servidor anfitrión se explica en Integrar la aplicación anfitriona.

Cómo se abre un documento incrustado Ver a tamaño completo Ver a tamaño completo

Quién puede ser lector#

ECenter solo emite un token para un usuario que cumple todo esto:

Está habilitado.
Tiene alguno de los roles de los lectores de la aplicación.
Tiene Acceso al Portal (o Administración del portal).
No tiene Administración del sistema. No se emiten tokens para quien administra el sistema.
Puede leer ahora el contenido pedido: el libro y, en una plantilla, el privilegio de cada página.

Los lectores son usuarios de ECenter y cuentan en el máximo de usuarios de la licencia.

Dar de alta una aplicación anfitriona#

Vaya a Administración › Incrustación.
Pulse Nueva aplicación anfitriona….
Rellene el diálogo y pulse Crear aplicación.

Opción	Qué es
Nombre	La intranet, el ERP o el portal que incrusta: «Intranet comercial». Hasta 100 caracteres.
Clave	Va en la dirección del iframe: `/embed/<clave>`. De 3 a 40 minúsculas, dígitos o guiones, sin guion al principio ni al final. `sdk` y `print` están reservadas. Se propone a partir del nombre.
Primer origen	La página que enmarca el contenido: `https://host[:puerto]`, sin ruta.
Rol de los lectores	Solo se emiten tokens para usuarios con un rol permitido. Se pueden añadir más en la pestaña Usuarios.

La aplicación se abre después en su página, con seis pestañas: General, Contenido, Usuarios, Credenciales, Sesiones y Probar. Los cambios de las tres primeras se guardan con Guardar cambios; si sale de la página con cambios sin guardar, ECenter lo pregunta.

La lista de aplicaciones anfitrionas en Administración › Incrustación con su estado

La lista de Administración › Incrustación enseña de cada aplicación su Nombre (con su dirección /embed/<clave>), Orígenes, Contenido, Credenciales, Sesiones activas y Estado: Habilitada, Deshabilitada o Sin credencial activa.

General#

Opción	Qué hace
Nombre	El nombre de la aplicación.
Clave	La clave de la dirección. Copiar la dirección copia la dirección completa del iframe. Cambiar la clave cambia la dirección que usa la anfitriona.
Descripción	Opcional, hasta 500 caracteres.
Habilitada: emite tokens y enseña su contenido	Deshabilitada, no se emiten tokens y su página no enseña nada.
Orígenes	De 1 a 10 orígenes que pueden enmarcar el contenido (abajo).
Duración máxima de una sesión (minutos)	Lo más que dura una sesión incrustada; al llegar, el iframe pide otro token. 0 es la de la instalación (8 horas por defecto).
Sus tokens pueden permitir exportar	Sin marcar, ningún token de la aplicación puede permitir exportar.
Sus tokens pueden dejar elegir una versión anterior	Sin marcar, solo se ve la versión publicada más reciente.
Solo documentos dinámicos	Solo se incrustan documentos dinámicos. Los congelados llevan los datos de quien publicó: todos los lectores ven las mismas cifras.

Orígenes#

Un origen es el esquema, el host y el puerto de la página anfitriona: https://intranet.example.com o https://erp.example.com:8443. Escríbalo en Añadir un origen y pulse Añadir.

Solo https://host[:puerto], sin ruta, consulta ni fragmento. La barra final se quita.
Sin comodines: un origen por página anfitriona.
Sin usuario ni contraseña en la dirección.
http solo para localhost y solo si la instalación lo permite (ecenter.embedding.allow-insecure-localhost, para desarrollo).

Con estos orígenes, ECenter calcula en cada petición la cabecera Content-Security-Policy: frame-ancestors de /embed/<clave>, que los navegadores aplican a todas las páginas que enmarcan. Una clave que no existe o una aplicación deshabilitada da frame-ancestors 'none'. El resto de ECenter no se puede enmarcar en ningún sitio.

Importante

Si un proxy de su organización añade X-Frame-Options o su propia Content-Security-Policy a todas las respuestas, el iframe no se verá. Lo que viene del backend, y en particular /embed/, tiene que pasar sin cabeceras añadidas. La imagen del frontal de ECenter ya lo hace así (véase la instalación).

Contenido#

La pestaña Contenido es un árbol con lo que se puede incrustar, solo lo publicado:

Libros publicados, con sus documentos. Cada documento dice si es Dinámico: cada lector ve sus datos o Congelado: todos los lectores ven los datos de quien publicó.
Plantillas del portal, con sus páginas. Marcar la plantilla permite todas sus páginas; marcar solo algunas páginas, solo esas. Se avisa de las páginas ocultas en las pestañas y de las que tienen privilegio de lectura.

Cada token pide una parte de esto, y el lector solo ve lo que puede leer en ese momento. Si algo permitido deja de estar publicado, una franja lo avisa y Quitarlos lo quita del contenido.

La pestaña Contenido con el árbol de libros publicados y plantillas del portal

Usuarios#

En Roles de los lectores se eligen uno o varios roles: los tokens solo nombran a usuarios habilitados con uno de ellos y Acceso al portal. Al menos un rol es obligatorio. Un rol que incluye Administración del sistema se marca, porque sus usuarios no pueden ser lectores.

Credenciales#

El servidor de la aplicación pide los tokens con una credencial de ámbito Incrustación ligada a la aplicación. Su titular es quien la crea y necesita Administración del sistema: si la pierde, la credencial deja de valer.

En la pestaña Credenciales, pulse Crear credencial….
En Caduca, elija Al año (por defecto), A los 90 días o A los 30 días.
Pulse Crear credencial.
Copie el secreto con Copiar y póngalo en el servidor de la aplicación, en la cabecera Authorization: Bearer. Es la única vez que se muestra.
Pulse Hecho.

La tabla muestra de cada credencial su Titular, la Pista del secreto, el Estado, cuándo Caduca y su Último uso. Revocar… la revoca: el servidor ya no podrá pedir tokens con ella y se cierran sus sesiones abiertas.

Atención

El secreto de la credencial de incrustación permite pedir un token para cualquier usuario lector de la aplicación. Guárdelo solo en el servidor de la aplicación anfitriona, nunca en la página ni en el navegador.

Sin una credencial activa, la aplicación aparece como Sin credencial activa y su servidor no puede pedir tokens. Para rotarla sin cortar el servicio, cree la nueva, cámbiela en el servidor y revoque la anterior. La consola de operación avisa de las credenciales de incrustación que van a caducar.

Sesiones#

La pestaña Sesiones lista las sesiones incrustadas abiertas: Usuario, Origen, Inicio, Última actividad y Termina como muy tarde. Las de Probar llevan la marca Vista previa.

Cerrar cierra una: el iframe deja de enseñar el contenido y pide otro token a su aplicación.
Cerrar todas… cierra todas las de la aplicación.
Actualizar vuelve a leer la lista.

Una sesión termina sola por inactividad (30 minutos por defecto) o al llegar a su duración máxima, y también si se revoca la credencial, se elimina la aplicación o se inhabilita o borra al usuario.

Probar#

La pestaña Probar enseña el contenido como lo vería un usuario, sin programar nada en la anfitriona. Prueba lo guardado: guarde antes los cambios.

Busque el usuario en Buscar usuario y elíjalo en Usuario.
En Qué se incrusta, elija un documento o una plantilla del contenido permitido. Con una plantilla, elija la Página inicial.
Si quiere, elija una Vista inicial: un marcador público, o uno privado del propio usuario.
Marque o desmarque Con la cabecera (título y versión).
Pulse Probar.

Debajo aparecen Así lo ve el usuario, en un iframe, los Mensajes del iframe que recibiría la anfitriona y, en Para la página anfitriona, un fragmento HTML de ejemplo con Copiar el fragmento.

La pestaña Probar con el contenido incrustado como lo ve comercial.norte y los mensajes del iframe

Si ECenter no emite el token, una franja dice por qué:

Mensaje	Qué hacer
«El usuario no está habilitado.»	Habilítelo o elija otro.
«El usuario no tiene ninguno de los roles de la aplicación (pestaña Usuarios).»	Añada su rol a Roles de los lectores.
«El usuario no tiene Acceso al portal.»	Dele un rol con Acceso al Portal.
«No se emiten tokens para usuarios con Administración del sistema.»	Pruebe con un usuario lector.
«El contenido no está permitido o el usuario no lo puede ver (el libro, la página o su privilegio).»	Revise la pestaña Contenido y los privilegios del libro o de la página.
«El usuario no puede leer ese marcador (un privado de otro) o no es de este contenido.»	Elija otra vista inicial.
«El marcador abre otra versión y la aplicación no deja elegirla (Política).»	Marque Sus tokens pueden dejar elegir una versión anterior o elija otro marcador.
«La aplicación está deshabilitada.»	Habilítela en General.
«Una segmentación no se puede aplicar a un documento congelado.»	Use un documento dinámico.
«La incrustación está desactivada en esta instalación.»	Active `ecenter.embedding.enabled`.

Eliminar una aplicación#

Eliminar…, en la cabecera de la aplicación, revoca sus credenciales y cierra sus sesiones: su página deja de enseñar el contenido. No se puede deshacer.

Configuración#

Propiedad	Por defecto	Qué es
`ecenter.embedding.enabled`	`true`	Activa la incrustación
`ecenter.embedding.token-ttl`	`5m`	Lo que vive un token para canjearlo (como mucho 5 minutos)
`ecenter.embedding.access-token-ttl`	`15m`	Lo que vive el portador de la sesión antes de renovarse
`ecenter.embedding.idle-timeout`	`30m`	Inactividad que termina una sesión
`ecenter.embedding.max-session-duration`	`8h`	Duración máxima de una sesión (techo de la política de cada aplicación; como mucho 24 h)
`ecenter.embedding.allow-insecure-localhost`	`false`	Admitir orígenes `http://localhost` (solo desarrollo)
`ecenter.embedding.issue-rate`	`600/min`	Tokens por aplicación y instancia; por encima, `429 RATE_LIMITED`
`ecenter.embedding.retention`	`30d`	Lo que se conserva una sesión terminada
`ecenter.embedding.index-location` (`ECENTER_EMBEDDING_INDEX_LOCATION`)	`classpath:/static/index.html`	El `index.html` del frontal que se sirve en `/embed/{clave}`

Con varias instancias del backend, el balanceador tiene que mandar las peticiones de un iframe a la misma instancia por la cabecera X-ECenter-Embed-Session (véase la instalación).

Auditoría y operación#

La auditoría anota los cambios en las aplicaciones y sus credenciales, cada token emitido y rechazado (con el usuario, la aplicación, el contenido y las restricciones), cada sesión y cada documento abierto, con el canal EMBED. La consola de operación avisa si se intenta reutilizar un token, que es señal de un ataque: un token ya canjeado cierra la sesión que abrió.