Integrar Cloud embebido sin exponer credenciales

El problema: embeber no es entregar credenciales

Integrar gestor de archivos con iframe y API suele empezar con una necesidad sencilla: mostrar archivos, carpetas, transformaciones o descargas dentro de un producto existente. El error habitual es asumir que, si la interfaz se ve en el navegador, también deben viajar al navegador las claves que permiten operar sobre Cloud. Esa mezcla rompe la separación básica entre experiencia de usuario y autoridad de ejecución. El iframe debe servir para presentar una sesión controlada; la API REST debe usarse desde el servidor cuando haya que gestionar recursos, usuarios, configuración o trabajos de transformación.

Apification ofrece tres modalidades principales para este escenario: API REST, webhooks firmados y Cloud embebido. Cloud embebido se integra mediante una sesión controlada y personalizada, con sesiones iframe firmadas, temas y permisos efectivos, y comunicación JavaScript con el host. Esto no equivale a replicar todo el almacenamiento ni a exponer rutas internas. Tampoco debe confundirse con una sincronización continua de fuentes externas: cuando Google Drive, OneDrive o Dropbox actúan como fuentes, la importación copia archivos seleccionados al Cloud de Apification.

• No pongas claves API en JavaScript del cliente.
• No conviertas un iframe en un proxy sin reglas de negocio.
• No trates el embebido como una copia total del almacenamiento externo.

Mapa de responsabilidades: frontend, backend y Cloud

El frontend debe encargarse de la experiencia: abrir el área embebida, reaccionar a eventos permitidos, mostrar estados y pedir acciones al backend. Un iframe, según la definición general de la plataforma web, es un contexto de navegación anidado que incrusta otra página dentro de la actual. Cada iframe tiene su propio documento y navegación, y consume memoria y recursos adicionales, así que conviene usarlo cuando aporta una experiencia completa y no como mecanismo indiscriminado para cada operación mínima.

El backend debe custodiar credenciales, aplicar reglas propias del producto y llamar a la API REST de Apification de forma servidor a servidor. La integración REST contempla claves API con scopes, operaciones de escritura idempotentes y trabajos asíncronos de File Transformer. Apification Cloud, por su parte, mantiene el espacio de trabajo organizado y versionado, los recursos compartibles, los permisos, los usuarios, grupos, roles y visibilidad que controlan quién puede consultar o modificar cada elemento.

• Frontend: interfaz, iframe, mensajes JavaScript limitados y visualización de estado.
• Backend: autenticación propia, autorización, scopes, idempotencia y llamadas REST.
• Apification Cloud: archivos, servicios, permisos efectivos, versiones y resultados transformados.

Cuándo usar iframe, JavaScript, REST API u OpenAPI

Usa Cloud embebido cuando quieras que el usuario navegue por una experiencia de gestión de archivos dentro de tu producto sin reconstruir toda la interfaz. Apification permite sesiones iframe firmadas con acceso temporal, y el servidor resuelve el tema y los permisos efectivos antes de abrir Cloud. Esto encaja en portales de cliente, paneles de SaaS y backoffices donde el usuario debe ver una parte controlada del workspace, descargar originales o transformados, o trabajar dentro de una experiencia visual coherente con el producto anfitrión.

Usa la API REST cuando la acción tenga consecuencias de negocio o deba ejecutarse con reglas del servidor: crear un trabajo de transformación, gestionar recursos Cloud, aplicar configuración o coordinar usuarios. Usa JavaScript solo para comunicación limitada entre la página host y el iframe, no para ejecutar autoridad sensible. Usa el contrato OpenAPI 3.1 descargable para alinear esquemas de petición y respuesta, generar clientes internos o validar integraciones, recordando que las credenciales con scopes siguen perteneciendo al servidor.

• Iframe: mejor para experiencia completa y controlada de Cloud.
• JavaScript: útil para coordinación de interfaz, no para secretos.
• REST API: adecuada para automatización, reglas de backend y trabajos.
• OpenAPI: útil para contrato técnico, tipos, pruebas y revisión de cambios.

Patrón recomendado: backend como mediador

El patrón operativo más robusto empieza con una petición del usuario a tu aplicación. El backend valida la sesión propia, comprueba qué puede hacer ese usuario según tu modelo de negocio y decide si corresponde abrir Cloud embebido o ejecutar una acción vía API. Si se abre Cloud, el servidor prepara una sesión firmada y temporal, con el tema y los permisos efectivos resueltos antes de entregar la experiencia al navegador. El cliente recibe lo necesario para mostrar el iframe, no una credencial reutilizable.

Para operaciones de escritura o transformación, el backend usa una credencial con scopes y concede solo los permisos de lectura y escritura necesarios. Cuando la acción pueda repetirse por reintentos del navegador o problemas de red, usa operaciones idempotentes para evitar duplicados. En flujos pesados, como importaciones, transformaciones o renders, Apification puede procesar trabajos en segundo plano. La secuencia recomendada queda clara: credencial con scopes, petición idempotente, trabajo asíncrono, evento firmado y resultado autenticado.

• Valida al usuario en tu backend antes de crear una sesión embebida.
• Mapea permisos de negocio a permisos efectivos de Cloud.
• Usa scopes mínimos para la credencial del servidor.
• Diseña las escrituras para tolerar reintentos sin duplicar acciones.

Permisos, temas y restricciones sin ampliar acceso

La seguridad de una integración embebida depende menos del iframe en sí y más de cómo se resuelven los permisos antes de abrirlo. Apification usa usuarios, grupos, roles y visibilidad como controles para decidir quién puede consultar o modificar cada elemento. En una integración, esos controles deben alinearse con tu producto: si un cliente solo puede ver un proyecto, la sesión embebida no debe permitirle navegar a recursos de otro cliente, aunque conozca un identificador o manipule parámetros en la URL.

El tema visual también debe resolverse desde el servidor cuando se prepara la sesión embebida, porque forma parte de la experiencia controlada. En el lado del navegador, considera los atributos estándar de iframe como parte de la defensa de interfaz: allow define una Permissions Policy para funciones disponibles según origen, y sandbox puede imponer restricciones al contenido embebido. La recomendación general es no confiar en el cliente como fuente de permisos, y tener cuidado con combinaciones de sandbox que anulen su valor de seguridad en escenarios mismo origen.

• Comprueba usuario, grupo, rol y visibilidad antes de abrir o ejecutar acciones.
• No aceptes permisos, tema o alcance final solo desde parámetros del cliente.
• Restringe funciones del iframe a lo necesario para la experiencia.
• Revisa que las descargas de originales o transformados pertenezcan al usuario correcto.

Flujos de ejemplo: selector, transformación y descarga

Un flujo de selector embebido puede funcionar así: el usuario entra en tu portal, selecciona un proyecto y pulsa “abrir archivos”. Tu backend valida que ese usuario pertenece al proyecto y solicita una sesión embebida con permisos efectivos adecuados. El frontend inserta el iframe y, mediante comunicación JavaScript limitada con el host, puede recibir una señal de selección o cierre. La acción posterior no debe basarse ciegamente en un ID enviado por el navegador; el backend debe verificar que el elemento seleccionado pertenece al ámbito permitido.

Un flujo de transformación sigue otra lógica. El usuario solicita convertir, dividir, fusionar, optimizar o procesar un documento, imagen, vídeo, audio o dato mediante una acción de tu producto. El backend valida propietario y permiso, llama a la API REST para crear el trabajo asíncrono de File Transformer y registra un estado interno como “en curso”. Cuando el resultado esté disponible, el usuario debe acceder mediante un resultado autenticado, no por rutas internas de almacenamiento. Si el archivo original cambia, el historial de elementos y versiones de Cloud ayuda a conservar una fuente organizada.

• Selector: sesión embebida, selección limitada y validación posterior en backend.
• Transformación: permiso, trabajo asíncrono, estado visible y resultado autenticado.
• Descarga: original o transformado solo para el usuario o grupo autorizado.

Webhooks y acciones asíncronas sin duplicados

Los webhooks de Apification permiten reaccionar a eventos relevantes sin consultar continuamente recursos o trabajos en segundo plano. Incluyen payloads firmados con HMAC, historial de entregas, reintentos y eventos de transformación completada. Para usarlos bien, necesitas un endpoint HTTPS accesible y estable. Ese endpoint no debe limitarse a aceptar cualquier carga: debe validar la firma, registrar el evento recibido y relacionarlo con el trabajo o recurso que tu backend creó previamente.

Como hay reintentos, tu receptor debe ser idempotente. En la práctica, registra una clave de entrega o una referencia del evento y evita que una misma transformación completada dispare dos veces la misma acción de negocio. También conviene separar el estado técnico del estado visible: “recibido”, “procesando”, “completado” o “fallido” en tus registros internos; “tu archivo se está preparando” o “no se pudo completar la transformación” en la interfaz. Así el usuario entiende el progreso sin ver detalles internos ni rutas de almacenamiento.

• Exige HTTPS estable para el endpoint de webhook.
• Valida HMAC antes de confiar en el payload.
• Guarda historial de entregas y resultado de procesamiento.
• Haz que el manejador sea idempotente ante reintentos.

Casos de fallo y checklist antes de producción

Los fallos más peligrosos aparecen cuando el equipo intenta simplificar la integración saltándose el backend. Una clave API en JavaScript puede ser extraída del cliente. Un proxy genérico que reenvía cualquier operación a la API puede ampliar permisos sin querer. Un endpoint que confía en IDs enviados por el navegador cae en problemas de autorización a nivel de objeto: el usuario cambia un identificador y accede a un recurso ajeno. La misma lógica aplica a propiedades: no todo campo que llega del cliente debe ser aceptado como editable.

También hay fallos operativos. Si no registras trabajos en curso, errores de integración o transformaciones fallidas, el usuario solo ve silencio. Si no limitas acciones pesadas, puedes facilitar consumo de recursos no previsto. Si no distingues embebido de importación desde fuentes externas, puedes prometer una sincronización que no corresponde. Antes de producción, revisa que tu backend sea la única pieza con credenciales, que cada acción valide propietario y permiso, y que originales y resultados transformados mantengan una única fuente de verdad en Cloud.

• Credenciales: ninguna clave API en el navegador.
• Autorización: validar objeto, propietario, grupo, rol y visibilidad en backend.
• Scopes: conceder solo lectura y escritura necesarias.
• Proxy: permitir solo operaciones previstas por tu producto.
• Asincronía: registrar trabajos, webhooks, reintentos y errores visibles para soporte.
• Recursos: controlar acciones pesadas y evitar ejecuciones duplicadas.
• Mensajes al usuario: mostrar estados comprensibles sin exponer detalles internos.

Preguntas frecuentes