Keycloak: Pas het uiterlijk aan

Brand eenvoudig uw Keycloak inlogpagina's, accountconsole en e-mails op Stackhero: stel uw kleuren, logo, teksten in en maak zelfs volledig aangepaste thema's met de ingebouwde online editor.

👋 Welkom bij de Stackhero-documentatie!

Stackhero biedt een Keycloak cloud dienst waarmee u in slechts 2 minuten een productieklare identity provider kunt uitrollen:

• Onbeperkt aantal gebruikers, realms en clients
• Ondersteunt OpenID Connect, OAuth 2.0, SAML 2.0, social login, LDAP en Active Directory-federatie
• Eigen domeinnaam met ingebouwde HTTPS voor veilige toegang (bijvoorbeeld https://login.uw-bedrijf.com)
• Aangepaste thema's: pas eenvoudig uw loginpagina's, accountconsole en e-mails aan met de meegeleverde online editor
• Toegewijde mailserver met SPF, DKIM en DMARC, zodat accountbevestigingen en wachtwoordresets automatisch voor u worden afgehandeld
• Ingebouwde PostgreSQL-database, met de beheerdersconsole beschikbaar op een eigen afsluitbare poort
• One-click updates houden uw systeem up-to-date zonder handmatige tussenkomst

Besteed uw tijd aan ontwikkelen, niet aan configureren: u kunt Stackhero's Keycloak cloudoplossing in minder dan 5 minuten uitproberen.

Pas het uiterlijk van uw Keycloak aan

Uw inlogpagina is een van de eerste dingen die uw gebruikers zien. Met Stackhero maakt u deze in enkele minuten helemaal eigen: stel uw kleuren, logo en teksten in voor elke ondersteunde taal. Dit geldt ook voor de e-mails die Keycloak verstuurt.

Er zijn twee hoofdtools, beide inbegrepen bij uw service:

• De themes editor, een online bestandseditor waarin uw thema zich bevindt.
• Quick Theme, de visuele themabouwer in uw Keycloak-beheerconsole, waarmee u kleuren en branding kiest zonder CSS te bewerken.

Geen SSH, geen rebuilds en geen redeploys nodig.

De themes editor openen

Op uw servicepagina in het Stackhero dashboard vindt u een Themes editor-URL naast uw beheerconsole:

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

Log in met uw Keycloak-beheerdersgegevens: dezelfde die u gebruikt voor de beheerconsole.

Let op de volgende twee punten:

• De editor draait op de beheerpoort, niet op de poort die uw applicaties gebruiken. Als u deze poort sluit in uw Stackhero-firewall, zijn zowel de beheerconsole als de editor niet meer bereikbaar. Uw applicaties blijven gewoon authenticeren.
• Alles wat u hier wijzigt, wordt opgeslagen op de schijf van uw service, zit in uw back-ups en blijft behouden bij herstarten en updates.

U vindt twee mappen:

Elke map bevat een README.md-bestand met actuele documentatie die past bij uw serviceversie.

Uw thema is klaar om te bewerken

Open themes/ en u vindt een default/-map. Dit is uw actieve thema, al in gebruik door uw Keycloak-instantie. U hoeft niets te selecteren: bewerk gewoon de bestanden en zie uw wijzigingen direct terug.

U hoeft geen voorkennis van Keycloak-thema's te hebben. Elk bestand bevat al veelgebruikte instellingen die u kunt aanpassen, met de huidige Keycloak-waarde als uitgecommentarieerd voorbeeld. Om een waarde te wijzigen, verwijdert u het commentaarteken, past u de waarde aan en slaat u op.

Als een regel uitgecommentarieerd blijft, gebruikt Keycloak de standaardwaarde. Zo blijft uw service altijd overeenkomen met het standaard Keycloak-gedrag, ook na updates.

Uw logo bijwerken

Open default/login/resources/img/. Hier ziet u de twee afbeeldingen die momenteel op uw inlogpagina worden gebruikt. Upload uw eigen logo met dezelfde bestandsnaam, keycloak-logo-text.svg, en ververs de inlogpagina met Ctrl+F5 (Cmd+Shift+R op macOS).

Dat is alles. U hoeft geen bestanden te bewerken of uw service te herstarten: de update wordt direct toegepast zodra u opslaat. Om de achtergrondafbeelding te wijzigen, vervangt u keycloak-bg-darken.svg in dezelfde map.

Wilt u andere bestandsnamen gebruiken, pas dan de verwijzingen aan in default/login/resources/css/stackhero.css onder het gedeelte "Your logo".

Uw kleuren instellen

In stackhero.css vindt u variabelen die al zijn ingevuld met hun huidige waarden:

: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; */

Om een wijziging toe te passen, verwijdert u de commentaartekens, stelt u uw kleur in, slaat u op en laadt u de pagina opnieuw. Dat is alles.

Tijdens het aanpassen: Uw browser cachet de thema-CSS, afbeeldingen en scripts voor één uur. Wanneer u aanpassingen test, herlaad altijd met Ctrl+F5 om uw laatste wijzigingen te zien. Uw bezoekers zien de update binnen een uur.

U heeft volledige controle: het bestand is gewone CSS en wordt als laatste geladen, zodat u elke stijl kunt overschrijven. Gebruik de DevTools van uw browser (F12) om elementen te inspecteren. Keycloak 26 gebruikt het PatternFly design system, dus de meeste kleurvariabelen heten --pf-v5-global--* en kunnen in :root worden overschreven.

Uw bedrijfsnaam instellen

Hiervoor hoeft u geen thema te bewerken. Open in uw beheerconsole Realm settings > General en stel de Display name in. Deze naam verschijnt op inlogpagina's en in e-mails.

Teksten aanpassen, in meerdere talen

U kunt teksten aanpassen zonder CSS of HTML te wijzigen. In default/login/messages/messages_en.properties vindt u alle teksten van het inlogformulier met hun standaardformulering. Om een regel te wijzigen, verwijdert u de #, schrijft u uw eigen tekst en slaat u op:

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

Voeg bestanden toe zoals messages_fr.properties voor Frans of messages_de.properties voor Duits, en schakel deze talen vervolgens in via de beheerconsole onder Realm settings > Localization.

Tip: Het tabblad Localization heeft ook een sectie Realm overrides, waarmee u teksten direct in de console kunt aanpassen: geen bestandsbewerking of herstart nodig. Gebruik de methode die het beste bij uw workflow past.

Uw e-mails branden

Keycloak verstuurt e-mails voor adresbevestiging, wachtwoordherstel en gebruikersuitnodigingen. In default/email/messages/messages_en.properties vindt u de standaard onderwerpregels en berichten die u kunt aanpassen:

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

Let bij het bewerken van e-mailberichten op het volgende:

• Behoud de {0}, {1}, {2} placeholders (Keycloak vult deze in met de link, weergavenaam en tijdslimiet).
• Escape apostrofs door er twee te schrijven (don''t).

Wilt u de HTML van e-mails aanpassen, kopieer dan de gewenste template uit het Keycloak base email theme naar default/email/html/ en bewerk uw kopie.

Stackhero configureert e-mailaflevering voor u met SPF, DKIM en DMARC ingesteld. Stel dit in via Realm settings > Email met de host en poort die op uw servicepagina staan.

Uw thema resetten indien nodig

Gaat er iets mis, dan kunt u de hele default-map verwijderen en uw service herstarten. Stackhero maakt dan een nieuw standaardthema aan, waarmee het standaard Keycloak-uiterlijk wordt hersteld.

Uw realms, gebruikers en clients staan in uw database en blijven onaangetast.

Ontwerp uw thema visueel met Quick Theme

In uw Keycloak-beheerconsole vindt u Quick Theme, de visuele themabouwer van Keycloak. Upload een logo, kies uw kleuren, bekijk een preview van uw login- en accountconsoles en download het voltooide thema als .jar-bestand.

Om het te installeren, plaatst u het bestand in de themes/-map via de editor en herstart u uw service. Het .jar-bestand wordt uitgepakt naar een themamap en het archief wordt verwijderd:

themes/acme.jar        wordt     themes/acme/

Het nieuwe thema verschijnt in Realm settings > Themes. U kunt de bestanden daarna handmatig blijven bewerken als u wilt.

Deze methode ondersteunt ook thema's die zijn gebouwd met Keycloakify of door een designer zijn aangeleverd. Elk .jar- of .zip-bestand met een thema kan op deze manier worden geïnstalleerd. Bestaat er al een thema met dezelfde naam, dan wordt het nieuwe geïnstalleerd als acme-1, zodat uploads nooit uw werk overschrijven. Is het bestand geen thema, dan blijft het gewoon staan en start Keycloak normaal op.

Eén merk per realm: white-label ondersteuning

Thema's worden per realm geselecteerd in Realm settings > Themes, met opties voor elk paginatype: login, account, admin en e-mail. Individuele applicaties kunnen ook hun eigen login-thema instellen in de client-instellingen.

Beheert u meerdere merken of biedt u white-label oplossingen, gebruik dan één realm per merk en wijs elk een eigen thema toe:

1. Kopieer in de editor de map default en geef de kopie een nieuwe naam (bijvoorbeeld acme).
2. Herstart uw service.
3. Open in de beheerconsole het betreffende realm en selecteer acme als login-thema.

Elk realm dat u niet configureert, blijft uw default-thema gebruiken.

De structuur van een Keycloak-thema begrijpen

Een thema is een map met submappen voor elk type pagina:

themes/
  acme/
    login/                             # Gebruikers-inlogpagina's
      theme.properties                 # Thema-overerving en CSS-includes
      resources/css/stackhero.css      # Uw CSS
      resources/img/logo.svg           # Uw afbeeldingen
      messages/messages_en.properties  # Uw teksten
    account/                           # Gebruikersprofielbeheer
    admin/                             # Uiterlijk van de beheerconsole
    email/                             # E-mailtemplates

Thema's erven van standaard Keycloak-thema's en overschrijven alleen wat u nodig heeft. Een typisch login/theme.properties-bestand ziet er zo uit:

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

• parent bepaalt het basisthema.
• styles somt de CSS-bestanden op die geladen moeten worden. Zet uw CSS als laatste zodat uw wijzigingen effect hebben.

De lijst styles vervangt die van het parent-thema, breidt deze niet uit. Neem altijd het stylesheet van het parent-thema (css/styles.css) op, anders verliest uw pagina de standaardopmaak.

U heeft alleen FreeMarker-templates (.ftl-bestanden) nodig als u de HTML-structuur wilt aanpassen. Voor kleuren, logo's, achtergronden, teksten en talen is geen templatebewerking nodig. Zie voor meer details de Keycloak themes documentatie.

Java-extensies (providers)

De map providers/ is bedoeld voor functionaliteiten die niet met thema's kunnen: aangepaste authenticators, user storage, event listeners of protocol mappers.

Plaats uw .jar-bestand in deze map en herstart uw service. Deze herstart duurt iets langer (ongeveer een minuut) omdat Keycloak zichzelf opnieuw opbouwt om de nieuwe extensie toe te voegen. Wilt u een extensie verwijderen, verwijder dan het bestand en herstart opnieuw.

U kunt hier ook thema-.jar-bestanden plaatsen, maar voor thema's is themes/ de voorkeur: dat vereist geen rebuild en u kunt de bestanden daarna blijven bewerken.