Keycloak: Dostosuj wygląd

Łatwo dostosuj strony logowania, konsolę konta oraz e-maile Keycloak na Stackhero: ustaw swoje kolory, logo, teksty, a nawet twórz w pełni własne motywy za pomocą wbudowanego edytora online.

👋 Witamy w dokumentacji Stackhero!

Stackhero oferuje usługę Keycloak cloud, która umożliwia szybkie wdrożenie gotowego do produkcji dostawcy tożsamości w zaledwie 2 minuty:

• Nieograniczona liczba użytkowników, realms i klientów
• Obsługa OpenID Connect, OAuth 2.0, SAML 2.0, logowania społecznościowego, federacji LDAP oraz Active Directory
• Własna nazwa domeny z wbudowanym HTTPS dla bezpiecznego dostępu (na przykład https://login.twoja-firma.com)
• Własne motywy: łatwo dostosuj strony logowania, konsolę konta i wiadomości email za pomocą wbudowanego edytora online
• Dedykowany serwer email z obsługą SPF, DKIM i DMARC – potwierdzenia konta i resetowanie hasła obsługiwane są automatycznie
• Wbudowana baza danych PostgreSQL, z konsolą administracyjną dostępną na osobnym, zamykanym porcie
• Aktualizacje jednym kliknięciem pozwalają utrzymać system zawsze aktualny bez ręcznej ingerencji

Skup się na rozwoju, nie na konfiguracji: możesz przetestować rozwiązanie Keycloak cloud od Stackhero w mniej niż 5 minut.

Dostosuj wygląd swojego Keycloak

Strona logowania to jeden z pierwszych elementów widocznych dla Twoich użytkowników. Dzięki Stackhero możesz ją spersonalizować w kilka minut: ustaw swoje kolory, logo oraz teksty dla każdego obsługiwanego języka. Ta sama metoda dotyczy e-maili wysyłanych przez Keycloak.

Do dyspozycji masz dwa główne narzędzia, oba dostępne w ramach Twojej usługi:

• Edytor motywów – edytor plików online, w którym znajduje się Twój motyw.
• Quick Theme – wizualny kreator motywów wbudowany w konsolę administracyjną Keycloak, umożliwiający wybór kolorów i brandingu bez edycji CSS.

Nie jest wymagane SSH, przebudowywanie ani ponowne wdrażanie.

Otwórz edytor motywów

Na stronie Twojej usługi w panelu Stackhero znajdziesz adres URL Themes editor obok konsoli administracyjnej:

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

Zaloguj się używając danych administratora Keycloak – tych samych, których używasz do konsoli administracyjnej.

Oto dwie ważne kwestie:

• Edytor działa na porcie administracyjnym, a nie na porcie używanym przez Twoje aplikacje. Jeśli zamkniesz ten port w zaporze Stackhero, zarówno konsola administracyjna, jak i edytor staną się niedostępne. Twoje aplikacje nadal będą się uwierzytelniać jak zwykle.
• Wszystkie zmiany są zapisywane na dysku Twojej usługi, uwzględniane w backupach i przetrwają restart oraz aktualizacje.

Znajdziesz tam dwa katalogi:

Każdy katalog zawiera plik README.md z aktualną dokumentacją odpowiadającą wersji Twojej usługi.

Twój motyw jest gotowy do edycji

Otwórz themes/, a znajdziesz katalog default/. To Twój aktywny motyw, już używany przez instancję Keycloak. Nie musisz nic wybierać: po prostu edytuj pliki i obserwuj natychmiastowe efekty.

Nie musisz znać się wcześniej na motywach Keycloak. Każdy plik zawiera już najczęściej zmieniane ustawienia, pokazując aktualną wartość Keycloak jako zakomentowany przykład. Aby zaktualizować wartość, usuń znak komentarza, zmień wartość i zapisz.

Jeśli linia pozostanie zakomentowana, Keycloak użyje wartości domyślnej. Dzięki temu Twoja usługa zawsze zachowuje standardowe zachowanie Keycloak, nawet po aktualizacjach.

Aktualizacja logo

Otwórz default/login/resources/img/. W środku zobaczysz dwa obrazy aktualnie używane na stronie logowania. Prześlij własne logo, używając tej samej nazwy pliku, keycloak-logo-text.svg, i odśwież stronę logowania za pomocą Ctrl+F5 (Cmd+Shift+R na macOS).

To wszystko. Nie musisz edytować plików ani restartować usługi: zmiany są widoczne od razu po zapisaniu. Aby zmienić tło, zaktualizuj keycloak-bg-darken.svg w tym samym folderze.

Jeśli wolisz użyć innych nazw plików, zaktualizuj odwołania w default/login/resources/css/stackhero.css w sekcji "Your logo".

Ustawianie kolorów

W pliku stackhero.css znajdziesz zmienne już wpisane z aktualnymi wartościami:

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

Aby zastosować zmianę, usuń znaki komentarza, ustaw swój kolor, zapisz i odśwież stronę. To wszystko.

Podczas pracy: Przeglądarka buforuje CSS motywu, obrazy i skrypty przez godzinę. Podczas testowania zawsze odświeżaj stronę za pomocą Ctrl+F5, aby zobaczyć najnowsze zmiany. Twoi użytkownicy zobaczą aktualizacje w ciągu godziny.

Masz pełną kontrolę: plik to zwykły CSS i ładuje się jako ostatni, więc możesz nadpisać dowolny styl. Użyj narzędzi deweloperskich przeglądarki (F12), aby sprawdzić elementy. Keycloak 26 korzysta z PatternFly design system, więc większość zmiennych kolorów ma nazwę --pf-v5-global--* i można je nadpisać w :root.

Ustawianie nazwy firmy

Nie musisz edytować motywu. W konsoli administracyjnej otwórz Realm settings > General i ustaw Display name. Ta nazwa pojawi się na stronach logowania i w e-mailach.

Zmiana tekstów w wielu językach

Możesz zmieniać teksty bez edycji CSS czy HTML. W pliku default/login/messages/messages_en.properties znajdziesz wszystkie teksty formularza logowania z domyślnym brzmieniem. Aby zmienić linię, usuń #, wpisz własny tekst i zapisz:

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

Dodaj pliki takie jak messages_fr.properties dla francuskiego czy messages_de.properties dla niemieckiego, a następnie włącz te języki w konsoli administracyjnej w Realm settings > Localization.

Wskazówka: Zakładka Localization posiada także sekcję Realm overrides, która pozwala zmieniać teksty bezpośrednio w konsoli – bez edycji plików i restartu. Wybierz metodę najlepiej pasującą do Twojego procesu pracy.

Personalizacja e-maili

Keycloak wysyła e-maile dotyczące potwierdzenia adresu, resetowania hasła oraz zaproszeń użytkowników. W pliku default/email/messages/messages_en.properties znajdziesz standardowe tematy i treści gotowe do edycji:

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

Podczas edycji treści e-maili pamiętaj:

• Zachowaj znaczniki {0}, {1}, {2} (Keycloak uzupełni je linkiem, nazwą wyświetlaną i opóźnieniem).
• Apostrofy należy zapisywać podwójnie (don''t).

Aby nadpisać HTML e-maila, skopiuj wybrany szablon z Keycloak base email theme do default/email/html/, a następnie edytuj swoją kopię.

Stackhero konfiguruje wysyłkę e-maili za Ciebie, z ustawionymi SPF, DKIM i DMARC. Skonfiguruj to w Realm settings > Email używając hosta i portu podanych na stronie Twojej usługi.

Jeśli musisz zresetować motyw

Jeśli coś pójdzie nie tak, możesz usunąć cały katalog default i zrestartować usługę. Stackhero utworzy nowy domyślny motyw, przywracając standardowy wygląd Keycloak.

Twoje realmy, użytkownicy i klienci są przechowywani w bazie danych i pozostają nienaruszone.

Zaprojektuj motyw wizualnie z Quick Theme

W konsoli administracyjnej Keycloak znajdziesz Quick Theme – wizualny kreator motywów Keycloak. Prześlij logo, wybierz kolory, podglądaj strony logowania i konta, a następnie pobierz gotowy motyw jako plik .jar.

Aby go zainstalować, umieść plik w katalogu themes/ za pomocą edytora, a następnie zrestartuj usługę. Plik .jar zostanie rozpakowany do katalogu motywu, a archiwum usunięte:

themes/acme.jar        staje się     themes/acme/

Nowy motyw pojawi się w Realm settings > Themes. Możesz dalej edytować jego pliki ręcznie, jeśli chcesz.

Ta metoda obsługuje także motywy stworzone za pomocą Keycloakify lub dostarczone przez projektanta. Każdy plik .jar lub .zip zawierający motyw można zainstalować w ten sposób. Jeśli motyw o tej samej nazwie już istnieje, nowy zostanie zainstalowany jako acme-1, dzięki czemu Twoje pliki nigdy nie zostaną nadpisane. Jeśli plik nie jest motywem, zostanie po prostu zignorowany, a Keycloak uruchomi się normalnie.

Jedna marka na realm: wsparcie white-label

Motywy wybierane są per realm w Realm settings > Themes, z opcjami dla każdego typu strony: logowania, konta, admina i e-maili. Poszczególne aplikacje mogą także określić własny motyw logowania w ustawieniach klienta.

Jeśli obsługujesz wiele marek lub oferujesz rozwiązania white-label, użyj osobnego realm dla każdej marki i przypisz do niego własny motyw:

1. W edytorze skopiuj katalog default i zmień nazwę kopii (np. acme).
2. Zrestartuj usługę.
3. W konsoli administracyjnej otwórz odpowiedni realm i wybierz acme jako motyw logowania.

Każdy realm, którego nie skonfigurujesz, będzie nadal używał motywu default.

Struktura motywu Keycloak

Motyw to katalog zawierający podkatalogi dla każdego typu strony:

themes/
  acme/
    login/                             # Strony logowania użytkownika
      theme.properties                 # Dziedziczenie motywu i dołączanie CSS
      resources/css/stackhero.css      # Twój CSS
      resources/img/logo.svg           # Twoje obrazy
      messages/messages_en.properties  # Twoje teksty
    account/                           # Zarządzanie profilem użytkownika
    admin/                             # Wygląd konsoli administracyjnej
    email/                             # Szablony e-maili

Motywy dziedziczą po standardowych motywach Keycloak, nadpisując tylko to, co potrzebne. Typowy plik login/theme.properties wygląda tak:

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

• parent ustawia motyw bazowy.
• styles określa listę plików CSS do załadowania. Umieść swój CSS na końcu, aby mieć pewność, że zmiany zostaną zastosowane.

Lista styles zastępuje listę motywu nadrzędnego, nie rozszerza jej. Zawsze uwzględnij arkusz stylów rodzica (css/styles.css), w przeciwnym razie Twoja strona straci domyślny wygląd.

Szablony FreeMarker (.ftl) są potrzebne tylko, jeśli chcesz zmienić strukturę HTML. Do zmiany kolorów, logo, tła, tekstów i języków nie jest to wymagane. Więcej informacji znajdziesz w dokumentacji Keycloak dotyczącej motywów.

Rozszerzenia Java (providers)

Katalog providers/ służy do funkcji, których nie da się zrealizować motywami: własne autentykatory, przechowywanie użytkowników, nasłuchiwacze zdarzeń czy protocol mappers.

Umieść swój plik .jar w tym katalogu i zrestartuj usługę. Ten restart potrwa nieco dłużej (około minuty), ponieważ Keycloak przebuduje się, aby uwzględnić nowe rozszerzenie. Aby usunąć rozszerzenie, usuń plik i zrestartuj ponownie.

Możesz także umieszczać pliki .jar z motywami tutaj, ale preferowanym miejscem dla motywów jest themes/: nie wymaga to przebudowy i pozwala na dalszą edycję plików.