Описание решения

Для поддержки технологии SSO (single sing-on, технология единого входа) в рамках комплекса SoftWLC поддержана возможность интеграции с решением Keycloak (https://www.keycloak.org/), в основе которого используется протокол OAUTH 2.0 (https://oauth.net). Данное решение позволяет отказаться от использования локальных учетных записей (далее УЗ) для аутентификации и авторизации в Eltex-EMS, Личном кабинете (далее ЛК), Конструкторе порталов (далее КП) и eltex-radius-nbi и выполнять ее на основе БД пользователей Keycloak или использовать интеграцию Keycloak с LDAP.

Общая схема аутентификации в ЛК / КП

Image Removed

AuthCode (authorization code) - временный код, который клиент должен обменять на AccessToken. AuthCode выдается сервером авторизации, на который обращается клиент после его аутентификации. С этим кодом пользователь возвращается на страницу приложения, которое обменивает его на AccessToken.

AccessToken - специальная строка, которую пользователь использует для выполнения запросов к приложению.

Схема процесса авторизации и взаимодействия ЛК/КП с NBI

Image Removed

Общая схема аутентификации и авторизации в EMS

Image Removed

Настройка Keycloak

Сервис Keycloak запускается в docker-контейнере. Подробнее про возможные концепции старта сервиса можно посмотреть в официальной документации к сервису.

...

Так же потребуется установить сервис docker и docker-compose.

Запуск сервиса в Docker с помощью Docker compose

Перед запуском контейнера на хостовую машину потребуется установить docker и плагин compose.

...

Настройка Keycloak

Keycloak - первоначальная настройка

Отрыть браузер, в браузере пере"Настройка конструктора порталов" йти на страницу http://<IP-адрес сервера>:8282 и выбрать раздел Administration Console. После выбора раздела будет совершен переход на страницу авторизации.

...

После ввода логина/пароля откроется административная консоль:

Создание Realm

Realm - область управления, которая содержит совокупность всех данных: пользователей, учетные данные, роли и группы; необходимых для аутентификации и авторизации пользователей данного realm. Каждый realm изолирован от других realm-ов.

...

Нажимаем кнопку "Create". После создания переход в новый realm выполниться автоматически, дальнейшие настройки выполняются в нем.

Создание Clients

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

...

Создание client для Личного кабинета

В созданном realm "softwlc" переходим в раздел clients и нажимаем кнопку "Сreate client":

...

Создание client для Конструктора порталов

В созданном realm "softwlc" переходим в раздел clients и нажимаем кнопку "Сreate client":

...

Создание client для EMS

В созданном realm "softwlc" переходим в раздел clients и нажимаем кнопку "Сreate client":

...

и нажимаем кнопку "Save".

Настройка mappers

Mapper (далее "маппер") отвечает за передачу атрибута пользователя в приложение. Настройка необходимых атрибутов выполняется отдельно для каждого "client". Для каждого приложения существует своя таблица атрибутов, которые необходимо настроить.

Настройка mappers для Личного кабинета

Для ЛК поддержаны атрибуты:

...

Состояние мапперов для client "wifi-cab" после настройки:

Настройка mappers для Конструктора порталов

Для КП поддержаны атрибуты аналогичные ЛК. Настройка мапперов для client "portal-constructor" выполняется аналогично настройке мапперов для ЛК:

...

Состояние мапперов для client "portal-constructor" после настройки:

Настройка mappers для EMS

Если для ЛК и КП атрибуты совпадают, то для EMS в связи с архитектурными отличиями используется практически полностью другой набор атрибутов. Атрибуты, которые используются при настройке client для приложения EMS, имеют в своем названии "EMS". В частности, ЛК/КП и EMS имеют различный набор ролей. Настройки роли EMS определяют домен пользователя, для пользователя ЛК/КП же требуется указание отдельного атрибута Eltex-Domain.

...

Особенности взаимодействия сервиса eltex-radius-nbi с Keycloak

Сервис eltex-radius-nbi при взаимодействии с Keycloak использует токен (AccessToken), с которым к нему обратилось приложение (ЛК, КП или EMS), при этом используются ограничения на права обращения к методам NBI из роли пользователя.

Для обращения непосредственно к api eltex-radius-nbi можно использовать системных пользователей или создать их в ЛК.

Добавление и настройка Groups

Groups - группа общих политик и атрибутов, применяемых к пользователю. 

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

Создание групп

Для создания группы в realm "softwlc" перейдем в меню Groups и нажмем кнопку "Create group":

...

Аналогичным способом создать группы для приложений КП и EMS. В итоге получится следующий список групп:

Image ModifiedСоздание и настройка подгрупп

В группе "wifi-cab" нажать на  справа от названия группы. В открывшемся меню:

...

Для корректного взаимодействия с EMS достаточно выполнить настройку в подгруппе атрибута "Eltex-EMS-Role". Другие атрибуты EMS рекомендуется настраивать индивидуально для пользователя.

Добавление и настройка пользователей

...

Аналогичным образом добавляем пользователя в подгруппы "portal-constructor - default_provider" и "ems - SuperUser". В итоге членство пользователя в группах будет выглядеть следующим образом:

Интеграция с LDAP

Возможна интеграция Keycloak с LDAP. В приведенном примере рассматривается интеграция с OpenLDAP. Установка и настройка OpenLDAP в данной документации не рассматривается. Предполагается, что он уже установлен и готов к работе.

...

Далее в инструкции указан один из вариантов интеграции.

Настройка взаимодействия с LDAP

Настройка интеграции с LDAP выполняется в рамках одного realm.

...

В случае проблем с соединением надо проверить доступность сервера LDAP по указанному адресу, а также проверить работоспособность УЗ и правильность введенных данных.

Настройка group-ldap-mapper

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

...

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

Настройка маппинга имени пользователя в атрибут User-Name

Настройку маппинга имени пользователя LDAP в атрибут User-Name выполняется в рамках настройки мапперов каждого client realm.

...

Далее необходимо настроить аналогичным образом мапперы clients для portal-constructor и ems.

Добавление пользователей в группу

Добавление пользователей импортированных из LDAP в ранее созданные группы ems, portal-constructor, wifi-cab выполняется аналогично добавлению пользователей Keycloak.

...

После этого данный пользователь появиться в подгруппе "default_provider". Аналогичным образом добавляем пользователя в подгруппы "portal-constructor - default_provider" и "ems - SuperUser".

Настройка NBI

Настройка взаимодействия с Keycloak выполняться в файле конфигурации "/etc/eltex-radius-nbi/radius_nbi_config.txt" в разделе:

...

sudo systemctl restart tomcat8

Настройка личного кабинета

...

sudo systemctl restart eltex-wifi-cab

Настройка конструктора порталов

Настройка взаимодействия с Keycloak выполняться в файле конфигурации "/etc/eltex-portal-constructor/application.conf" в разделе:

...

sudo systemctl restart eltex-portal-constructor

Настройка EMS

...

sudo systemctl restart eltex-ems

Решение проблем

В случае, если редирект не происходит или страница авторизации Keycloak не открывается необходимо проверить доступность сервера с Keycloak с машины, на которой установлен комплекс SoftWLC командами:

...

Личный кабинет

Логи аутентификации пользователей сохраняются в файл "/var/log/eltex-wifi-cab/default.log".

...

то необходимо проверить корректность значения параметра "sso.auth.auth.path" - правильно ли указано имя Realm и внимательно проверить нет ли лишних символов. Если аналогичное сообщение возникает при выходе из ЛК - следует проверить корректность значения параметра "sso.auth.logout.path".

Конструктор порталов

Логи аутентификации пользователей сохраняются в файл "/var/log/eltex-portal-constructor/portal-constructor.log".

...

то необходимо проверить в настройках КП параметры "client_id" и "redirect_uri": соответствие параметра "client_id" используемому в настройках Keycloak имени client, корректность параметра "redirect_uri" и соответствие его настройке вкладке "Settings" Keycloak для "Client" "wifi-cab" параметр "Valid redirect URIs".

Eltex-EMS

Логи аутентификации пользователей сохраняются в файл "/var/log/eltex-ems/black_box.txt".

...

то необходимо проверить корректность настройки параметра EMS "sso.keycloak.resource" и соответствие его используемому в Keycloak "Realm - Client" (в приведенной инструкции "ems").

Eltex-radius-NBI

Логи аутентификации сохраняются в файл "/var/log/eltex-axis/radius-nbi/nbi_error.log".

...

то необходимо проверить корректность значений параметров "sso.rest.getToken.path" и "sso.rest.getUserInfo.path": корректность Realm, корректность параметров в целом, отсутствие лишних символов.

Приложения

Таблица атрибутов пользователей, используемых SoftWLC

...