Thème d'un royaume : une autre apparence pour la connexion et le compte

Les pages de connexion (/auth/) et l’espace compte (/account/) lisent au chargement un fichier, auth/themes/themes.json. Pour chaque royaume, il peut donner une feuille de style, un logo, un nom et une ligne de copyright. Une seule feuille habille tout le parcours, de la connexion à l’espace compte, et il n’y a rien à recompiler ni à redémarrer.

Ce tutoriel installe l’exemple Université des Sciences, puis montre comment sa feuille est construite pour que vous puissiez l’adapter à votre établissement. L’exemple ne change pas seulement les couleurs : la page de connexion perd sa carte et montre un campus dessiné, et le menu latéral du compte devient une barre d’onglets.

Étape 1 : télécharger l’exemple#

Téléchargez theme-universite.zip (50 Ko). Il contient :

Tout est local : la page ne charge rien depuis un autre site, pas même la police.

Étape 2 : copier le thème dans TOSIAM#

Les thèmes vivent dans le dossier auth/themes/ de l’application déployée. Avec la QuickStart, c’est apache-tomcat-11.0.14/webapps/tosiam/auth/themes/ :

cd ~/tosiam-quickstart-3.38.0/apache-tomcat-11.0.14/webapps/tosiam/auth/themes
unzip -o ~/Téléchargements/theme-universite.zip

Étape 3 : déclarer le thème#

Voici le themes.json de l’archive :

{
  "default": {},
  "realms": {
    "/": {
      "stylesheet": "universite/theme.css",
      "logo": { "light": "universite/logo.svg", "dark": "universite/logo-dark.svg", "alt": "Université des Sciences" },
      "name": { "fr": "Espace étudiant", "en": "Student portal" },
      "layout": "card",
      "theme": "auto",
      "copyright": "Copyright © 2026 Université des Sciences. Tous droits réservés."
    }
  }
}

Chaque clé de realms est le chemin d’un royaume. / est le royaume racine ; un royaume sans entrée prend celle de son parent le plus proche, donc / habille aussi tous les royaumes qui n’ont pas la leur. Pour n’habiller qu’un royaume, utilisez son chemin, par exemple "/ref". default donne les valeurs communes à toutes les entrées.

Le fichier est relu à chaque chargement de page : il n’y a pas de cache à vider dans TOSIAM. Tomcat peut servir l’ancienne version quelques secondes après une modification.

Étape 4 : voir le résultat#

Ouvrez http://localhost:8080/tosiam/auth/. La connexion est maintenant une page à part entière : le logo et le nom de l’espace dans la barre du haut (1), le formulaire posé sur la page, sans carte, avec un grand titre (2), le bouton principal aux couleurs de l’université (3) et, à droite, le campus. À côté de la langue, le bouton de thème (4) reprend le style du thème sans rien ajouter à la feuille.

1 2 3 4

Connectez-vous : l’espace compte suit le même thème, avec l’en-tête sombre et son logo clair (1), et le menu devenu une barre d’onglets (2).

1 2

Pour voir l’autre version, choisissez « Sombre » ou « Clair » avec le bouton de thème (4) : chaque couleur du thème a ses deux valeurs. Le choix est gardé dans le navigateur, le même pour la connexion et l’espace compte ; « Appareil » revient au réglage de l’appareil. Les captures de cette page suivent d’ailleurs le thème du site.

Comment la feuille est construite#

Ouvrez universite/theme.css. Elle se lit en quatre parties.

1. Une portée : :root[data-realm]#

Les deux applications posent le royaume courant sur l’élément racine (data-realm="root" pour le royaume racine, data-realm="ref" pour /ref), et ne chargent la feuille que pour les royaumes qui la déclarent. Toute la feuille est donc imbriquée sous :root[data-realm] : cela suffit à la limiter à ces royaumes, et ce sélecteur l’emporte sur les valeurs par défaut de TOSIAM.

2. La palette, puis les jetons de TOSIAM#

La feuille définit d’abord la palette de l’université (--hz-*), puis y fait pointer les jetons de TOSIAM (--tos-*) que les deux applications utilisent pour tout dessiner :

:root[data-realm] {
  --hz-surface:  light-dark(#FFFFFF, #202734);
  --hz-ink:      light-dark(#202734, #E0F8C7);
  --hz-primary:  light-dark(#36415A, #B7D894);

  --tos-surface: var(--hz-surface);
  --tos-text:    var(--hz-ink);
  --tos-accent:  var(--hz-primary);
  --tos-font-sans: "Atkinson Hyperlegible Next", system-ui, sans-serif;
  --tos-radius-md: 10px;
}

Chaque couleur est une paire light-dark(clair, sombre) : le navigateur choisit selon le choix de l’utilisateur, sinon selon theme dans themes.json, sinon selon le thème de l’appareil. Les jetons les plus utiles :

Changez aussi les couleurs d’état : le rouge par défaut de TOSIAM jure vite avec une autre palette. L’exemple prend un rouge brique, un ocre et un bleu ardoise de la même famille que ses couleurs, chacun avec au moins 4,5:1 de contraste sur la page et sur sa teinte claire. En sombre, le texte posé sur ces couleurs est foncé, pas blanc.

3. La mise en page#

Aucune des deux applications n’enferme ses composants dans un shadow DOM : la feuille atteint chaque élément par sa classe, et peut donc changer la mise en page, pas seulement les couleurs. La page de connexion « sans carte » tient en quelques règles :

:root[data-realm] {
  --hz-login-split: 52%;
  --hz-login-art: url("login-art.svg");

  .tos-cardlogo, .tos-circuit { display: none; }
  .tos-column { position: relative; }
  /* le campus, à droite du formulaire, sous la barre du haut */
  .tos-column::after { content: ""; position: absolute; top: 64px; right: 0; bottom: 0; left: var(--hz-login-split);
    background: var(--hz-login-art) center / cover no-repeat; }
  .tos-main, .tos-footer { margin-right: calc(100% - var(--hz-login-split)); }
  .tos-shell[data-layout] .tos-card { max-width: 400px; padding: 0; background: transparent; box-shadow: none; }
}

La barre d’onglets du compte ne s’applique qu’au-dessus de 860 px (@media (min-width: 861px)) : en dessous, le compte garde son tiroir de menu, pensé pour le téléphone. Gardez cette règle si vous remodelez le compte.

4. Les images et la police#

Une image n’est pas une couleur : light-dark() ne peut pas choisir entre deux fichiers. Le campus passe donc par une variable, changée pour le thème sombre :

:root[data-realm][data-theme="dark"] { --hz-login-art: url("login-art-dark.svg"); }
@media (prefers-color-scheme: dark) {
  :root[data-realm]:not([data-theme="light"]) { --hz-login-art: url("login-art-dark.svg"); }
}

Le logo, lui, a sa version sombre dans themes.json (logo.dark). Les adresses de la feuille (url(...)) sont relatives au dossier de la feuille, et la police est déclarée par un @font-face vers fonts/ : rien ne part vers un autre site.

Adapter l’exemple à votre établissement#

1. Copiez le dossier universite sous un autre nom et changez le chemin dans themes.json.
2. Remplacez les logos (SVG de préférence, environ 130 × 40) et le dessin, ou supprimez la règle .tos-column::after pour une page sans image.
3. Changez la palette --hz-* en haut de la feuille, en gardant deux valeurs par couleur, et vérifiez les contrastes : 4,5:1 pour le texte, 3:1 pour les contours de champs et l’anneau de focus.
4. Changez name et copyright.
5. Vérifiez la connexion, une erreur de mot de passe, l’espace compte et un téléphone, en clair et en sombre.

Garder le thème après un redémarrage#

Le dossier auth/themes/ fait partie de l’application déployée. Au démarrage, la QuickStart extrait de nouveau tosiam.war par-dessus webapps/tosiam/ : votre dossier universite/ reste, mais themes.json reprend la version du WAR, qui ne déclare aucun royaume. Recopiez votre themes.json après chaque démarrage, ou ajoutez le thème au WAR lui-même :

mkdir -p build/auth/themes
cp -r universite themes.json build/auth/themes/
cd build && zip -r ../tosiam.war auth/themes

Lancée à côté de votre tosiam.war, la commande y remplace auth/themes/themes.json et ajoute le dossier du thème ; déployez ensuite ce WAR comme d’habitude.

Limites#

• Le thème change l’apparence, pas le contenu : les textes, l’ordre des champs et les étapes de connexion viennent de TOSIAM et du graphe d’authentification.
• name est le même pour la connexion et le compte.
• La console d’administration (/console) ne lit pas themes.json.