Saltar al contenido principal

Personalizar la página de inicio de sesión en Casdoor: estilo personalizado de la interfaz de autenticación sin bifurcar

· 11 min de lectura
Yang Luo
Yang Luo
Casdoor Maintainer

Sí, Casdoor admite el estilo personalizado de su interfaz de autenticación, y no necesitas bifurcar el frontend para lograrlo. Cada aplicación tiene una pestaña UI Customization donde puedes configurar el logotipo, favicon, imagen de fondo, CSS personalizado para escritorio y móvil, la posición del formulario, un panel lateral, HTML de pie de página y un tema. Dos tablas, Signin items y Signup items, deciden qué campos muestran las páginas de inicio de sesión y registro, en qué orden, con qué etiquetas y marcadores de posición. Todo se almacena por aplicación en la base de datos, por lo que una instancia de Casdoor puede servir muchas páginas de inicio de sesión con marcas diferentes, y los administradores de la organización pueden editar sus propias páginas dentro de límites seguros.

Qué cambiar y dónde​

Qué quieres cambiarDónde en CasdoorDocumentación
Color primario, radio de esquina, estilo oscuro o compactoTheme de la organización, o de la aplicación con Follow organization theme desactivadoCustomize the theme
Una apariencia completa lista para usarIdentity → Marketplace, temas de inicio de sesiónMarketplace
Logotipo, logotipo oscuro, favicon, título de páginaPágina de edición de la aplicaciónApplication settings
Imagen de fondo (escritorio y teléfono)Background URL, Background URL MobileUI customization
Apariencia del formularioCustom CSS, Custom CSS MobileUI customization
Formulario a la izquierda, centro o derecha, o junto a un panelForm position, Side panel HTMLUI customization
Texto debajo del formularioFooter HTMLApplication settings
Campos que muestra la página de inicio de sesión, orden, marcadores de posiciónSignin itemsSign-in items table
Contraseña, código, enlace mágico, WebAuthn, LDAP y su ordenSignin methodsSign-in methods
Campos de registro, banderas de obligatorio, etiquetas, regexSignup itemsSign-up items table
Selector de idiomaElemento de inicio de sesión Languages, Languages de la organizaciónSign-in items table
Permitir a los usuarios elegir o escribir su organizaciónOrg choice modeSpecify login organization

En la consola en chino, la pestaña se llama 界面定制 y la tabla de inicio de sesión 登录项, así que si buscas cómo cambiar la 登录界面 de una aplicación, empieza por ahí.

Temas: organización, aplicación y Marketplace​

El cambio más rápido es el tema. Un tema en Casdoor es un pequeño objeto con un estilo (Default, Dark, Document o Blossom en el editor), un color primario, un radio de borde y un interruptor compacto. Puedes configurarlo en la organización, donde se aplica a la consola para sus miembros y a las páginas de entrada de cada aplicación que sigue el tema de la organización, o en una sola aplicación desactivando Follow organization theme. La página de edición de la aplicación tiene una vista previa en vivo, por lo que puedes ver el resultado antes de guardar.

Si quieres algo más que colores, el Casdoor Marketplace tiene temas de inicio de sesión. Instalar uno escribe los datos del tema, la posición del formulario, el CSS del formulario para escritorio y móvil, el HTML del panel lateral, el HTML del pie de página y las URLs de fondo de una aplicación. El repositorio casdoor-integrations contiene actualmente 24 temas, desde Midnight y Split hasta Terminal, Nord y Solarized. Desinstalar un tema restaura lo que la aplicación tenía antes, por lo que probar uno no cuesta nada. Explóralos en marketplace.casdoor.com.

Marca: logotipo, favicon y fondo​

Cada aplicación tiene su propio Logo, Favicon y Title, separados de los de la organización. Una organización puede ejecutar varios productos que comparten usuarios pero muestran logotipos diferentes. También hay un Logo dark opcional, que se muestra cuando la página está en modo oscuro; sin él, Casdoor sigue usando el logotipo normal.

Background URL establece la imagen detrás del formulario. Establece también Background URL Mobile si la imagen de escritorio recorta mal en teléfonos. La vista previa se actualiza tan pronto como se carga la URL.

CSS personalizado y diseño del formulario​

Custom CSS acepta reglas CSS simples; Casdoor las envuelve en un elemento style por sí mismo, así que no añadas uno propio. Los contenedores principales a los que apuntar son .login-panel y .login-form:

.login-panel {
  border-radius: 12px;
  background-color: #ffffff;
  box-shadow: 0 0 30px 20px rgba(0, 0, 0, 0.2);
}

Custom CSS Mobile contiene reglas para teléfonos, por lo que no necesitas escribir consultas de medios para el caso común.

Form position coloca el formulario a la izquierda, en el centro o a la derecha. La cuarta opción, Enable side panel, centra el formulario y pone un panel al lado cuyo contenido proviene de Side panel HTML. Ese campo acepta HTML, por lo que un elemento style dentro está bien.

Footer HTML se renderiza debajo de los formularios de inicio de sesión y registro. Si la aplicación es la aplicación predeterminada de su organización, su pie de página también reemplaza "Powered by Casdoor" en la consola de administración para los usuarios de esa organización.

Cuando estés satisfecho con un diseño en staging, Export JSON en la parte inferior de la página de edición de la aplicación copia la apariencia (logotipo, favicon, fondos, CSS, posición del formulario, panel lateral, tema y los campos de HTML personalizado) al portapapeles, y Import JSON en la misma aplicación en otra instancia la aplica. La exportación no contiene secretos ni proveedores.

Campos, etiquetas y orden​

La tabla Signin items lista cada elemento de la página de inicio de sesión: el logotipo, los campos de nombre de usuario y contraseña, el enlace para recuperar la contraseña, la casilla de verificación del acuerdo, el selector de idioma, el captcha, los botones de proveedores, etc. Para cada fila puede configurar Visible, un Placeholder personalizado, Custom CSS por elemento y una regla, además de moverlo hacia arriba o hacia abajo. También puede agregar elementos personalizados cuya etiqueta sea HTML.

Algunas reglas que conviene conocer:

  • Ocultar Forgot password? desactiva el restablecimiento de la contraseña también en la API, no solo el enlace.
  • La regla Captcha cambia entre un captcha emergente y uno en línea. Si está eligiendo un proveedor de captcha, consulte Comparación de proveedores de CAPTCHA para páginas de inicio de sesión.
  • La regla Languages cambia entre un icono de globo y un selector etiquetado. La lista se limita a los Languages de la organización, por lo que una organización que solo atiende a usuarios de inglés y japonés mostrará únicamente esos dos.

Los métodos de inicio de sesión (contraseña, código de verificación, enlace mágico, WebAuthn, LDAP, Face ID y otros) son una tabla separada, Signin methods, con su propio orden y nombres de visualización.

La tabla Signup items hace lo mismo para el registro, con validaciones Required, Regex, Label personalizado y reglas como "No verification" para el correo electrónico. POST /api/signup también limpia todos los campos cuyo elemento está oculto, por lo que los clientes de API no pueden establecer campos que su formulario no muestra. Prompted solicita a los usuarios los campos faltantes, como un número de teléfono, después de iniciar sesión a través de un proveedor que no los proporcionó.

Especificar la organización de inicio de sesión​

Si varias organizaciones comparten un Casdoor, los usuarios necesitan una forma de llegar a la correcta. Org choice mode en la aplicación predeterminada de una organización (o en app-built-in) agrega un paso de selección de organización a /login: Input muestra un campo de texto, Select muestra un menú desplegable. Después de que el usuario elige, Casdoor lo envía a /login/<organization>, que muestra la página con el estilo propio de esa organización. El navegador recuerda la última organización en localStorage, por lo que un usuario cuya sesión de consola haya expirado aterrizará nuevamente en su propia página de inicio de sesión.

Qué pueden cambiar de forma segura los administradores de inquilinos​

Permitir que cada cliente personalice su propia página de inicio de sesión plantea una pregunta obvia: ¿qué impide que un administrador de organización agregue un script que copie contraseñas, o un selector CSS que filtre cada carácter escrito mediante solicitudes de imágenes de fondo? Casdoor verifica esto en el servidor. Cuando un administrador que no es un administrador global agrega o guarda una aplicación, cada campo HTML y CSS personalizado que cambió es validado, y el guardado se rechaza si alguno de ellos incumple las reglas:

  • El HTML solo puede usar elementos de diseño y texto como div, span, p, encabezados, listas, enlaces, imágenes, tablas, style y formas SVG básicas. Se rechazan script, form, input e iframe, así como manejadores de eventos on..., atributos srcset, formaction, srcdoc y similares. href solo se permite en enlaces con URLs relativas, http, https, mailto o tel.
  • El CSS no puede contener barras invertidas, <, image(, image-set( y algunas otras funciones. Cada url() debe ser relativa, una URL data: o comenzar con un prefijo permitido: Google Fonts, Fontsource en jsDelivr, los CDNs de Casdoor, el origen propio de este Casdoor, los dominios de los proveedores de almacenamiento globales o una entrada de formCssAllowedUrls.
  • @import solo se permite desde Google Fonts y Fontsource, porque una hoja de estilos importada no se verifica en sí misma.

Para permitir que los inquilinos carguen imágenes desde su propio host, agréguelo a conf/app.conf (consulte Configuración):

formCssAllowedUrls = "https://img.example.com/"

Además de la comprobación al guardar, las páginas de inicio de sesión sanitizan el HTML personalizado antes de renderizarlo, a menos que la aplicación pertenezca a la organización built-in o que un administrador global haya activado Enable custom scripts para ella. Solo un administrador global puede activar ese interruptor, y mientras esté activado, solo un administrador global puede cambiar el HTML de esa aplicación. Las mismas reglas se aplican cuando un inquilino instala un tema de Marketplace: un tema que incumpla estas reglas solo puede ser instalado por un administrador global.

Signin HTML y Signup HTML merecen una nota aparte: reemplazan toda la página integrada, incluido el formulario. Dado que los inquilinos no pueden agregar formularios ni scripts, estos dos campos están destinados principalmente a los administradores globales; para la imagen de marca, CSS, el panel lateral y el pie de página son las mejores herramientas.

¿Página de inicio de sesión alojada o su propia interfaz de usuario?​

Puede construir su propia pantalla de inicio de sesión sobre la API de Casdoor, pero la página alojada suele ser la mejor opción. Con OAuth 2.0 u OpenID Connect, los usuarios escriben su contraseña solo en el origen de Casdoor y su aplicación recibe un código de autorización, nunca las credenciales. Captcha, MFA, proveedores sociales y empresariales, recuperación de contraseña, validación de registro y el selector de organización siguen funcionando sin código de su parte, y continúan recibiendo correcciones al actualizar Casdoor. Una interfaz de usuario personalizada tiene que reimplementar cada uno de esos flujos y pasa las contraseñas a través de sus propios servidores. Guías para integrar la página alojada en una aplicación: SSO con Spring Boot usando OIDC y Autenticación SSO con Nginx.

Otros proveedores alojados hacen el mismo intercambio. Idura Verify, por ejemplo, le permite agregar una URL de hoja de estilos y HTML personalizado alrededor de su cuadro de inicio de sesión desde su panel, bajo una estricta Política de Seguridad de Contenido (CSP) con una lista explícita de orígenes de estilos para fuentes e imágenes. formCssAllowedUrls de Casdoor desempeña el mismo papel, con la diferencia de que Casdoor es de código abierto y autoalojado, por lo que usted controla la lista.

Referencias​