Aller au contenu

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.

GuideDéveloppeur
Durée
30 min
Voir en Markdown

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), fichier theme.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).

Texte
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.properties

Chaque 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 :

properties
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.css

Attention

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 :

CSS
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 :

Texte
mon-theme.jar
└── theme/
    └── marque/
        └── login/
            ├── theme.properties
            └── resources/css/marque.css
Bash
mkdir -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

ContrainteValeur
Taille de l'archive50 Mo au plus
Taille une fois décompressée50 Mo au plus
Nombre de fichiers5 000 au plus
Thèmes par archiveun 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.properties de 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.

Voir aussi