Personalizzazione della pagina di accesso per Keycloak

1. Panoramica

Keycloak è un server di autorizzazione di terze parti utilizzato per gestire i requisiti di autenticazione e autorizzazione delle nostre applicazioni web o mobili. Utilizza una pagina di accesso predefinita per accedere agli utenti per conto della nostra app.

In questo tutorial, ci concentreremo su come personalizzare la pagina di accesso per il nostro server Keycloak in modo che possiamo avere un aspetto diverso. Lo vedremo sia per i server standalone che per quelli incorporati.

Costruiremo oltre ai temi di personalizzazione per il tutorial Keycloak per farlo.

2. Personalizzazione di un server Keycloak autonomo

Continuando con il nostro esempio del tema personalizzato , vediamo prima il server standalone.

2.1. Impostazioni della Console di amministrazione

Per avviare il server, andiamo alla directory in cui è conservata la nostra distribuzione Keycloak ed eseguiamo questo comando dalla sua cartella bin :

./standalone.sh -Djboss.socket.binding.port-offset=100

Una volta avviato il server, dobbiamo solo aggiornare la pagina per vedere le nostre modifiche riflesse, grazie alle modifiche che abbiamo precedentemente apportato a standalone.xml .

Ora creiamo una nuova cartella, denominata login , all'interno della directory themes / custom . Per mantenere le cose semplici, copieremo prima tutto il contenuto della directory themes / keycloak / login qui. Questo è il tema della pagina di accesso predefinito.

Quindi, andremo alla console di amministrazione, digiteremo le credenziali iniziali1 / zaq1! QAZ e andremo alla scheda Temi per il nostro regno:

Selezioneremo personalizzato per il tema di accesso e salveremo le nostre modifiche.

Con quel set, ora possiamo provare alcune personalizzazioni. Ma prima, diamo un'occhiata alla pagina di accesso predefinita:

2.2. Aggiunta di personalizzazioni

Ora diciamo che dobbiamo cambiare lo sfondo. Per questo, apriremo login / resources / css / login.css e cambieremo la definizione della classe:

.login-pf body { background: #39a5dc; background-size: cover; height: 100%; }

Per vedere l'effetto, aggiorniamo la pagina:

Successivamente, proviamo a cambiare le etichette per il nome utente e la password.

Per ottenere ciò, dobbiamo creare un nuovo file, messages_en.properties nella cartella theme / login / messages . Questo file sovrascrive il pacchetto di messaggi predefinito utilizzato per le proprietà fornite:

usernameOrEmail=Enter Username: password=Enter Password:

Per testare, aggiorna di nuovo la pagina:

Supponiamo di voler modificare l'intero HTML o una parte di esso, dovremo sovrascrivere i modelli di freemarker che Keycloak utilizza per impostazione predefinita. I modelli predefiniti per la pagina di accesso sono conservati nella directory base / login .

Supponiamo di voler visualizzare BENVENUTO IN BAELDUNG al posto di SPRINGBOOTKEYCLOAK .

Per questo, dovremo copiare base / login / template.ftl nella nostra cartella custom / login .

Nel file copiato, cambia la riga:

 ${kcSanitize(msg("loginTitleHtml",(realm.displayNameHtml!'')))?no_esc} 

Per:

 WELCOME TO BAELDUNG 

La pagina di accesso ora visualizzerà il nostro messaggio personalizzato invece del nome del dominio.

3. Personalizzazione di un server Keycloak incorporato

Il primo passo qui è aggiungere tutti gli artefatti che abbiamo modificato per il server autonomo al codice sorgente del nostro server di autorizzazione incorporato.

Quindi, creiamo una nuova cartella di accesso all'interno di src / main / resources / themes / custom con questi contenuti:

Ora tutto ciò che dobbiamo fare è aggiungere istruzioni nel nostro file di definizione realm, baeldung-realm.json, in modo che venga utilizzato personalizzato per il nostro tipo di tema di accesso:

"loginTheme": "custom",

Siamo già stati reindirizzati alla directory del tema personalizzato in modo che il nostro server sappia da dove prelevare i file del tema per la pagina di accesso.

Per il test, andiamo alla pagina di accesso:

Come possiamo vedere, tutte le personalizzazioni eseguite in precedenza per il server autonomo, come lo sfondo, i nomi delle etichette e il titolo della pagina, vengono visualizzate qui.

4. Bypassare la pagina di accesso di Keycloak

Tecnicamente, possiamo bypassare completamente la pagina di accesso di Keycloak utilizzando la password o il flusso di concessione dell'accesso diretto. Tuttavia, si consiglia vivamente di non utilizzare affatto questo tipo di concessione.

In questo caso, non esiste un passaggio intermedio per ottenere un codice di autorizzazione e quindi ricevere in cambio il token di accesso. Invece, possiamo inviare direttamente le credenziali dell'utente tramite una chiamata API REST e ottenere il token di accesso in risposta.

Ciò significa effettivamente che possiamo utilizzare la nostra pagina di accesso per raccogliere l'ID e la password dell'utente e, insieme all'ID del client e al segreto, inviarlo a Keycloak in un POST al suo endpoint token .

Ma ancora una volta, poiché Keycloak fornisce un ricco set di opzioni di accesso, come ricordami, reimpostazione della password e MFA, per citarne alcuni, ci sono pochi motivi per aggirarlo.

5. conclusione

In questo tutorial, abbiamo imparato come modificare la pagina di accesso predefinita per Keycloak e aggiungere le nostre personalizzazioni .

Lo abbiamo visto sia per un'istanza autonoma che incorporata.

Infine, abbiamo esaminato brevemente come bypassare completamente la pagina di accesso di Keycloak e perché non farlo.

Come sempre, il codice sorgente è disponibile su GitHub. Per il server autonomo, si trova sui tutorial GitHub e, per l'istanza incorporata, su OAuth GitHub.