Personnalisation de la page de connexion pour Keycloak

1. Vue d'ensemble

Keycloak est un serveur d'autorisation tiers utilisé pour gérer les exigences d'authentification et d'autorisation de nos applications Web ou mobiles. Il utilise une page de connexion par défaut pour connecter les utilisateurs au nom de notre application.

Dans ce didacticiel, nous allons nous concentrer sur la façon dont nous pouvons personnaliser la page de connexion de notre serveur Keycloak afin que nous puissions avoir une apparence et une convivialité différentes. Nous verrons cela pour les serveurs autonomes et intégrés.

Nous allons construire en plus de la personnalisation des thèmes pour le didacticiel Keycloak pour ce faire.

2. Personnalisation d'un serveur Keycloak autonome

En continuant avec notre exemple du thème personnalisé , voyons d'abord le serveur autonome.

2.1. Paramètres de la console d'administration

Pour démarrer le serveur, naviguons vers le répertoire où se trouve notre distribution Keycloak et exécutons cette commande à partir de son dossier bin :

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

Une fois le serveur démarré, il suffit de rafraîchir la page pour voir nos modifications reflétées, grâce aux modifications que nous avons précédemment apportées au fichier standalone.xml .

Créons maintenant un nouveau dossier, nommé login , dans le répertoire themes / custom . Pour garder les choses simples, nous allons d'abord copier tout le contenu du répertoire themes / keycloak / login ici. Il s'agit du thème de la page de connexion par défaut.

Ensuite, nous allons accéder à la console d'administration, saisir les informations d'identification initiales1 / zaq1! QAZ et accéder à l' onglet Thèmes de notre royaume:

Nous sélectionnerons personnalisé pour le thème de connexion et enregistrerons nos modifications.

Avec cet ensemble, nous pouvons maintenant essayer quelques personnalisations. Mais avant cela, jetons un œil à la page de connexion par défaut:

2.2. Ajout de personnalisations

Disons maintenant que nous devons changer l'arrière-plan. Pour cela, nous allons ouvrir login / resources / css / login.css et changer la définition de la classe:

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

Pour voir l'effet, rafraîchissons la page:

Ensuite, essayons de changer les étiquettes du nom d'utilisateur et du mot de passe.

Pour y parvenir, nous devons créer un nouveau fichier, messages_en.properties dans le dossier theme / login / messages . Ce fichier remplace le groupe de messages par défaut utilisé pour les propriétés données:

usernameOrEmail=Enter Username: password=Enter Password:

Pour tester, actualisez à nouveau la page:

Supposons que nous souhaitons modifier le code HTML entier ou une partie de celui-ci, nous devrons remplacer les modèles de marqueurs libres que Keycloak utilise par défaut. Les modèles par défaut de la page de connexion sont conservés dans le répertoire base / login .

Disons que nous voulons que WELCOME TO BAELDUNG soit affiché à la place de SPRINGBOOTKEYCLOAK .

Pour cela, nous devrons copier base / login / template.ftl dans notre dossier custom / login .

Dans le fichier copié, modifiez la ligne:

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

À:

 WELCOME TO BAELDUNG 

La page de connexion afficherait maintenant notre message personnalisé au lieu du nom du domaine.

3. Personnalisation d'un serveur Keycloak intégré

La première étape ici consiste à ajouter tous les artefacts que nous avons modifiés pour le serveur autonome au code source de notre serveur d'autorisation intégré.

Alors, créons une nouvelle connexion de dossier dans src / main / resources / themes / custom avec ce contenu:

Maintenant, tout ce que nous devons faire est d'ajouter des instructions dans notre fichier de définition de domaine, baeldung-realm.json afin que custom soit utilisé pour notre type de thème de connexion:

"loginTheme": "custom",

Nous avons déjà redirigé vers le répertoire de thème personnalisé afin que notre serveur sache d'où récupérer les fichiers de thème pour la page de connexion.

Pour les tests, frappons la page de connexion:

Comme nous pouvons le voir, toutes les personnalisations effectuées précédemment pour le serveur autonome, telles que l'arrière-plan, les noms d'étiquettes et le titre de page, apparaissent ici.

4. Contournement de la page de connexion Keycloak

Techniquement, nous pouvons contourner complètement la page de connexion Keycloak en utilisant le mot de passe ou le flux d'octroi d'accès direct. Cependant, il est fortement recommandé de ne pas utiliser du tout ce type de subvention.

Dans ce cas, il n'y a pas d'étape intermédiaire pour obtenir un code d'autorisation, puis recevoir le jeton d'accès en échange. Au lieu de cela, nous pouvons envoyer directement les informations d'identification de l'utilisateur via un appel d'API REST et obtenir le jeton d'accès en réponse.

Cela signifie effectivement que nous pouvons utiliser notre page de connexion pour collecter l'identifiant et le mot de passe de l'utilisateur, et avec l'identifiant et le secret du client, l'envoyer à Keycloak dans un POST vers son point de terminaison de jeton .

Mais encore une fois, étant donné que Keycloak fournit un ensemble d'options de connexion riche en fonctionnalités - telles que se souvenir de moi, réinitialisation de mot de passe et MFA - pour n'en nommer que quelques-uns, il y a peu de raisons de le contourner.

5. Conclusion

Dans ce didacticiel, nous avons appris à modifier la page de connexion par défaut pour Keycloak et à ajouter nos personnalisations .

Nous avons vu cela à la fois pour une instance autonome et intégrée.

Enfin, nous avons brièvement expliqué comment contourner complètement la page de connexion de Keycloak et pourquoi ne pas le faire.

Comme toujours, le code source est disponible à l'adresse over sur GitHub. Pour le serveur autonome, il se trouve sur les tutoriels GitHub et pour l'instance intégrée, sur OAuth GitHub.