Trae tu propia interfaz

Logto te permite traer tu propia interfaz para reemplazar completamente la experiencia de inicio de sesión incorporada, además de las opciones de personalización de interfaz preconstruidas. Esta función te permite subir un archivo zip que contenga tus propios recursos de interfaz (HTML, CSS, JavaScript, imágenes, etc.), alojarlos en los servidores de Logto Cloud y usarlos como la experiencia de inicio de sesión para los usuarios de tu tenant.

nota:

Esta función requiere que tu interfaz personalizada sea compatible con aplicaciones de una sola página (SPA), y se recomienda usar siempre una compilación de producción para un rendimiento óptimo.

Explora la función de interfaz personalizada en Logto Console

Comienza con el proyecto oficial

La forma más rápida de iniciar una interfaz de inicio de sesión personalizada es clonar el proyecto de experiencia de Logto. Esta es la interfaz de experiencia de inicio de sesión incorporada de Logto que cubre todas las funciones y las mejores prácticas de Logto. Puedes personalizarla para adaptarla a tus necesidades.

Después de revisar el código, simplemente ejecuta el siguiente comando para compilar el proyecto:

pnpm install && pnpm build

nota:

Todo el proyecto Logto es un monorepo de pnpm. Si deseas ejecutar el paquete de experiencia de forma independiente (sin pnpm), reemplaza las dependencias workspace: en package.json por números de versión específicos (como ^1.0.0).

Una vez completada la compilación, encontrarás todos los recursos compilados en el directorio dist. Luego crea un archivo ZIP del directorio dist; este archivo se usará para subirlo a Logto Cloud más adelante.

Requisitos de los recursos de la interfaz personalizada

Antes de subir tus recursos personalizados de interfaz, asegúrate de que cumplan con los siguientes requisitos:

• Los recursos a subir deben estar empaquetados en un solo archivo zip.
• El archivo zip debe contener un archivo index.html en el directorio raíz.
• El archivo zip no debe exceder los 20MB de tamaño.
• El archivo zip no debe contener ningún archivo que exceda los 10MB de tamaño.
• El archivo zip no debe contener más de 200 archivos en total.

Sube tus recursos personalizados de interfaz

nota:

Procede con precaución al usar esta función en producción, ya que afectará inmediatamente la experiencia de inicio de sesión de tus usuarios.

1. Navega a Consola > Inicio de sesión y cuenta > Marca > Trae tu propia interfaz.
2. Haz clic para seleccionar o arrastra y suelta tu archivo zip creado en el paso anterior, y el proceso de carga comenzará automáticamente.
3. Una vez completada la carga, guarda los cambios y tu interfaz personalizada se servirá de inmediato.
4. La ventana de "Vista previa de inicio de sesión" se desactivará cuando uses tu interfaz personalizada de inicio de sesión. Sin embargo, aún puedes hacer clic en el botón "Vista previa en vivo" para probar tu página personalizada de inicio de sesión en una nueva pestaña del navegador.

Configura fuentes CSP personalizadas

Logto aplica un encabezado de Política de Seguridad de Contenidos (CSP) a las páginas de interfaz personalizada. Si tu interfaz personalizada carga scripts de terceros o se conecta a servicios externos, agrega los orígenes adicionales en Consola > Inicio de sesión y cuenta > Marca > Trae tu propia interfaz.

Puedes configurar:

• script-src: Permite fuentes de módulos o scripts JavaScript, como proveedores de CAPTCHA, analítica o gestores de etiquetas.
• connect-src: Permite endpoints de red usados por fetch, XMLHttpRequest, EventSource y conexiones WebSocket.

Ejemplo:

{
  "scriptSrc": ["https://scripts.example.com"],
  "connectSrc": ["https://api.example.com", "wss://events.example.com"]
}

Usa orígenes HTTPS para ambas directivas. connect-src también acepta orígenes wss:// para conexiones WebSocket. Logto añade estas fuentes a la política de seguridad existente solo cuando tus recursos personalizados de interfaz están activos.

Configura el encabezado Cross-Origin-Opener-Policy

Por defecto, Logto no envía ningún encabezado Cross-Origin-Opener-Policy (COOP), por lo que una aplicación que abre la página de inicio de sesión en una ventana emergente puede seguir comunicándose con ella a través de window.opener. Si tus aplicaciones no inician sesión de usuarios mediante ventanas emergentes, puedes aislar tu interfaz personalizada de inicio de sesión de otras ventanas del navegador. Elige una política bajo Cross-Origin-Opener-Policy en Consola > Inicio de sesión y cuenta > Marca > Trae tu propia interfaz:

Opción	Encabezado enviado	Efecto
No establecido (sin header)	Ninguno	Por defecto. Toda integración basada en ventanas emergentes sigue funcionando.
same-origin-allow-popups	Cross-Origin-Opener-Policy: same-origin-allow-popups	Desconecta la ventana que abrió la página de inicio de sesión. Las ventanas emergentes que tu interfaz personalizada abre mantienen window.opener mientras permanezcan en otros sitios.
same-origin	Cross-Origin-Opener-Policy: same-origin	También desconecta las ventanas emergentes que tu interfaz personalizada abre.

También puedes establecer el campo crossOriginOpenerPolicy con la API de Management API para actualizar la experiencia de inicio de sesión. Acepta unsafe-none (por defecto, no envía encabezado), same-origin-allow-popups y same-origin.

aviso:

Antes de elegir una política, revisa cómo tus aplicaciones y tu interfaz personalizada usan ventanas emergentes:

• Las aplicaciones que abren la página de inicio de sesión en una ventana emergente y dependen de window.opener, por ejemplo para recibir el resultado mediante postMessage, dejarán de funcionar con cualquiera de las políticas. Mantén el valor por defecto mientras tengas tales aplicaciones, o migra primero a un flujo de inicio de sesión basado en redirección.
• Las ventanas emergentes que tu interfaz personalizada abre pierden window.opener una vez que navegan de regreso a tu interfaz personalizada, por ejemplo a una página de callback de inicio de sesión social. Las ventanas emergentes que permanecen en otro sitio y envían su resultado desde allí, como la ventana emergente de inicio de sesión de un proveedor, siguen funcionando con same-origin-allow-popups. Con same-origin, las ventanas emergentes pierden window.opener tan pronto como se abren.

Si necesitas una política, prefiere same-origin-allow-popups sobre same-origin.

Logto envía el encabezado solo mientras tus recursos personalizados de interfaz están activos. Las páginas de inicio de sesión incorporadas, las páginas /oidc/* y el Centro de Cuenta (/account) nunca envían un encabezado COOP, por lo que los escáneres de seguridad pueden seguir informando que falta en esas páginas.

Desarrolla tu interfaz personalizada

Interactúa con Experience API

Tu interfaz personalizada necesita interactuar con la Experience API para realizar varias acciones como inicio de sesión, registro, restablecimiento de contraseña, vinculación de cuentas sociales, habilitación de MFA y más. Para comprender mejor los flujos de usuario y los detalles de implementación, te recomendamos revisar nuestro RFC de diseño de Experience API, que proporciona especificaciones técnicas completas y ejemplos.

También necesitas acceder a otras configuraciones de la Experiencia de Inicio de Sesión, como colores de marca, logotipo de la empresa, favicon, política de contraseñas, frases de idioma localizadas e incluso CSS personalizado, a través del endpoint de Experience API de inicio de sesión.

Maneja CAPTCHA cuando esté habilitado

La experiencia de inicio de sesión incorporada de Logto maneja CAPTCHA automáticamente. Si tu tenant usa Trae tu propia interfaz y habilita la protección contra bots CAPTCHA, tu interfaz personalizada debe completar la integración de CAPTCHA en el frontend antes de llamar a PUT /api/experience.

Envía el token del proveedor devuelto como captchaToken en el cuerpo de la solicitud PUT /api/experience. Consulta las guías específicas del proveedor para más detalles:

• reCAPTCHA Enterprise con Trae tu propia interfaz
• Cloudflare Turnstile con Trae tu propia interfaz

Proyectos de ejemplo

Proporcionamos una colección de proyectos de ejemplo para ayudarte a comprender e implementar rápidamente una interfaz personalizada. Consulta el repositorio de GitHub del proyecto de experiencia de Logto para más detalles.

Además, continuaremos trabajando en proporcionar más proyectos de ejemplo simplificados y basados en escenarios para cubrir los casos de uso más comunes. ¡Estate atento a nuestras futuras actualizaciones!

Desarrollo local y depuración

Para el desarrollo local y la depuración, proporcionamos la herramienta Logto Tunnel CLI para:

• Redirigir solicitudes de Experience API desde tu máquina local al endpoint de Logto Cloud.
• Probar tu implementación personalizada de interfaz localmente.

Esto permite a los usuarios probar y depurar la interfaz personalizada localmente antes de subirla a Logto Cloud.

Consulta Depura y prueba tu interfaz personalizada localmente para más detalles.

Sube tus recursos personalizados de interfaz usando la CLI

Además de subirlos a través de la Consola, también puedes usar la CLI de Logto para subir recursos personalizados de interfaz. Esto es especialmente útil para flujos de despliegue automatizados.

Consulta Sube recursos personalizados de interfaz usando la CLI para más detalles.

Restaura la experiencia de inicio de sesión incorporada de Logto

Si deseas restaurar la experiencia de inicio de sesión incorporada de Logto, simplemente haz clic en el botón de eliminar en la tarjeta de Trae tu propia interfaz. Después de guardar los cambios, la interfaz de experiencia de inicio de sesión volverá a la predeterminada de Logto.

Recursos relacionados

RFCS: Experience API

Ejemplos de experiencia

Trae tu propia interfaz de inicio de sesión a Logto Cloud