Keycloak: Personalizza l'aspetto

Personalizza facilmente le pagine di login, la console account e le email di Keycloak su Stackhero: imposta i tuoi colori, il logo, i testi e crea anche temi completamente personalizzati grazie all'editor online integrato.

👋 Benvenuto nella documentazione di Stackhero!

Stackhero offre un servizio Keycloak cloud che semplifica il deployment di un identity provider pronto per la produzione in soli 2 minuti:

• Utenti, realms e client illimitati
• Supporta OpenID Connect, OAuth 2.0, SAML 2.0, social login, federazione LDAP e Active Directory
• Nome di dominio personalizzato con HTTPS integrato per un accesso sicuro (ad esempio, https://login.tua-azienda.com)
• Temi personalizzati: personalizza facilmente le tue pagine di login, la console account e le email grazie all’editor online incluso
• Server email dedicato con SPF, DKIM e DMARC, così le conferme account e i reset password vengono gestiti automaticamente
• Database PostgreSQL integrato, con la console di amministrazione disponibile su una porta dedicata e disattivabile
• Aggiornamenti one-click per mantenere il sistema sempre aggiornato senza interventi manuali

Dedica il tuo tempo allo sviluppo, non alla configurazione: puoi provare la soluzione Keycloak cloud di Stackhero in meno di 5 minuti.

Personalizza l'aspetto di Keycloak

La pagina di login è uno dei primi elementi che i tuoi utenti vedono. Con Stackhero, puoi renderla unica in pochi minuti: imposta i tuoi colori, il logo e i testi per ogni lingua supportata. Lo stesso approccio si applica anche alle email inviate da Keycloak.

Hai a disposizione due strumenti principali, entrambi inclusi nel servizio:

• L'editor dei temi, un editor di file online dove risiede il tuo tema.
• Quick Theme, il designer visuale integrato nella console di amministrazione Keycloak, per scegliere colori e branding senza modificare il CSS.

Non è necessario SSH, né ricompilare o ridistribuire nulla.

Accedi all'editor dei temi

Nella pagina del tuo servizio sulla dashboard Stackhero trovi un URL Themes editor accanto alla console di amministrazione:

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

Accedi con le credenziali amministrative di Keycloak: le stesse che usi per la console di amministrazione.

Ecco due aspetti importanti da ricordare:

• L'editor gira sulla porta di amministrazione, non su quella usata dalle applicazioni. Se chiudi questa porta nel firewall Stackhero, sia la console di amministrazione che l'editor non saranno più accessibili. Le tue applicazioni continueranno ad autenticarsi normalmente.
• Tutte le modifiche effettuate vengono salvate sul disco del servizio, incluse nei backup e persistono dopo riavvii e aggiornamenti.

Troverai due directory:

Ogni directory contiene un file README.md con la documentazione aggiornata relativa alla versione del tuo servizio.

Il tuo tema è pronto per essere modificato

Apri themes/ e troverai una directory default/. Questo è il tuo tema attivo, già in uso dalla tua istanza Keycloak. Non c'è nulla da selezionare: modifica semplicemente i file e vedrai subito i cambiamenti.

Non è richiesta alcuna conoscenza pregressa dei temi Keycloak. Ogni file contiene già le impostazioni più comuni che potresti voler modificare, mostrando il valore Keycloak attuale come esempio commentato. Per aggiornare un valore, rimuovi il simbolo di commento, modifica il valore e salva.

Se una riga rimane commentata, Keycloak utilizza il valore predefinito. Questo garantisce che il servizio sia sempre conforme al comportamento standard di Keycloak, anche dopo eventuali aggiornamenti.

Aggiornare il logo

Apri default/login/resources/img/. All'interno troverai le due immagini attualmente utilizzate nella pagina di login. Carica il tuo logo usando lo stesso nome file, keycloak-logo-text.svg, e aggiorna la pagina di login con Ctrl+F5 (Cmd+Shift+R su macOS).

Non serve altro. Non è necessario modificare altri file o riavviare il servizio: l'aggiornamento viene applicato appena salvi. Per cambiare l'immagine di sfondo, aggiorna keycloak-bg-darken.svg nella stessa cartella.

Se preferisci usare nomi file diversi, puoi aggiornare i riferimenti nella sezione "Your logo" di default/login/resources/css/stackhero.css.

Impostare i colori

In stackhero.css troverai già le variabili con i valori attuali:

: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; */

Per applicare una modifica, rimuovi i simboli di commento, imposta il tuo colore, salva e ricarica la pagina. Tutto qui.

Durante la personalizzazione: Il browser memorizza nella cache CSS, immagini e script del tema per un'ora. Durante le modifiche, aggiorna sempre con Ctrl+F5 per vedere i cambiamenti più recenti. I tuoi visitatori vedranno l'aggiornamento entro un'ora.

Hai pieno controllo: il file è CSS puro e viene caricato per ultimo, quindi puoi sovrascrivere qualsiasi stile. Usa gli strumenti di sviluppo del browser (F12) per ispezionare gli elementi. Keycloak 26 utilizza il PatternFly design system, quindi la maggior parte delle variabili colore sono denominate --pf-v5-global--* e possono essere ridefinite in :root.

Impostare il nome della tua azienda

Non è necessario modificare il tema per questa operazione. Nella console di amministrazione, apri Realm settings > General e imposta il Display name. Questo nome apparirà nelle pagine di login e nelle email.

Modificare i testi, in più lingue

Puoi aggiornare i testi senza toccare CSS o HTML. In default/login/messages/messages_en.properties troverai tutti i testi del form di login con la dicitura predefinita. Per modificare una riga, rimuovi il #, inserisci il tuo testo e salva:

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

Aggiungi file come messages_fr.properties per il francese o messages_de.properties per il tedesco, poi abilita queste lingue nella console di amministrazione in Realm settings > Localization.

Suggerimento: La scheda Localization offre anche una sezione Realm overrides che consente di modificare i testi direttamente dalla console, senza modificare file o riavviare. Usa il metodo che meglio si adatta al tuo flusso di lavoro.

Personalizzare le email

Keycloak invia email per la conferma dell'indirizzo, il reset della password e gli inviti agli utenti. In default/email/messages/messages_en.properties troverai gli oggetti e i messaggi standard pronti per essere personalizzati:

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

Quando modifichi il corpo delle email, ricorda:

• Mantieni i placeholder {0}, {1}, {2} (Keycloak li sostituirà con il link, il nome visualizzato e il tempo di validità).
• Per inserire un apostrofo, scrivilo doppio (don''t).

Per sovrascrivere l'HTML delle email, copia il template desiderato dal Keycloak base email theme in default/email/html/, poi modifica la tua copia.

Stackhero configura per te l'invio delle email con SPF, DKIM e DMARC già impostati. Configuralo in Realm settings > Email usando host e porta forniti nella pagina del servizio.

Se hai bisogno di ripristinare il tema

Se qualcosa va storto, puoi eliminare l'intera directory default e riavviare il servizio. Stackhero ricreerà un tema predefinito, ripristinando l'aspetto standard di Keycloak.

I tuoi realms, utenti e client sono memorizzati nel database e non vengono toccati.

Progetta il tuo tema visivamente con Quick Theme

Nella console di amministrazione Keycloak troverai Quick Theme, il designer visuale dei temi Keycloak. Carica un logo, scegli i colori, visualizza l'anteprima delle pagine di login e account, e scarica il tema finale come file .jar.

Per installarlo, posiziona il file nella directory themes/ tramite l'editor, poi riavvia il servizio. Il .jar viene estratto in una directory tema e l'archivio viene rimosso:

themes/acme.jar        diventa     themes/acme/

Il nuovo tema apparirà in Realm settings > Themes. Puoi continuare a modificare i file manualmente se lo desideri.

Questo metodo supporta anche temi creati con Keycloakify o forniti da un designer. Qualsiasi .jar o .zip contenente un tema può essere installato in questo modo. Se esiste già un tema con lo stesso nome, quello nuovo verrà installato come acme-1, così i caricamenti non sovrascrivono mai il tuo lavoro. Se il file non è un tema, viene semplicemente ignorato e Keycloak si avvia normalmente.

Un brand per ogni realm: supporto white-label

I temi vengono selezionati per realm in Realm settings > Themes, con opzioni per ogni tipo di pagina: login, account, admin ed email. Ogni applicazione può anche specificare il proprio tema di login nelle impostazioni del client.

Se gestisci più brand o offri soluzioni white-label, usa un realm per ogni brand e assegna un tema personalizzato a ciascuno:

1. Nell'editor, copia la directory default e rinomina la copia (ad esempio, acme).
2. Riavvia il servizio.
3. Nella console di amministrazione, apri il realm interessato e seleziona acme come tema di login.

Ogni realm non configurato continuerà a utilizzare il tema default.

Comprendere la struttura di un tema Keycloak

Un tema è una directory che contiene sottodirectory per ogni tipo di pagina:

themes/
  acme/
    login/                             # Pagine di login utente
      theme.properties                 # Ereditarietà tema e inclusione CSS
      resources/css/stackhero.css      # Il tuo CSS
      resources/img/logo.svg           # Le tue immagini
      messages/messages_en.properties  # I tuoi testi
    account/                           # Gestione profilo utente
    admin/                             # Aspetto della console di amministrazione
    email/                             # Template email

I temi ereditano dai temi standard di Keycloak, sovrascrivendo solo ciò che serve. Un tipico file login/theme.properties appare così:

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

• parent imposta il tema di base.
• styles elenca i file CSS da caricare. Metti il tuo CSS per ultimo per assicurarti che le modifiche abbiano effetto.

L'elenco styles sostituisce quello del tema padre, non lo estende. Includi sempre il foglio di stile del padre (css/styles.css) altrimenti la pagina perderà lo stile predefinito.

Hai bisogno dei template FreeMarker (.ftl) solo se vuoi modificare la struttura HTML. Per colori, loghi, sfondi, testi e lingue, non è necessario modificare i template. Per maggiori dettagli, consulta la documentazione sui temi Keycloak.

Estensioni Java (providers)

La directory providers/ è destinata alle funzionalità che i temi non possono offrire: autenticatori personalizzati, user storage, event listener o protocol mapper.

Posiziona il tuo file .jar in questa directory e riavvia il servizio. Questo riavvio richiede un po' più tempo (circa un minuto) perché Keycloak si ricostruisce per includere la nuova estensione. Per rimuovere un'estensione, elimina il file e riavvia nuovamente.

Puoi anche inserire file .jar di temi qui, ma per i temi è preferibile usare themes/: non richiede ricostruzione e ti permette di modificare i file successivamente.