Keycloak: Personalizar la apariencia

Personalice fácilmente las páginas de inicio de sesión, la consola de cuenta y los correos electrónicos de Keycloak en Stackhero: configure sus colores, logotipo, textos e incluso cree temas totalmente personalizados con el editor online integrado.

👋 ¡Bienvenido a la documentación de Stackhero!

Stackhero ofrece un servicio de Keycloak en la nube que le permite desplegar un proveedor de identidad listo para producción en solo 2 minutos:

• Usuarios, realms y clientes ilimitados
• Compatible con OpenID Connect, OAuth 2.0, SAML 2.0, inicio de sesión social, federación LDAP y Active Directory
• Nombre de dominio personalizado con HTTPS integrado para un acceso seguro (por ejemplo, https://login.su-empresa.com)
• Temas personalizados: personalice fácilmente sus páginas de inicio de sesión, la consola de cuentas y los correos electrónicos con el editor online incluido
• Servidor de correo electrónico dedicado con SPF, DKIM y DMARC, para que las confirmaciones de cuenta y los restablecimientos de contraseña se gestionen automáticamente
• Base de datos PostgreSQL integrada, con la consola de administración disponible en un puerto dedicado y cerrable
• Actualizaciones con un solo clic para mantener su sistema siempre actualizado sin intervención manual

Dedique su tiempo a desarrollar, no a configurar: puede probar la solución Keycloak en la nube de Stackhero en menos de 5 minutos.

Personalizar la apariencia de su Keycloak

La página de inicio de sesión es una de las primeras cosas que ven sus usuarios. Con Stackhero, puede personalizarla en solo unos minutos: configure sus colores, logotipo y textos para cada idioma que soporte. El mismo método se aplica a los correos electrónicos que envía Keycloak.

Hay dos herramientas principales, ambas incluidas en su servicio:

• El editor de temas, un editor de archivos online donde reside su tema.
• Quick Theme, el diseñador visual de temas integrado en la consola de administración de Keycloak, para elegir colores e identidad visual sin editar CSS.

No se requiere SSH, ni reconstrucciones ni redepliegues.

Abrir el editor de temas

En la página de su servicio en el panel de Stackhero encontrará una URL de Themes editor junto a su consola de administración:

https://your-domain.com:4443/stackhero_themes/

Inicie sesión con sus credenciales de administrador de Keycloak: las mismas que utiliza para la consola de administración.

Tenga en cuenta dos aspectos importantes:

• El editor se ejecuta en el puerto de administración, no en el puerto que usan sus aplicaciones. Si cierra ese puerto en el firewall de Stackhero, tanto la consola de administración como el editor dejarán de estar accesibles. Sus aplicaciones seguirán autenticando con normalidad.
• Todo lo que cambie aquí se almacena en el disco de su servicio, se incluye en sus copias de seguridad y persiste tras reinicios y actualizaciones.

Encontrará dos directorios:

Cada directorio incluye un archivo README.md con documentación actualizada correspondiente a la versión de su servicio.

Su tema está listo para editar

Abra themes/ y encontrará un directorio default/. Este es su tema activo, ya en uso por su instancia de Keycloak. No hay nada que seleccionar: simplemente edite sus archivos y verá los cambios reflejados al instante.

No necesita conocimientos previos sobre temas de Keycloak. Cada archivo ya incluye los ajustes habituales que puede querer modificar, mostrando el valor actual de Keycloak como ejemplo comentado. Para actualizar un valor, elimine el carácter de comentario, ajuste el valor y guarde.

Si una línea permanece comentada, Keycloak usará su valor por defecto. Esto garantiza que su servicio siempre se comporte como Keycloak estándar, incluso tras actualizaciones.

Actualizar su logotipo

Abra default/login/resources/img/. Dentro encontrará las dos imágenes que actualmente se usan en su página de inicio de sesión. Suba su propio logotipo usando el mismo nombre de archivo, keycloak-logo-text.svg, y actualice la página de inicio de sesión con Ctrl+F5 (Cmd+Shift+R en macOS).

Eso es todo lo que necesita hacer. No es necesario editar archivos ni reiniciar el servicio: los cambios se aplican en cuanto guarde. Para cambiar la imagen de fondo, actualice keycloak-bg-darken.svg en la misma carpeta.

Si prefiere usar otros nombres de archivo, puede actualizar las referencias en default/login/resources/css/stackhero.css en la sección "Your logo".

Configurar sus colores

En stackhero.css encontrará variables ya escritas con sus valores actuales:

:root {
  /* ---------- Colors ---------- */
  /* The buttons */
  /* --pf-v5-global--primary-color--100: #06c; */
  /* The buttons, while hovered */
  /* --pf-v5-global--primary-color--200: #004080; */
  /* The links */
  /* --pf-v5-global--link--Color: #06c; */
  /* The colored line on top of the login box */
  /* --keycloak-card-top-color: #06c; */

Para aplicar un cambio, elimine las marcas de comentario, establezca su color, guarde y recargue la página. Eso es todo.

Mientras trabaja: Su navegador almacena en caché el CSS, las imágenes y los scripts del tema durante una hora. Cuando esté haciendo pruebas, recargue siempre con Ctrl+F5 para ver los últimos cambios. Sus visitantes verán las actualizaciones en el plazo de una hora.

Tiene control total: el archivo es CSS estándar y se carga al final, por lo que puede sobrescribir cualquier estilo. Utilice las DevTools de su navegador (F12) para inspeccionar los elementos. Keycloak 26 utiliza el PatternFly design system, así que la mayoría de las variables de color se llaman --pf-v5-global--* y pueden redefinirse en :root.

Configurar el nombre de su empresa

No es necesario editar el tema para esto. En la consola de administración, abra Realm settings > General y establezca el Display name. Este nombre aparecerá en las páginas de inicio de sesión y en los correos electrónicos.

Cambiar textos, en varios idiomas

Puede actualizar los textos sin tocar CSS ni HTML. En default/login/messages/messages_en.properties encontrará todos los textos del formulario de inicio de sesión con su redacción por defecto. Para cambiar una línea, elimine el #, escriba su propio texto y guarde:

loginAccountTitle=Sign in to Acme
doLogIn=Sign in
doForgotPassword=I forgot my password

Añada archivos como messages_fr.properties para francés o messages_de.properties para alemán, y luego active esos idiomas en la consola de administración en Realm settings > Localization.

Consejo: La pestaña Localization también tiene una sección Realm overrides que le permite cambiar textos directamente desde la consola: no es necesario editar archivos ni reiniciar. Utilice el método que mejor se adapte a su flujo de trabajo.

Personalizar sus correos electrónicos

Keycloak envía correos electrónicos para confirmación de dirección, restablecimiento de contraseña e invitaciones de usuario. En default/email/messages/messages_en.properties encontrará los asuntos y mensajes estándar listos para personalizar:

emailVerificationSubject=Confirm your Acme account
passwordResetSubject=Reset your Acme password

Al editar los cuerpos de los correos, recuerde:

• Mantenga los placeholders {0}, {1}, {2} (Keycloak los rellenará con el enlace, el nombre a mostrar y el tiempo de validez).
• Para escapar una apóstrofe, escríbala dos veces (don''t).

Para sobrescribir el HTML de los correos, copie la plantilla que desee desde el Keycloak base email theme en default/email/html/ y edite su copia.

Stackhero configura el envío de correos por usted con SPF, DKIM y DMARC ya preparados. Configúrelo en Realm settings > Email usando el host y puerto que aparecen en la página de su servicio.

Si necesita restablecer su tema

Si algo sale mal, puede eliminar todo el directorio default y reiniciar su servicio. Stackhero creará un tema por defecto nuevo, restaurando la apariencia estándar de Keycloak.

Sus realms, usuarios y clientes se almacenan en su base de datos y no se ven afectados.

Diseñe su tema visualmente con Quick Theme

En la consola de administración de Keycloak encontrará Quick Theme, el diseñador visual de temas de Keycloak. Suba un logotipo, elija sus colores, previsualice sus páginas de inicio de sesión y cuenta, y descargue el tema finalizado como un archivo .jar.

Para instalarlo, coloque el archivo en el directorio themes/ usando el editor y reinicie su servicio. El .jar se descomprime en un directorio de tema y el archivo se elimina:

themes/acme.jar        pasa a ser     themes/acme/

El nuevo tema aparecerá en Realm settings > Themes. Puede seguir editando sus archivos manualmente si lo desea.

Este método también es compatible con temas creados con Keycloakify o proporcionados por un diseñador. Cualquier archivo .jar o .zip que contenga un tema puede instalarse de esta forma. Si ya existe un tema con el mismo nombre, el nuevo se instalará como acme-1, asegurando que sus subidas nunca sobrescriban su trabajo. Si el archivo no es un tema, simplemente se deja sin tocar y Keycloak arranca normalmente.

Una marca por realm: soporte white-label

Los temas se seleccionan por realm en Realm settings > Themes, con opciones para cada tipo de página: inicio de sesión, cuenta, admin y correo electrónico. Las aplicaciones individuales también pueden especificar su propio tema de inicio de sesión en la configuración del cliente.

Si gestiona varias marcas u ofrece soluciones white-label, utilice un realm por marca y asigne un tema personalizado a cada uno:

1. En el editor, copie el directorio default y renombre la copia (por ejemplo, acme).
2. Reinicie su servicio.
3. En la consola de administración, abra el realm correspondiente y seleccione acme como su tema de inicio de sesión.

Cualquier realm que no configure seguirá usando su tema default.

Entender la estructura de un tema Keycloak

Un tema es un directorio que contiene subdirectorios para cada tipo de página:

themes/
  acme/
    login/                             # Páginas de inicio de sesión de usuario
      theme.properties                 # Herencia del tema e inclusión de CSS
      resources/css/stackhero.css      # Su CSS
      resources/img/logo.svg           # Sus imágenes
      messages/messages_en.properties  # Sus textos
    account/                           # Gestión del perfil de usuario
    admin/                             # Apariencia de la consola de administración
    email/                             # Plantillas de correo electrónico

Los temas heredan de los temas estándar de Keycloak, sobrescribiendo solo lo necesario. Un login/theme.properties típico se ve así:

parent=keycloak.v2
styles=css/styles.css css/stackhero.css

• parent define el tema base.
• styles lista los archivos CSS a cargar. Coloque su CSS al final para asegurarse de que sus cambios tengan efecto.

La lista styles reemplaza la lista del tema padre, no la amplía. Recuerde incluir la hoja de estilos del padre (css/styles.css) o su página perderá el estilo por defecto.

Solo necesita plantillas FreeMarker (.ftl) si desea cambiar la estructura HTML. Para colores, logotipos, fondos, textos e idiomas, no es necesario editar plantillas. Para más detalles, consulte la documentación de temas de Keycloak.

Extensiones Java (providers)

El directorio providers/ está destinado a funcionalidades que los temas no pueden proporcionar: autenticadores personalizados, almacenamiento de usuarios, listeners de eventos o protocol mappers.

Coloque su archivo .jar en este directorio y reinicie su servicio. Este reinicio tarda un poco más (alrededor de un minuto) ya que Keycloak se recompila para incluir la nueva extensión. Para eliminar una extensión, borre el archivo y reinicie de nuevo.

También puede colocar archivos .jar de temas aquí, pero para temas se recomienda usar themes/: no requiere reconstrucción y le permite editar los archivos después.