Общая схема взаимодействия
Установка
Полноценного этапа установки у сервиса нет, в основном старт сервиса заключается в исполнении скрипта или поднятии контейнеров.
Подробнее про возможные концепции старта сервиса можно посмотреть здесь.
Рекомендуемые минимальные требования: 4G RAM, 4 CPU, и 50Gb HDD.
Docker compose
Рассмотрим работу через docker compose.
Для корректного запуска рекомендуется установить compose плагин по инструкции
Ключ | Применение | Возможные значения |
---|---|---|
--auto-build | собирает наш экземпляр со всеми зависимостями и кастомизациями | - |
--db | указывает, какую БД мы будем использовать, чтобы выбрать соответствующий драйвер | mariadb (была в тестах 10 версия), mssql (была в тестах 2016 версия), mysql (была в тестах 8 версия), oracle (была в тестах 12с версия), postgres (была в тестах 10 версия) |
--hostname-strict-https | разрешаем/запрещаем фронту и бэку keycloak общаться по HTTP | false/true |
--hostname-strict | вкл/выкл динамического имени хоста из заголовков запросов | false/true |
--http-enabled | разрешаем взаимодействие по http | false/true |
--import-realm | включаем импортирование realms из файлов конфигураций | - |
--spi-user-profile-legacy-user-profile-read-only-attributes | "--spi-user-profile-legacy-user-profile-read-only-attributes *_RES_ACCESS_MODE" опция означает, что все пользовательские атрибуты с постфиксом _RES_ACCESS_MODE доступны для редактирования только администратору realm | Перечисление атрибутов |
--spi-login-protocol-openid-connect-suppress-logout-confirmation-screen | Выключает страницу Keycloak с подтверждением выхода(logout). В docker-compose.yml по умолчанию true. | true, false |
--spi-login-protocol-openid-connect-legacy-logout-redirect-uri | Включает возможность делать logout из Keycloak по старому механизму с использованием redirect_uri параметра. В docker-compose.yml по умолчанию true. | true, false |
Посмотреть более полную конфигурацию можно здесь
docker compose up -d
После старта сервиса можно перейти в web для его конфигурации http://{serverIp}:8282 , данные для входа указаны в конфигурации docker-compose.yml KEYCLOAK_ADMIN и KEYCLOAK_ADMIN_PASSWORD.
Настройка
Официальная инструкция
Первоначальная
Конфигурация Realms
Согласно документации keycloak "master" realm мы используем только для создание других realms. В свою очередь созданные нами realms из мастера мы будем конфигурировать в будущем и интегрировать с приложениями.
realm's definition
A realm manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm. Realms are isolated from one another and can only manage and authenticate the users that they control.
Таким образом мы можем создавать разные области, в которых будет собственная настройка для авторизации и аутентификации.
После создания вы автоматически окажетесь в новом realm, дальнейшие настройки мы продолжаем в нем.
Конфигурация Clients
Сущность client - нужна нам для связи keycloak с конкретным приложением.
Создадим клиент для взаимодействия с wifi-cab в качестве общего примера:
На этом этапе у разных клиентов, которых необходимо будет создавать в будущем, будет отличаться лишь название.
Если потребуется создать для приложения клиент со специфическими настройками, его имя будет гиперссылкой.
Для корректной работы нужно создать следующие клиенты:
- wifi-cab - для работы с личным кабинетом.
portal-constructor - для работы с порталом.
- nbi - для правильного взаимодействия с back-сервисом.
- ems - для работы с системой управления.
Конфигурация Mappers
Сущность mapper - нужна нам для определения keycloak какой атрибут пользователя передать в приложение.
Каждое приложение использует свои mappers, поэтому иногда процедуру требуется сделать несколько раз в зависимости от приложения.
Создадим mapper для взаимодействия с wifi-cab в качестве общего примера:
При создании mapper для атрибута Eltex-Domain обязательно нужно включить "Multivalued"
Чтобы настроить нужные mappers следует обратиться к таблице атрибутов в документации
Конфигурация Groups
Сущность group - нужна нам для применения к пользователям общих политик, например атрибутов.
Создадим группу для взаимодействия с wifi-cab в качестве общего примера:
Атрибуты для приложений могут различаться, поэтому при создании групп берите информацию согласно таблице атрибутов.
Таблица атрибутов, используемых SoftWLC
Название | Применение | Окончательно утвержден? |
---|---|---|
Eltex-User-Role | Передача роли пользователя для ЛК/КП/NBI | Да. Обязательный |
Eltex-Domain | Передача домена пользователя для ЛК/КП/NBI | Да. Обязательный для: ЛК/КП/NBI. |
User-Name | Передача имени пользователя для ЛК/КП/NBI/EMS | Да. Обязательный для Для: ЛК/NBI Используется для: ЛК/КП/NBI/EMS. |
Eltex-EMS-Role | Имя роли в ems | обязательный аттрибут для EMS |
Eltex-EMS-ResendTrap | Настройка профайла пользователя: Пересылать аварии на Email | необязательный аттрибут |
Eltex-EMS-SendLogs | Настройка профайла пользователя: Пересылать логи на Email | необязательный аттрибут |
Eltex-EMS-SendOntProblems | Настройка профайла пользователя: Пересылать проблемы ONT на Email | необязательный аттрибут |
Eltex-EMS-IpList | Настройка профайла пользователя: IP адреса для режима 'multiuser' | необязательный аттрибут |
Eltex-User-Timezone | Отвечает за таймзону пользователя. Участвует в планировщике отчетов и отображении времени. При настройке для пользователя должен иметь строковый формат вида Asia/Krasnoyarsk | Да. обязательный атрибут для ЛК/NBI необязателен, но желателен для КП |
Возможные проблемы при настройке
Авторизация в keycloak проходит, а в EMS нет (Ошибка - пользователя не существует).
Встречалась при первоначальной настройке.
Проблема заключается в том, что в токене не приходит роль пользователя.
Необходимо пересоздать маппер Eltex-EMS-Role
HTTPS required
Что бы не было проблемы "HTTPS required" надо в реалме указывать в настройке "Require SSL" None. По умолчанию стоит "External requests".