Préparer un thème de connexion
Structurer le dossier keycloak-theme/ dans un dépôt GitHub de votre application, ou empaqueter un .jar, en respectant les contraintes de Wakastart.
- Durée
- 30 min
Un thème de connexion est un thème Keycloak standard. Wakastart lui impose seulement un emplacement, une structure et quelques limites, pour pouvoir le nommer et le déployer sans intervention manuelle.
Avant de commencer
- Le dépôt qui portera le thème est rattaché à une définition de service de votre application et hébergé sur GitHub. Les autres hébergeurs ne sont pas pris en charge pour l'import : utilisez alors un fichier
.jar. - Vous connaissez le format des thèmes Keycloak : gabarits FreeMarker (
.ftl), fichiertheme.properties, ressources CSS et images. Voir la documentation Keycloak, chapitre « Themes ».
Créer le dossier du thème
Créez un dossier keycloak-theme/ à la racine du dépôt. Si le dépôt est un monorepo, placez-le dans le répertoire racine du service (le root directory de sa définition de service).
keycloak-theme/
├── login/
│ ├── theme.properties
│ ├── login.ftl (facultatif : seulement les gabarits que vous modifiez)
│ └── resources/
│ ├── css/marque.css
│ └── img/logo.png
└── email/ (facultatif)
├── theme.properties
└── messages/messages_fr.propertiesChaque sous-dossier porte un type reconnu : login, email, account, admin ou welcome. Il en faut au moins un.
Écrire le fichier theme.properties
Héritez d'un thème fourni par Keycloak et ajoutez votre feuille de style :
parent=keycloak.v2
# Recopiez la valeur « styles » du thème parent, puis ajoutez votre fichier à la fin
styles=<styles du thème parent> css/marque.cssAttention
La propriété styles remplace la liste du thème parent, elle ne s'y ajoute pas. Si vous déclarez seulement styles=css/marque.css, la page de connexion perd tous les styles de Keycloak et s'affiche nue. Recopiez la liste styles du theme.properties du thème parent dans votre version de Keycloak, puis ajoutez votre fichier en dernier : l'ordre fixe la priorité.
Ne faites jamais référence à votre propre thème dans parent= ou import= : Wakastart renomme le thème à l'empaquetage, et la référence serait rompue. Utilisez un thème de base comme base, keycloak ou keycloak.v2.
Ajouter un repère visuel pour vos tests
Pendant la mise au point, un bandeau qui ne dépend d'aucun sélecteur interne à Keycloak vous dit, d'un coup d'œil, quelle version est affichée :
body::before {
content: "Thème marque — v3";
position: fixed; top: 0; left: 0; right: 0; z-index: 9999;
padding: 6px 12px; text-align: center;
font: 700 14px/1.4 ui-monospace, monospace;
background: #111; color: #f5c400;
}Retirez-le avant de publier en production.
Empaqueter un .jar (alternative)
Si vous ne passez pas par GitHub, construisez une archive .jar dont la racine contient un dossier theme/ avec un seul thème :
mon-theme.jar
└── theme/
└── marque/
└── login/
├── theme.properties
└── resources/css/marque.cssmkdir -p build/theme/marque
cp -R keycloak-theme/* build/theme/marque/
(cd build && zip -r ../mon-theme.jar theme)Le nom du dossier (marque) est libre : Wakastart le remplace par le nom de version.
Respecter les limites
| Contrainte | Valeur |
|---|---|
| Taille de l'archive | 50 Mo au plus |
| Taille une fois décompressée | 50 Mo au plus |
| Nombre de fichiers | 5 000 au plus |
| Thèmes par archive | un seul, sous theme/ |
| Compression | « stored » ou « deflate » ; pas d'entrée chiffrée |
Vérifier le résultat
- Le dossier
keycloak-theme/est poussé sur la branche que vous voulez faire importer. - Le fichier
theme.propertiesde chaque type hérite d'un thème de base et ne cite pas votre propre thème. - Votre feuille de style est la dernière de la liste
styles.