Keycloak: Pritaikyti išvaizdą

Lengvai pritaikykite Keycloak prisijungimo puslapius, paskyros konsolę ir el. laiškus Stackhero platformoje: nustatykite savo spalvas, logotipą, tekstus ir netgi kurkite visiškai individualius šablonus naudodami integruotą internetinį redaktorių.

👋 Sveiki atvykę į Stackhero dokumentaciją!

Stackhero siūlo Keycloak cloud paslaugą, kuri leidžia paprastai įdiegti gamybai paruoštą tapatybės tiekėją vos per 2 minutes:

• Neribotas naudotojų, realms ir klientų skaičius
• Palaikomi OpenID Connect, OAuth 2.0, SAML 2.0, socialinis prisijungimas, LDAP ir Active Directory federacija
• Individualus domeno vardas su integruotu HTTPS saugiam prisijungimui (pavyzdžiui, https://login.jusu-imone.lt)
• Individualūs temos: lengvai pritaikykite prisijungimo puslapius, paskyros konsolę ir el. laiškus su integruotu internetiniu redaktoriumi
• Dedikuotas el. pašto serveris su SPF, DKIM ir DMARC, todėl paskyros patvirtinimai ir slaptažodžio atstatymai bus tvarkomi automatiškai
• Integruota PostgreSQL duomenų bazė, administravimo konsolė pasiekiama atskiru, uždaromu prievadu
• Vieno paspaudimo atnaujinimai leidžia sistemą nuolat palaikyti atnaujintą be rankinio įsikišimo

Skirkite laiką kūrimui, o ne konfigūravimui: Stackhero Keycloak cloud sprendimą galite išbandyti vos per 5 minutes.

Pritaikykite savo Keycloak išvaizdą

Jūsų prisijungimo puslapis yra vienas pirmųjų dalykų, kuriuos mato jūsų naudotojai. Su Stackhero galite jį pritaikyti vos per kelias minutes: nustatykite savo spalvas, logotipą ir tekstus kiekvienai palaikomai kalbai. Tokiu pačiu principu galite pritaikyti ir Keycloak siunčiamus el. laiškus.

Yra du pagrindiniai įrankiai, abu įtraukti į jūsų paslaugą:

• Temų redaktorius – internetinis failų redaktorius, kuriame saugoma jūsų tema.
• Quick Theme – vizualus temų dizaineris, integruotas į Keycloak administravimo konsolę, leidžiantis pasirinkti spalvas ir prekinį ženklą be CSS redagavimo.

Nereikia SSH, nereikia perkompiliuoti ar iš naujo diegti paslaugos.

Atidarykite temų redaktorių

Jūsų paslaugos puslapyje Stackhero valdymo skydelyje šalia administravimo konsolės rasite Themes editor nuorodą:

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

Prisijunkite naudodami Keycloak administratoriaus prisijungimo duomenis – tuos pačius, kuriuos naudojate administravimo konsolei.

Svarbu atkreipti dėmesį į du dalykus:

• Redaktorius veikia administravimo prievade, o ne tame, kurį naudoja jūsų aplikacijos. Jei Stackhero ugniasienėje uždarysite šį prievadą, tiek administravimo konsolė, tiek redaktorius taps nepasiekiami. Jūsų aplikacijos ir toliau galės autentifikuotis kaip įprasta.
• Visi pakeitimai saugomi jūsų paslaugos diske, įtraukiami į atsargines kopijas ir išlieka po perkrovimų ar atnaujinimų.

Rasite du katalogus:

Kiekviename kataloge yra README.md failas su naujausia dokumentacija, atitinkančia jūsų paslaugos versiją.

Jūsų tema paruošta redagavimui

Atidarykite themes/ ir rasite default/ katalogą. Tai yra jūsų aktyvi tema, jau naudojama jūsų Keycloak instancijoje. Nieko pasirinkti nereikia: tiesiog redaguokite failus ir matykite pakeitimus iš karto.

Jums nereikia išankstinių žinių apie Keycloak temas. Kiekviename faile jau pateikti dažniausiai keičiamų nustatymų pavyzdžiai su dabartine Keycloak reikšme kaip užkomentuotas pavyzdys. Norėdami pakeisti reikšmę, pašalinkite komentaro ženklą, pakoreguokite reikšmę ir išsaugokite.

Jei eilutė lieka užkomentuota, Keycloak naudoja numatytąją reikšmę. Tai užtikrina, kad jūsų paslauga visada atitiks standartinį Keycloak elgesį, net ir po atnaujinimų.

Logotipo atnaujinimas

Atidarykite default/login/resources/img/. Čia rasite du šiuo metu prisijungimo puslapyje naudojamus paveikslėlius. Įkelkite savo logotipą su tuo pačiu failo pavadinimu – keycloak-logo-text.svg – ir atnaujinkite prisijungimo puslapį naudodami Ctrl+F5 (Cmd+Shift+R macOS).

Viskas, ką reikia padaryti. Nereikia redaguoti kitų failų ar perkrauti paslaugos: pakeitimai pritaikomi iš karto po išsaugojimo. Norėdami pakeisti fono paveikslėlį, atnaujinkite keycloak-bg-darken.svg tame pačiame kataloge.

Jei norite naudoti kitus failų pavadinimus, galite atnaujinti nuorodas faile default/login/resources/css/stackhero.css skiltyje "Your logo".

Spalvų nustatymas

Faile stackhero.css rasite jau užrašytas kintamąsias su dabartinėmis reikšmėmis:

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

Norėdami pritaikyti pakeitimą, pašalinkite komentaro ženklus, įrašykite savo spalvą, išsaugokite ir perkraukite puslapį. Viskas.

Kol dirbate: Jūsų naršyklė talpina temos CSS, paveikslėlius ir skriptus vienai valandai. Atliekant pakeitimus, visada atnaujinkite puslapį su Ctrl+F5, kad matytumėte naujausius pakeitimus. Jūsų lankytojai matys atnaujinimus per valandą.

Turite visišką kontrolę: failas yra paprastas CSS ir įkeliamas paskutinis, todėl galite perrašyti bet kokį stilių. Naudokite naršyklės DevTools (F12), kad apžiūrėtumėte elementus. Keycloak 26 naudoja PatternFly design system, todėl dauguma spalvų kintamųjų vadinasi --pf-v5-global--* ir gali būti perrašyti :root bloke.

Įmonės pavadinimo nustatymas

Tam nereikia redaguoti temos. Administravimo konsolėje atidarykite Realm settings > General ir nustatykite Display name. Šis pavadinimas bus rodomas prisijungimo puslapiuose ir el. laiškuose.

Tekstų keitimas keliomis kalbomis

Tekstus galite keisti neliesdami CSS ar HTML. Faile default/login/messages/messages_en.properties rasite visus prisijungimo formos tekstus su numatytomis reikšmėmis. Norėdami pakeisti eilutę, pašalinkite #, įrašykite savo tekstą ir išsaugokite:

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

Pridėkite tokius failus kaip messages_fr.properties prancūzų ar messages_de.properties vokiečių kalbai, tada įjunkite šias kalbas administravimo konsolėje per Realm settings > Localization.

Patarimas: Skiltyje Localization taip pat yra Realm overrides dalis, leidžianti keisti tekstus tiesiogiai konsolėje – nereikia redaguoti failų ar perkrauti paslaugos. Naudokite jums patogiausią būdą.

El. laiškų prekinis ženklinimas

Keycloak siunčia el. laiškus adresų patvirtinimui, slaptažodžio atstatymui ir naudotojų kvietimams. Faile default/email/messages/messages_en.properties rasite standartines temų eilutes ir žinutes, kurias galite pritaikyti:

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

Redaguojant el. laiškų turinį, atkreipkite dėmesį:

• Palikite {0}, {1}, {2} vietos žymes (Keycloak jas užpildys nuoroda, rodomu vardu ir laiko intervalu).
• Apostrofą pabėgti reikia rašant du (don''t).

Norėdami pakeisti el. laiško HTML, nukopijuokite norimą šabloną iš Keycloak bazinės el. laiškų temos į default/email/html/ ir redaguokite savo kopiją.

Stackhero automatiškai sukonfigūruoja el. pašto siuntimą su SPF, DKIM ir DMARC. Nustatykite tai Realm settings > Email naudodami paslaugos puslapyje nurodytą serverį ir prievadą.

Jei reikia atstatyti temą

Jei kas nors nepavyko, galite ištrinti visą default katalogą ir perkrauti paslaugą. Stackhero sukurs naują numatytąją temą, atkurdama standartinę Keycloak išvaizdą.

Jūsų realm'ai, naudotojai ir klientai saugomi duomenų bazėje ir nebus paveikti.

Kurkite temą vizualiai su Quick Theme

Keycloak administravimo konsolėje rasite Quick Theme – Keycloak vizualų temų dizainerį. Įkelkite logotipą, pasirinkite spalvas, peržiūrėkite prisijungimo ir paskyros konsoles, atsisiųskite galutinę temą kaip .jar failą.

Norėdami ją įdiegti, įkelkite failą į themes/ katalogą naudodami redaktorių ir perkraukite paslaugą. .jar bus išpakuotas į temų katalogą, o archyvas pašalintas:

themes/acme.jar        becomes     themes/acme/

Nauja tema atsiras Realm settings > Themes. Jei norite, galite toliau redaguoti jos failus rankiniu būdu.

Šis metodas taip pat palaiko temas, sukurtas su Keycloakify arba dizainerio pateiktas temas. Bet kuris .jar ar .zip failas su tema gali būti įdiegtas tokiu būdu. Jei tema tokiu pačiu pavadinimu jau egzistuoja, nauja bus įdiegta kaip acme-1, todėl jūsų darbai niekada nebus perrašyti. Jei failas nėra tema, jis tiesiog paliekamas nepaliestas, o Keycloak paleidžiamas kaip įprasta.

Vienas prekinis ženklas kiekvienam realm: white-label palaikymas

Temos pasirenkamos kiekvienam realm atskirai per Realm settings > Themes, su pasirinkimais kiekvienam puslapio tipui: prisijungimo, paskyros, administravimo ir el. laiškų. Atskiros aplikacijos taip pat gali nurodyti savo prisijungimo temą kliento nustatymuose.

Jei valdote kelis prekių ženklus ar siūlote white-label sprendimus, naudokite po vieną realm kiekvienam prekės ženklui ir priskirkite kiekvienam individualią temą:

1. Redaktoriuje nukopijuokite default katalogą ir pervadinkite kopiją (pvz., acme).
2. Perkraukite paslaugą.
3. Administravimo konsolėje atidarykite atitinkamą realm ir pasirinkite acme kaip prisijungimo temą.

Visi realm'ai, kuriems nenurodysite temos, toliau naudos jūsų default temą.

Keycloak temų struktūros supratimas

Tema yra katalogas, kuriame yra poaplankiai kiekvienam puslapio tipui:

themes/
  acme/
    login/                             # Naudotojo prisijungimo puslapiai
      theme.properties                 # Temos paveldėjimas ir CSS įtraukimas
      resources/css/stackhero.css      # Jūsų CSS
      resources/img/logo.svg           # Jūsų paveikslėliai
      messages/messages_en.properties  # Jūsų tekstai
    account/                           # Naudotojo profilio valdymas
    admin/                             # Administravimo konsolės išvaizda
    email/                             # El. laiškų šablonai

Temos paveldi iš standartinių Keycloak temų, perrašydamos tik tai, kas būtina. Tipinis login/theme.properties failas atrodo taip:

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

• parent nurodo bazinę temą.
• styles išvardija CSS failus, kuriuos reikia įkelti. Savo CSS įrašykite paskutinį, kad pakeitimai būtų pritaikyti.

styles sąrašas pakeičia tėvinės temos sąrašą, o ne jį papildo. Visada įtraukite tėvinės temos stilių (css/styles.css), kitaip jūsų puslapis praras numatytąjį stilių.

FreeMarker šablonų (.ftl failų) reikia tik jei norite keisti HTML struktūrą. Spalvoms, logotipams, fonams, tekstams ir kalboms šablonų redaguoti nereikia. Daugiau informacijos rasite Keycloak temų dokumentacijoje.

Java plėtiniai (providers)

providers/ katalogas skirtas funkcijoms, kurių negalima įgyvendinti temomis: individualiems autentifikatoriams, naudotojų saugykloms, įvykių klausytojams ar protokolų žemėlapiams.

Įkelkite savo .jar failą į šį katalogą ir perkraukite paslaugą. Šis perkrovimas užtruks šiek tiek ilgiau (apie minutę), nes Keycloak persikompiliuos, kad įtrauktų naują plėtinį. Norėdami pašalinti plėtinį, ištrinkite failą ir perkraukite dar kartą.

Temų .jar failus taip pat galite dėti čia, tačiau temoms rekomenduojama naudoti themes/ katalogą: nereikia perkompiliuoti ir galite toliau redaguoti failus po įdiegimo.