Keycloak: Personnaliser l'apparence

Personnalisez facilement les pages de connexion, la console de compte et les e-mails de Keycloak sur Stackhero : définissez vos couleurs, votre logo, vos textes, et créez même des thèmes entièrement personnalisés grâce à l'éditeur en ligne intégré.

👋 Bienvenue sur la documentation de Stackhero !

Stackhero propose un service Keycloak cloud qui simplifie le déploiement d'un fournisseur d'identité prêt pour la production en seulement 2 minutes :

• Utilisateurs, realms et clients en nombre illimité
• Prise en charge de OpenID Connect, OAuth 2.0, SAML 2.0, connexion via réseaux sociaux, fédération LDAP et Active Directory
• Nom de domaine personnalisé avec HTTPS intégré pour un accès sécurisé (par exemple, https://login.votre-entreprise.com)
• Thèmes personnalisés : personnalisez facilement vos pages de connexion, la console de compte et les e-mails grâce à un éditeur en ligne inclus
• Serveur e-mail dédié avec SPF, DKIM et DMARC, pour que les confirmations de compte et réinitialisations de mot de passe soient gérées automatiquement
• Base de données PostgreSQL intégrée, avec la console d'administration accessible sur un port dédié et désactivable
• Mises à jour en un clic pour garder votre système à jour sans intervention manuelle

Consacrez votre temps au développement, pas à la configuration : vous pouvez tester la solution Keycloak cloud de Stackhero en moins de 5 minutes.

Personnaliser l'apparence de votre Keycloak

La page de connexion est l'un des premiers éléments vus par vos utilisateurs. Avec Stackhero, vous pouvez la personnaliser en quelques minutes : choisissez vos couleurs, votre logo et vos textes pour chaque langue prise en charge. La même approche s'applique aux e-mails envoyés par Keycloak.

Deux outils principaux sont inclus avec votre service :

• L'éditeur de thèmes, un éditeur de fichiers en ligne où se trouve votre thème.
• Quick Theme, le concepteur visuel de thèmes intégré à la console d'administration Keycloak, pour choisir vos couleurs et votre branding sans modifier le CSS.

Aucune connexion SSH, recompilation ou redéploiement n'est nécessaire.

Accéder à l'éditeur de thèmes

La page de votre service sur le tableau de bord Stackhero propose une URL Themes editor à côté de votre console d'administration :

https://your-domain.com:4443/stackhero_themes/

Connectez-vous avec vos identifiants administrateur Keycloak : les mêmes que pour la console d'administration.

Voici deux points importants à retenir :

• L'éditeur fonctionne sur le port d'administration, différent de celui utilisé par vos applications. Si vous fermez ce port dans le pare-feu Stackhero, la console d'administration et l'éditeur deviennent inaccessibles. Vos applications continuent à s'authentifier normalement.
• Toutes vos modifications sont enregistrées sur le disque de votre service, incluses dans vos sauvegardes, et persistent après redémarrage ou mise à jour.

Vous trouverez deux répertoires :

Chaque répertoire contient un fichier README.md avec une documentation à jour correspondant à la version de votre service.

Votre thème est prêt à être modifié

Ouvrez themes/ et vous trouverez un dossier default/. Il s'agit de votre thème actif, déjà utilisé par votre instance Keycloak. Il n'y a rien à sélectionner : modifiez simplement ses fichiers et voyez vos changements appliqués immédiatement.

Aucune connaissance préalable des thèmes Keycloak n'est requise. Chaque fichier contient déjà les paramètres courants à personnaliser, avec la valeur actuelle de Keycloak indiquée en exemple commenté. Pour modifier une valeur, retirez le caractère de commentaire, ajustez la valeur, puis enregistrez.

Si une ligne reste commentée, Keycloak utilise sa valeur par défaut. Cela garantit que votre service reste conforme au comportement standard de Keycloak, même après une mise à jour.

Mettre à jour votre logo

Ouvrez default/login/resources/img/. Vous y trouverez les deux images actuellement utilisées sur votre page de connexion. Téléversez votre propre logo en utilisant le même nom de fichier, keycloak-logo-text.svg, puis actualisez la page de connexion avec Ctrl+F5 (Cmd+Shift+R sur macOS).

C'est tout ce qu'il y a à faire. Inutile de modifier d'autres fichiers ou de redémarrer votre service : la mise à jour est appliquée dès l'enregistrement. Pour changer l'image de fond, remplacez keycloak-bg-darken.svg dans le même dossier.

Si vous souhaitez utiliser d'autres noms de fichiers, vous pouvez modifier les références dans default/login/resources/css/stackhero.css dans la section "Your logo".

Définir vos couleurs

Dans stackhero.css, vous trouverez des variables déjà renseignées avec leurs valeurs actuelles :

:root {
  /* ---------- Colors ---------- */
  /* The buttons */
  /* --pf-v5-global--primary-color--100: #06c; */
  /* The buttons, while hovered */
  /* --pf-v5-global--primary-color--200: #004080; */
  /* The links */
  /* --pf-v5-global--link--Color: #06c; */
  /* The colored line on top of the login box */
  /* --keycloak-card-top-color: #06c; */

Pour appliquer une modification, retirez les marques de commentaire, définissez votre couleur, enregistrez et rechargez la page. C'est tout.

Pendant vos modifications : Votre navigateur met en cache le CSS, les images et les scripts du thème pendant une heure. Lors de vos tests, rechargez toujours avec Ctrl+F5 pour voir vos derniers changements. Vos visiteurs verront la mise à jour dans l'heure qui suit.

Vous avez un contrôle total : le fichier est du CSS standard et se charge en dernier, ce qui vous permet de surcharger n'importe quel style. Utilisez les DevTools de votre navigateur (F12) pour inspecter les éléments. Keycloak 26 utilise le PatternFly design system, la plupart des variables de couleur sont nommées --pf-v5-global--* et peuvent être redéfinies dans :root.

Définir le nom de votre entreprise

Aucune modification de thème n'est nécessaire pour cela. Dans la console d'administration, ouvrez Realm settings > General et renseignez le Display name. Ce nom s'affichera sur les pages de connexion et dans les e-mails.

Modifier les textes, en plusieurs langues

Vous pouvez modifier les textes sans toucher au CSS ou au HTML. Dans default/login/messages/messages_en.properties, vous trouverez tous les textes du formulaire de connexion avec leur libellé par défaut. Pour modifier une ligne, retirez le #, saisissez votre texte, puis enregistrez :

loginAccountTitle=Sign in to Acme
doLogIn=Sign in
doForgotPassword=I forgot my password

Ajoutez des fichiers comme messages_fr.properties pour le français ou messages_de.properties pour l'allemand, puis activez ces langues dans la console d'administration, section Realm settings > Localization.

Astuce : L'onglet Localization propose aussi une section Realm overrides qui permet de modifier les textes directement dans la console, sans éditer de fichier ni redémarrer. Utilisez la méthode qui correspond le mieux à votre organisation.

Personnaliser vos e-mails

Keycloak envoie des e-mails pour la confirmation d'adresse, la réinitialisation de mot de passe et les invitations utilisateurs. Dans default/email/messages/messages_en.properties, vous trouverez les sujets et messages standards prêts à être adaptés :

emailVerificationSubject=Confirm your Acme account
passwordResetSubject=Reset your Acme password

Lorsque vous modifiez le contenu des e-mails, gardez à l'esprit :

• Conservez les placeholders {0}, {1}, {2} (Keycloak les remplacera par le lien, le nom affiché et le délai).
• Pour échapper une apostrophe, écrivez-la en double (don''t).

Pour personnaliser le HTML des e-mails, copiez le modèle souhaité depuis le Keycloak base email theme dans default/email/html/, puis modifiez votre copie.

Stackhero configure l'envoi des e-mails pour vous avec SPF, DKIM et DMARC déjà en place. Configurez-le dans Realm settings > Email en utilisant l'hôte et le port indiqués sur la page de votre service.

Si vous devez réinitialiser votre thème

En cas de problème, vous pouvez supprimer entièrement le dossier default puis redémarrer votre service. Stackhero recréera un thème par défaut, restaurant ainsi l'apparence standard de Keycloak.

Vos realms, utilisateurs et clients sont stockés dans votre base de données et ne sont pas affectés.

Concevez votre thème visuellement avec Quick Theme

Dans la console d'administration Keycloak, vous trouverez Quick Theme, le concepteur visuel de thèmes Keycloak. Téléversez un logo, choisissez vos couleurs, prévisualisez vos pages de connexion et de compte, puis téléchargez le thème finalisé au format .jar.

Pour l'installer, placez le fichier dans le dossier themes/ via l'éditeur, puis redémarrez votre service. Le .jar est décompressé dans un dossier de thème et l'archive est supprimée :

themes/acme.jar        devient     themes/acme/

Le nouveau thème apparaîtra dans Realm settings > Themes. Vous pouvez continuer à modifier ses fichiers manuellement si vous le souhaitez.

Cette méthode prend aussi en charge les thèmes créés avec Keycloakify ou fournis par un designer. Tout fichier .jar ou .zip contenant un thème peut être installé de cette façon. Si un thème du même nom existe déjà, le nouveau sera installé sous le nom acme-1, garantissant que vos envois n'écrasent jamais votre travail. Si le fichier n'est pas un thème, il est simplement ignoré et Keycloak démarre normalement.

Une marque par realm : support du white-label

Les thèmes sont sélectionnés par realm dans Realm settings > Themes, avec des options pour chaque type de page : connexion, compte, admin et e-mail. Chaque application peut aussi définir son propre thème de connexion dans ses paramètres client.

Si vous gérez plusieurs marques ou proposez des solutions en marque blanche, utilisez un realm par marque et attribuez un thème personnalisé à chacun :

1. Dans l'éditeur, copiez le dossier default et renommez la copie (par exemple, acme).
2. Redémarrez votre service.
3. Dans la console d'administration, ouvrez le realm concerné et sélectionnez acme comme thème de connexion.

Tout realm non configuré continuera à utiliser votre thème default.

Comprendre la structure d'un thème Keycloak

Un thème est un dossier contenant des sous-dossiers pour chaque type de page :

themes/
  acme/
    login/                             # Pages de connexion utilisateur
      theme.properties                 # Héritage du thème et inclusion CSS
      resources/css/stackhero.css      # Votre CSS
      resources/img/logo.svg           # Vos images
      messages/messages_en.properties  # Vos textes
    account/                           # Gestion du profil utilisateur
    admin/                             # Apparence de la console d'administration
    email/                             # Modèles d'e-mails

Les thèmes héritent des thèmes standards de Keycloak, en ne surchargeant que ce qui est nécessaire. Un fichier login/theme.properties typique ressemble à ceci :

parent=keycloak.v2
styles=css/styles.css css/stackhero.css

• parent définit le thème de base.
• styles liste les fichiers CSS à charger. Placez votre CSS en dernier pour garantir que vos modifications s'appliquent.

La liste styles remplace celle du thème parent, elle ne l'étend pas. Pensez à inclure la feuille de style du parent (css/styles.css) sinon votre page perdra son style par défaut.

Vous n'avez besoin de templates FreeMarker (.ftl) que si vous souhaitez modifier la structure HTML. Pour les couleurs, logos, fonds, textes et langues, aucune modification de template n'est nécessaire. Pour plus de détails, consultez la documentation Keycloak sur les thèmes.

Extensions Java (providers)

Le dossier providers/ est destiné aux fonctionnalités non couvertes par les thèmes : authenticators personnalisés, stockage utilisateur, listeners d'événements ou protocol mappers.

Placez votre fichier .jar dans ce dossier puis redémarrez votre service. Ce redémarrage prend un peu plus de temps (environ une minute) car Keycloak se reconstruit pour inclure la nouvelle extension. Pour supprimer une extension, supprimez le fichier et redémarrez à nouveau.

Vous pouvez aussi placer des fichiers .jar de thème ici, mais il est préférable d'utiliser themes/ pour les thèmes : cela ne nécessite pas de reconstruction et vous permet de modifier les fichiers par la suite.