Thèmes, parcours et accessibilité

La page de connexion est souvent la seule page de Keycloak que voient les usagers. Elle porte la charte, le parcours MFA et une bonne part de l’accessibilité du service. Ce cours présente les mécanismes de thème de Keycloak, ce qu’un thème par client permet sans créer de realm, les deux outils qui reviennent le plus souvent (Keycloakify et le thème DSFR communautaire) et les points RGAA propres aux pages d’authentification.

Les types de thèmes

Keycloak distingue cinq types de thèmes :

Type	Ce qu’il habille	Qui le voit	Technologie
login	Connexion, enrôlement MFA, mot de passe oublié, required actions	Tous les usagers	Gabarits FreeMarker côté serveur
email	Vérification d’e-mail, réinitialisation, alertes	Tous les usagers	Gabarits FreeMarker (HTML et texte)
account	Console de compte (profil, mots de passe, appareils)	Usagers qui gèrent leur compte	Application React
admin	Console d’administration	Administrateurs	Application React
welcome	Page d’accueil du serveur	Personne, en pratique	Option serveur

Le thème se choisit par realm, dans Realm settings, onglet Themes. Les thèmes fournis avec le produit (base, keycloak et leurs déclinaisons récentes) changent de nom au fil des versions : consultez la liste proposée par votre console plutôt que de la supposer.

Un thème est un dossier qui contient des gabarits, des feuilles de style, des messages traduits et un fichier theme.properties :

parent=keycloak
import=common/keycloak
styles=css/login.css css/charte.css
locales=fr,en

Ici, le thème hérite du thème de connexion keycloak, garde sa feuille login.css et y ajoute charte.css. Avec un parent plus récent, vérifiez les noms de feuilles de style qu’il déclare.

L’héritage (parent) est la clé de la maintenance : on ne surcharge que ce qui change, le reste vient du thème parent et suit les montées de version. En production, les thèmes se livrent dans un JAR déposé dans providers/, avec un descripteur :

{
  "themes": [
    { "name": "charte", "types": ["login", "email"] }
  ]
}

Ce fichier se place dans META-INF/keycloak-themes.json. En développement, désactivez les caches de thème (--spi-theme--cache-themes=false, --spi-theme--cache-templates=false, --spi-theme--static-max-age=-1) pour voir vos modifications sans redémarrer. Réactivez-les en production.

Un thème par client, sans créer de realm

Chaque client peut surcharger le thème de connexion du realm (onglet Settings du client, section Login settings, champ Login theme). Les e-mails, la console de compte et la console d’administration restent ceux du realm.

C’est ce qui permet de garder un seul realm, donc le SSO, tout en donnant une page de connexion propre à une application. Trois niveaux de personnalisation existent, du moins au plus coûteux :

1. Une variante dans le thème commun. Le gabarit lit l’identifiant du client et ajuste le logo ou un texte. Un seul artefact à maintenir.
2. Un thème enfant par application. Il hérite du thème commun et ne surcharge que quelques ressources. Coût modéré, autant de thèmes à tester à chaque version.
3. Un thème indépendant. Gabarits réécrits, aucune mise en commun. Coût élevé, à réserver à une contrainte forte.

Pour une logique plus fine que le choix par client (selon un paramètre de la requête, par exemple), il existe le Theme Selector SPI : c’est une extension Java.

Keycloakify : écrire les thèmes en React

Keycloakify est un projet open source, hors du produit Keycloak, qui permet d’écrire les thèmes avec React et Vite au lieu de FreeMarker. Il produit un JAR de thème standard, que Keycloak charge comme n’importe quel autre. Sa documentation couvre les thèmes login, account, email et admin, avec une compatibilité annoncée sur de nombreuses versions de Keycloak.

Ce qu’il apporte :

• les compétences front habituelles (composants, TypeScript, Storybook pour voir chaque page sans Keycloak) ;
• un objet kcContext typé, qui expose ce que Keycloak transmet à la page (page courante, client, messages, champs du user profile) ;
• la possibilité de ne réécrire que certaines pages et de laisser les autres au rendu par défaut.

Une variante par client devient une simple condition :

export default function Template(props: TemplateProps<KcContext, I18n>) {
    const { kcContext, children } = props;
    const logo = kcContext.client.clientId === "portail-agents"
        ? "/logos/agents.svg"
        : "/logos/commun.svg";
    return (
        <main lang={kcContext.locale?.currentLanguageTag ?? "fr"}>
            <img src={logo} alt="Accueil du service" />
            {children}
        </main>
    );
}

Cet extrait est schématique : les noms exacts suivent la version de Keycloakify utilisée. Ce qu’il coûte : une équipe à l’aise avec React, un outillage de build (Node et Maven pour le JAR), et le suivi des versions de Keycloakify en plus de celles de Keycloak.

Le thème DSFR communautaire

Le dépôt codegouvfr/keycloak-theme-dsfr fournit un thème Keycloak au Système de design de l’État (DSFR), construit avec Keycloakify et la bibliothèque react-dsfr. Points vérifiés dans le dépôt :

• il couvre les pages de connexion et la console de compte (en version multipage) ; le dépôt ne montre pas de thème e-mail ;
• il est publié sous forme de JAR par tranche de versions de Keycloak, dont une pour 26.2 et suivantes ;
• il se configure sans recompilation par variables d’environnement (DSFR_THEME_HOME_URL, DSFR_THEME_SERVICE_TITLE, DSFR_THEME_SERVICE_TAG_LINE, DSFR_NOTICE_TITLE…) ;
• il est utilisé en production par le catalogue SILL de code.gouv.fr.

À évaluer avant de l’adopter :

Critère	Question à poser
Éligibilité	Le service a-t-il le droit d’utiliser le DSFR ? Son usage est réservé aux sites de l’État.
Couverture	Les pages utiles (OTP, WebAuthn, required actions, organisations) sont-elles toutes stylées ?
Maintenance	Le rythme des versions suit-il celui de Keycloak ? Qui corrige en cas de régression ?
Personnalisation	Les variables suffisent-elles, ou faudra-t-il forker le dépôt ? Un fork transfère toute la maintenance.
Hébergement	L’hébergeur accepte-t-il ce JAR et ces variables d’environnement ?

Accessibilité des pages de connexion

Pour un service public, les pages de connexion font partie du périmètre du RGAA (référentiel général d’amélioration de l’accessibilité). Elles concentrent des difficultés connues :

• Langue et titre. Attribut lang correct, titre de page qui change selon l’étape (« Saisie du code de vérification » plutôt qu’un titre unique).
• Formulaires. Chaque champ a une étiquette visible et associée. Les erreurs sont reliées au champ concerné et annoncées aux lecteurs d’écran, pas seulement colorées en rouge.
• Facteurs d’authentification. Le champ OTP accepte le collage et l’autocomplétion (autocomplete="one-time-code"). Un utilisateur qui ne peut pas employer une clé FIDO2 doit disposer d’une alternative.
• Délais. La page de connexion expire (message « action expirée ») : c’est une limite de temps au sens du RGAA, à documenter ou à rendre ajustable.
• Affichage. Zoom à 200 %, affichage sur écran étroit, contrastes, focus visible, navigation complète au clavier.
• CAPTCHA. S’il en faut un, il doit offrir une alternative accessible.

Ni Keycloak ni un thème communautaire ne garantissent la conformité : elle se mesure par un audit sur les pages réellement servies, avec les messages et les parcours configurés. Prévoyez ces pages dans la grille d’audit et dans la déclaration d’accessibilité du service.

Thème par client et contrôle d'accessibilité

30 min

Installer le lab

1. Dans le realm approfondir (créez-le si besoin), ouvrez Realm settings, onglet Themes, et notez les thèmes de connexion proposés par votre version. Choisissez-en un pour le realm et enregistrez.

2. Ouvrez le client account-console, onglet Settings, section Login settings. Choisissez un autre thème de connexion que celui du realm et enregistrez.

3. En fenêtre privée, ouvrez http://localhost:8080/realms/approfondir/account : la page utilise le thème du client. Ouvrez ensuite http://localhost:8080/admin/approfondir/console/ : la page utilise le thème du realm. Vous avez deux rendus dans le même realm, avec le même SSO.

4. Sur la page de connexion, débranchez la souris : atteignez chaque champ et le bouton avec Tab, soumettez avec Entrée. Notez si le focus reste visible.

5. Saisissez un mauvais mot de passe. Dans les outils de développement du navigateur (panneau Accessibilité), vérifiez si le message d’erreur est relié au champ et si l’attribut lang de la page est correct.

6. Zoomez à 200 % et réduisez la fenêtre à environ 320 pixels de large : vérifiez qu’aucune information n’est tronquée.

7. Facultatif : téléchargez depuis les releases du dépôt codegouvfr/keycloak-theme-dsfr le JAR prévu pour votre version de Keycloak, copiez-le dans le conteneur et redémarrez-le. Choisissez ensuite DSFR comme thème de connexion du client et refaites les contrôles 4 à 6.

   cd keycloak-academy-lab
   docker compose cp keycloak-theme-for-kc-26.2-and-above.jar keycloak:/opt/keycloak/providers/
   docker compose restart keycloak

À retenir pour l’architecture

Un seul thème de socle, hérité d’un thème fourni, avec des variantes par client quand une application le justifie : c’est le modèle le moins coûteux. Le thème DSFR communautaire est un bon point de départ pour un service de l’État, à condition d’en évaluer la couverture et la maintenance, et de vérifier que l’hébergeur accepte son déploiement. L’accessibilité des pages de connexion se prouve par audit, pas par le choix d’un thème.