IllusionCMS
ES
Manual · 15

Cuenta, seguridad y tokens de API

Usuarios

En Ajustes → Usuarios creas más cuentas. Todas las cuentas son administradoras con acceso completo; a propósito, no hay gestión de permisos.

  • Crear cuenta: nombre de usuario y contraseña (al menos 8 caracteres); los datos de acceso se los das a la persona por un canal seguro.
  • Establecer contraseña: para contraseñas olvidadas. La cuenta se cierra en todos los dispositivos.
  • Eliminar: cierra la sesión de la cuenta de inmediato; el contenido se conserva. Tu propia cuenta y la última cuenta no se pueden eliminar.
  • La lista muestra cuándo inició sesión alguien por última vez.

Apariencia e idioma

Abajo del todo en el menú principal, y en la página de inicio de sesión arriba a la derecha:

  • Apariencia (los tres símbolos sol, luna y pantalla): Claro, Oscuro o Sistema (predeterminado: sigue el ajuste claro/oscuro del sistema operativo y cambia con él), Claro u Oscuro. El editor de Workflows, las estadísticas y el mapa del mundo se adaptan. Los editores de código se mantienen oscuros en ambas variantes, como es habitual en los entornos de desarrollo: así el resaltado de sintaxis se lee bien. La vista previa de tu sitio web se ve tal como es el propio sitio web.
  • Idioma de la interfaz (clic en la bandera): Idioma del navegador (predeterminado) o, de forma fija, inglés, alemán, francés, italiano o español. Si el idioma del navegador no es compatible, aparece el inglés.

Ambas cosas se aplican a este navegador (se guardan en el navegador, no en la cuenta): en otro equipo las configuras allí. El idioma de la interfaz no tiene nada que ver con el idioma de los contenidos de tu sitio web.

Inicio de sesión

  • Cambiar contraseña: Ajustes → Mi cuenta.
  • Protección del inicio de sesión: tras 10 intentos fallidos desde la misma dirección IP, los inicios de sesión se bloquean durante 15 minutos.
  • Las sesiones son válidas 14 días.

Tokens de API

Para programas externos (scripts de sincronización, frontends headless, automatizaciones) creas un token en Ajustes → Tokens de API:

  • Solo lectura: puede consultar contenido.
  • Lectura + escritura: puede crear y modificar contenido, pero no gestionar tokens ni contraseñas.

El token se muestra una sola vez. Uso: cabecera Authorization: Bearer <token> y, en consultas GET sencillas, también como parámetro de URL ?token=<token> (aunque entonces acaba en el historial y en los logs del servidor; mejor usa un token de solo lectura). Revocar lo bloquea de inmediato. Todos los endpoints están en la documentación de la API.

Integraciones y cambios atómicos

Los programas que mantienen IllusionCMS a través de la API (p. ej. IllusionPublish, n8n o tus propios scripts) guardan varios cambios en páginas, entradas, bloques globales, snippets y archivos de una sola vez con POST /batch: o todo sale bien o no se cambia nada – aunque alguien haya editado mientras tanto una de las páginas afectadas. Con una clave de idempotencia puedes repetir un batch sin riesgo, sin que nada se cree dos veces. Si un token escribe en nombre de una persona (cabecera X-IC-On-Behalf-Of), el historial de versiones muestra p. ej. Token „Publish“ – im Auftrag von Maria Muster. GET /schema devuelve collections, bloques, idiomas y sitios en una sola respuesta. Los detalles están en la documentación de la API. Estos programas se enteran de los cambios mediante webhooks.

Webhooks

Los webhooks avisan a otros programas en cuanto algo cambia: IllusionCMS envía entonces un POST con una descripción JSON del cambio a una dirección – por ejemplo a n8n, a un servicio que reconstruye un sitio estático, a IllusionPublish o a una entrada HTTP de uno de tus workflows.

Configurar un webhook

En Ajustes → Webhooks haz clic en + Webhook e indica un nombre (opcional), la dirección (http:// o https://), los eventos que quieres y Activo. Deja vacío el campo del secret – IllusionCMS genera uno y lo muestra una sola vez. Cópialo y guárdalo en el receptor. Más adelante, en Editar, puedes generar un Nuevo secret (el anterior deja de funcionar de inmediato) o introducir uno propio (al menos 16 caracteres).

  • El secret solo se guarda cifrado en la base de datos – como el secret de S3. Si trasladas la base de datos a otro servidor, llévate IC_ENCRYPTION_KEY o data/secret.key (ver Guardar medios en S3).
  • Los webhooks pertenecen a la instancia, no al contenido: no forman parte del bundle. En el modo remoto editas los webhooks del servidor.
  • Como máximo 20 webhooks; los inactivos no reciben nada (salvo Enviar prueba).

Eventos de webhook

  • content.changed – se crearon, modificaron, movieron o eliminaron páginas, entradas, bloques globales, archivos, snippets o CSS/JS, también mediante una importación, un bundle, una importación CSV o un batch. Los cambios en unos 2 segundos llegan como una sola entrega – guardar diez entradas no lanza diez builds.
  • schema.changed – se creó, modificó o eliminó una collection, o cambió el esquema de un tipo de bloque. Incluye la schema_version actual de GET /schema.
  • batch.applied – se aplicó un POST /batch, con sus resultados.

Así se ve una entrega:

{ "event": "content.changed", "at": 1791572100,
  "changes": [ { "kind": "page", "action": "updated", "id": 12 },
               { "kind": "item", "action": "created", "id": 31, "collection": "blog" } ] }

Todos los formatos están en la documentación de la API.

Comprobar la firma

Cada entrega lleva la cabecera X-IC-Signature: sha256=… – un HMAC-SHA256 del cuerpo con tu secret. El receptor lo recalcula y descarta todo lo que no coincida; así nadie puede colar eventos falsos. Importante: calcúlalo sobre el cuerpo sin modificar, no sobre JSON regenerado. En Node.js: También enviamos X-IC-Timestamp y X-IC-Signature-V2 (HMAC sobre marca de tiempo.cuerpo); si quieres, rechaza las entregas con una marca de tiempo de más de 5 minutos (protección contra repetición). La respuesta del destinatario no aparece en el registro de entregas, solo el código de estado.

const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
const ok = expected.length === header.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header))

En la documentación de la API hay un ejemplo completo en JavaScript y Go. Otras cabeceras: X-IC-Event (evento) y X-IC-Delivery (ID única, igual en los reintentos – sirve para detectar entregas duplicadas). Los workflows de esta instancia no pueden comprobar la firma (el nodo Function no conoce HMAC).

Pruebas y entregas

  • Enviar prueba envía al momento un evento ping y muestra el resultado – estado HTTP y duración, o el error.
  • Entregas muestra las últimas 50 entregas desde que se inició el servidor: hora, evento, estado (entregado, fallido, en curso, omitido), estado HTTP, duración, intentos y error con el inicio de la respuesta. Tras un reinicio la lista está vacía.
  • Si el receptor no responde en 10 segundos, o responde 408, 429 o 5xx, IllusionCMS lo reintenta hasta tres veces (tras 2, 10 y 30 segundos). Otras respuestas como 404 no se reintentan; cualquier respuesta 2xx cuenta como entregada.
  • Protección contra bucles: si un webhook llama a uno de tus workflows que vuelve a cambiar contenido, esto se repetiría sin fin. Por eso se detiene tras tres entregas seguidas – las siguientes aparecen como omitido en el registro.
  • Para probarlo sin un servicio externo: un workflow con una entrada HTTP pública (POST) que guarda msg.payload con store.set(…) y un webhook a su dirección – es lo que hace también el seed de prueba.

Cabeceras de seguridad

En Ajustes → Seguridad defines qué cabeceras de protección envía IllusionCMS. Los ajustes solo valen para esta instancia y no están en el Bundle, así que en local y en producción los configuras por separado. La tabla Cabeceras enviadas muestra el resultado.

Ajuste Valor predeterminado Efecto
X-Content-Type-Options: nosniff siempre activado Los navegadores no adivinan el tipo de archivo; una imagen subida, por ejemplo, nunca se ejecuta como script
Referrer Predeterminado Los sitios web ajenos, al hacer clic en un enlace, solo ven tu dominio, no la página exacta
Inserción (iframe) Solo páginas propias Protege contra el clickjacking: las páginas ajenas no pueden incrustar las tuyas de forma invisible. Dominios concretos lo permite, p. ej., a un socio (https://partner.de, *.partner.de); Permitido en todas partes desactiva la protección
Bloquear funciones del navegador desactivado Bloquea cámara, micrófono, ubicación, pagos, USB/Bluetooth, etc. Déjalo desactivado si una página usa, por ejemplo, «Mi ubicación» en un mapa
HSTS desactivado Los navegadores solo acceden al sitio web por HTTPS. Solo se envía por HTTPS, también detrás de un proxy que establezca X-Forwarded-Proto: https. Atención: los navegadores lo recuerdan durante el tiempo configurado, aunque vuelvas a desactivar HSTS. Actívalo solo cuando HTTPS funcione de forma permanente y, para probar, empieza con 5 minutos
Content-Security-Policy vacío Reglas propias sobre desde dónde se pueden cargar scripts, imágenes, fuentes … Con Solo informar el navegador no bloquea nada, sino que notifica las infracciones en la consola. Así pruebas una regla antes de activarla de verdad
Ocultar la versión en /healthz desactivado Los visitantes solo ven {"status":"ok"}. Los usuarios con sesión iniciada y los tokens de API siguen viendo la versión (así que el indicador de versión del admin sigue funcionando)

La inserción, las funciones del navegador y la CSP se aplican a las páginas del sitio web (páginas, 404, sitemap, robots.txt), no al admin, la API, los archivos ni el CSS/JS. La vista previa del admin no se ve afectada.

Lo que deberías saber

  • El HTML, el CSS y el JS son de confianza. Quien trabaja en el admin puede llevar cualquier código al sitio web: concede los accesos y los tokens de escritura en consecuencia.
  • Los campos Markdown no emiten HTML incrustado; así, las entradas de Collection que llegan de fuera por la API no pueden inyectar código.
  • Los SVG subidos se sirven con una política de seguridad que bloquea los scripts incrustados. Los archivos HTML, XML y con extensión desconocida subidos se sirven sin ejecución de scripts y como descarga (política sandbox, sin adivinar el tipo) – se pueden seguir subiendo y enlazando, pero no se ejecutan como página en el origen del admin.