Рубрики
Без рубрики

Настройка тем для Keycloak

Узнайте о темах в Keycloak – их типах и структуре.

Автор оригинала: Sampada Wagde.

1. Обзор

Keycloak -это решение для управления идентификацией и доступом с открытым исходным кодом или IAM, которое может использоваться в качестве стороннего сервера авторизации для управления требованиями к аутентификации и авторизации наших веб-или мобильных приложений.

В этом уроке мы сосредоточимся на том, как мы можем настроить тему для нашего сервера Keycloak , чтобы у нас был другой внешний вид для наших веб-страниц, обращенных к конечным пользователям.

Во-первых, мы установим фон с точки зрения автономного сервера Keycloak. В последующих разделах мы рассмотрим аналогичные примеры в контексте встроенного.

Для этого мы построим на основе наших предыдущих статей: Краткое руководство по использованию Keycloak и Keycloak, встроенного в приложение Spring Boot . Так что для тех, кто начинает, это хорошая идея, чтобы пройти через первый.

2. Темы в Keycloak

2.1. Темы по умолчанию

Несколько тем предварительно встроены в Keycloak и поставляются в комплекте с дистрибутивом.

Для автономного сервера они могут быть найдены в разных папках в каталоге keycloak-<версия>/темы :

  • base : скелетная тема, содержащая HTML-шаблоны и пакеты сообщений; все темы, включая пользовательские, обычно наследуются от нее
  • keycloak : содержит изображения и таблицы стилей для украшения страниц; если мы не предоставляем пользовательскую тему, она используется по умолчанию

Не рекомендуется изменять существующие темы. Вместо этого мы должны создать новую тему, которая расширяет одну из вышеперечисленных двух.

Чтобы создать новую настроенную тему, нам нужно добавить новую папку, назовем ее custom , в каталог themes //. В случае, если мы хотим провести полный капитальный ремонт, копирование содержимого из папки base -лучший способ начать работу.

Для нашей демо-версии мы не планируем заменять все, поэтому прагматично получить содержимое из каталога keycloak .

Как мы увидим в следующем разделе, custom потребуется только содержимое типа темы, который мы хотим переопределить, а не вся папка keycloak .

2.2. Типы тем

Keycloak поддерживает шесть типов тем:

  1. Общие: для общих элементов, таких как шрифты; импортируется другими типами тем
  2. Добро пожаловать: на целевую страницу
  3. Вход: для страниц входа, OTP, предоставления, регистрации и забытых паролей
  4. Учетная запись: для страниц управления учетными записями пользователей
  5. Консоль администратора: для консоли администратора
  6. Электронная почта: для электронных писем, отправляемых сервером

Последние четыре темы из приведенного выше списка можно задать с помощью консоли администратора для автономного сервера. Когда мы создаем новую папку в каталоге themes , она доступна для выбора после перезагрузки сервера.

Давайте войдем в консоль администратора с учетными данными initial 1 / заг 1!ВИКТОРИНА и перейдите на вкладку Темы для нашего царства:

Примечательно, что темы заданы по областям, так что у нас могут быть разные темы для разных областей. Здесь мы устанавливаем нашу пользовательскую тему для управления учетными записями пользователей для нашего Spring Boot Keycloak realm .

2.3. Структура типа темы

Помимо шаблонов HTML, пакетов сообщений, изображений и таблиц стилей, описанных в нашем разделе Темы по умолчанию , тема в Keycloak состоит еще из нескольких элементов – свойств темы и сценариев.

Каждый тип темы содержит файл theme.properties . В качестве примера давайте посмотрим на этот файл из типа account :

parent=base
import=common/keycloak

styles=css/account.css
stylesCommon=node_modules/patternfly/dist/css/patternfly.min.css node_modules/patternfly/dist/css/patternfly-additions.min.css

Как мы видим, эта тема расширяется от темы base , чтобы получить все свои пакеты HTML и сообщений, а также импортирует тему common , чтобы включить в нее несколько стилей . Кроме того, он также определяет свой собственный стиль, css/account.css .

Сценарии являются необязательной функцией. Если нам нужно включить специальные файлы JavaScript для наших шаблонов для данного типа темы, мы можем создать каталог resources/js и сохранить их там. Затем нам нужно включить их в наш theme.properties :

scripts=js/script1.js js/script2.js

2.4. Добавление Настроек

А теперь перейдем к самому интересному!

Давайте возьмем пример нашей страницы управления учетными записями и посмотрим, как изменить ее внешний вид. Если быть точным, мы изменим логотип, появляющийся на странице .

Непосредственно перед тем, как мы внесем все изменения, ниже приведен исходный шаблон, доступный по адресу http://localhost:8180/auth/realms/SpringBootKeycloak/account :

Давайте попробуем изменить логотип на наш собственный. Для этого нам нужно добавить новую папку account в каталог themes/custom . Мы скорее скопируем его из каталога themes/keycloak , чтобы у нас были все необходимые элементы.

Теперь остается только добавить наш новый файл логотипа, скажем baeldung.png в resources/img в нашем пользовательском каталоге и изменить resources/css/account.css :

.navbar-title {
    background-image: url('../img/baeldung.png');
    height: 25px;
    background-repeat: no-repeat;
    width: 123px;
    margin: 3px 10px 5px;
    text-indent: -99999px;
}

.container {
    height: 100%;
    background-color: #fff;
}

И вот как теперь выглядит страница:

Важно отметить, что на этапе разработки мы хотели бы увидеть эффект наших изменений немедленно, без перезагрузки сервера . Чтобы включить это, нам нужно внести несколько изменений в Keycloak standalone.xml в папке автономная/конфигурация :


    -1
    false
    false
    ...

Аналогично тому, как мы настроили тему account здесь, чтобы изменить внешний вид других типов тем, нам нужно добавить новые папки с именами admin , email, или login и выполнить тот же процесс.

2.5. Настройка страницы приветствия

Чтобы настроить страницу приветствия, сначала нам нужно добавить строку в standalone.xml :


    ...
    custom
    ...

Во-вторых, мы должны создать папку welcome в разделе темы/пользовательские . Опять же, разумно скопировать index.ftl и theme.properties вместе с существующими ресурсами из каталога по умолчанию keycloak theme.

Теперь давайте попробуем изменить фон этой страницы.

Давайте перейдем к http://localhost:8180/auth/ чтобы увидеть, как это изначально выглядит:

Чтобы изменить фоновое изображение, сохраните новое изображение, скажем geo.png, внутри темы/пользовательские/добро пожаловать/ресурсы , а затем просто отредактируйте ресурсы/css/welcome.css :

body {
    background: #fff url(../geo.png);
    background-size: cover;
}

Вот какой эффект:

3. Настройка встроенного сервера блокировки ключей

Встроенный сервер блокировки ключей по определению означает, что на вашем компьютере не установлен поставщик IAM. Следовательно, нам нужно сохранить все необходимые артефакты, такие как themes.properties и CSS-файлы, в нашем исходном коде .

Хорошее место для хранения их в папке src/main/resources/themes нашего проекта Spring Boot.

Конечно, поскольку файлы структуры темы одинаковы, способ их настройки также остается таким же, как и на автономном сервере.

Тем не менее, нам нужно настроить несколько вещей, чтобы дать указание серверу Keycloak забрать материал из нашей пользовательской темы.

3.1. Изменения в файле определения области

Во-первых, давайте посмотрим, как указать пользовательскую тему для данного типа темы.

Напомним, что в случае нашего автономного сервера на странице Темы нашей консоли администратора мы добавили пользовательскую тему из выпадающего списка для Темы учетной записи .

Чтобы достичь того же эффекта здесь, нам нужно добавить строку в наш файл определения области, baeldung-realm.json :

"accountTheme": "custom",

И это все, что нам нужно; все остальные типы, такие как Login и Email , по-прежнему будут следовать стандартной теме.

3.2. Перенаправление в каталог пользовательских тем

Далее давайте посмотрим, как мы можем сообщить серверу, где находится указанная пользовательская тема.

Мы можем сделать это несколькими способами.

Во время запуска загрузочного приложения для нашего встроенного сервера мы можем указать каталог темы в качестве аргумента виртуальной машины:

mvn spring-boot:run -Dkeycloak.theme.dir=/src/main/resources/themes

Чтобы добиться того же программно, мы можем установить его в качестве системного свойства в нашем классе @SpringBootApplication :

public static void main(String[] args) throws Exception {
    System.setProperty("keycloak.theme.dir","src/main/resources/themes");
    SpringApplication.run(JWTAuthorizationServerApp.class, args);
}

Или мы можем изменить конфигурацию сервера в файле keycloak-server.json :

"theme": {
    ....
    "welcomeTheme": "custom",
    "folder": {
        "dir": "src/main/resources/themes"
    }
},

Примечательно, что здесь мы также добавили атрибут welcome Theme , чтобы включить настройки на странице приветствия.

Как отмечалось ранее, все остальные изменения в CSS-файлах и изображениях остаются прежними .

Чтобы просмотреть изменения на нашей странице приветствия, нам нужно запустить встроенный сервер и перейти к http://localhost:8083/auth .

Страница управления учетной записью доступна по адресу http://localhost:8083/auth/realms/baeldung/account и мы можем получить доступ к нему, используя следующие учетные данные: [email protected] / 123.

4. Заключение

В этом уроке мы узнали о темах в Keycloak – их типах и структуре .

Затем мы рассмотрели несколько готовых тем и то, как расширить их, чтобы создать нашу собственную настроенную тему в отдельном экземпляре.

Наконец, мы увидели, как добиться того же самого во встроенном сервере Keycloak.

Как всегда, исходный код доступен на GitHub. Для автономного сервера он находится на учебниках GitHub , а для встроенного экземпляра-на OAuth GitHub .

Читайте ещё по теме: