Оглавление |
---|
Описание решения
Для поддержки технологии SSO (single sing-on, технология единого входа) в рамках комплекса SoftWLC поддержана возможность интеграции с решением Keycloak (https://www.keycloak.org/), в основе которого используется протокол OAUTH 2.0 (https://oauth.net). Данное решение позволяет отказаться от использования локальных учетных записей (далее УЗ) для аутентификации и авторизации в Eltex-EMS, Личном кабинете (далее ЛК), Конструкторе порталов (далее КП) и eltex-radius-nbi и выполнять ее на основе БД пользователей Keycloak или использовать интеграцию Keycloak с LDAP.
Общая схема аутентификации в ЛК / КП
Drawio | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
AuthCode (authorization code) - временный код, который клиент должен обменять на AccessToken. AuthCode выдается сервером авторизации, на который обращается клиент после его аутентификации. С этим кодом пользователь возвращается на страницу приложения, которое обменивает его на AccessToken.
AccessToken - специальная строка, которую пользователь использует для выполнения запросов к приложению.
Схема процесса авторизации и взаимодействия ЛК/КП с NBI
Drawio | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Общая схема аутентификации и авторизации в EMS
Drawio | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Подсказка |
---|
Для выполнения запросов к NBI EMS использует сервисную УЗ "softwlc_service". |
Настройка Keycloak
Сервис Keycloak запускается в docker-контейнере. Подробнее про возможные концепции старта сервиса можно посмотреть в официальной документации к сервису.
...
Так же потребуется установить сервис docker и docker-compose.
Запуск сервиса в Docker с помощью Docker compose
Перед запуском контейнера на хостовую машину потребуется установить docker и плагин compose.
...
Примечание |
---|
Для всех новых создаваемых realm значение настройки "Require SSL" будет "External requests". Потребуется для нового realm в разделе "Realm settings" изменить настройку "Require SSL" : "None". |
Настройка Keycloak
Keycloak - первоначальная настройка
Отрыть браузер, в браузере пере"Настройка конструктора порталов" йти на страницу http://<IP-адрес сервера>:8282 и выбрать раздел Administration Console. После выбора раздела будет совершен переход на страницу авторизации.
...
После ввода логина/пароля откроется административная консоль:
Создание Realm
Realm - область управления, которая содержит совокупность всех данных: пользователей, учетные данные, роли и группы; необходимых для аутентификации и авторизации пользователей данного realm. Каждый realm изолирован от других realm-ов.
...
Нажимаем кнопку "Create". После создания переход в новый realm выполниться автоматически, дальнейшие настройки выполняются в нем.
Создание Clients
Client - объект, который содержит совокупность параметров, необходимых для связи с определенным приложением.
...
Примечание |
---|
Перед любыми действиями с realm необходимо убедиться, что Вы находитесь в целевом realm. |
Создание client для Личного кабинета
В созданном realm "softwlc" переходим в раздел clients и нажимаем кнопку "Сreate client":
...
Подсказка |
---|
При необходимости, если используется несколько экземпляров приложения eltex-wifi-cab, можно указать несколько различных значений "Valid redirect URIs", нажав на кнопку "Add valid redirec URIs". |
Создание client для Конструктора порталов
В созданном realm "softwlc" переходим в раздел clients и нажимаем кнопку "Сreate client":
...
Подсказка |
---|
При необходимости, если используется несколько экземпляров приложения eltex-portal-constructor, можно указать несколько различных значений "Valid redirect URIs", нажав на кнопку "Add valid redirec URIs". |
Создание 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.
...
Предупреждение |
---|
При настройке мапперов для EMS необходимо проконтролировать, что настройка "Add to access token" включена! |
Особенности взаимодействия сервиса eltex-radius-nbi с Keycloak
Сервис eltex-radius-nbi при взаимодействии с Keycloak использует токен (AccessToken), с которым к нему обратилось приложение (ЛК, КП или EMS), при этом используются ограничения на права обращения к методам NBI из роли пользователя.
Для обращения непосредственно к api eltex-radius-nbi можно использовать системных пользователей или создать их в ЛК.
Добавление и настройка Groups
Groups - группа общих политик и атрибутов, применяемых к пользователю.
Рекомендуется создать группу для каждого приложения и в рамках группы приложения создать подгруппы для каждого набора привилегий пользователей.
Создание групп
Для создания группы в realm "softwlc" перейдем в меню Groups и нажмем кнопку "Create group":
...
Аналогичным способом создать группы для приложений КП и EMS. В итоге получится следующий список групп:
Создание и настройка подгрупп
В группе "wifi-cab" нажать на
справа от названия группы. В открывшемся меню:...
Для корректного взаимодействия с EMS достаточно выполнить настройку в подгруппе атрибута "Eltex-EMS-Role". Другие атрибуты EMS рекомендуется настраивать индивидуально для пользователя.
Добавление и настройка пользователей
Примечание |
---|
Не рекомендуется создавать пользователя с именем "admin", т.к. это имя совпадает с именем пользователя под которым выполняется управление Keycloak и он не может с этим именем войти в EMS. |
...
нажимаем кнопку "Save". Имя пользователя и значение атрибута могут не совпадать. При аутентификации необходимо вводить в качестве имени пользователя значение указанное в атрибуте "User-Name".
Что бы задать/изменить пароль пользователя переходим на вкладку "Credentials" и нажимаем кнопку "Set password":
вводим и подтверждаем пароль, нажимаем кнопку "Save".
Переходим на вкладку Groups и нажимаем кнопку "Join Group", раскрываем группу "wifi-cab" и выбираем подгруппу "default_provider":
...
Аналогичным образом добавляем пользователя в подгруппы "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 |
Настройка личного кабинета
Примечание |
---|
После включения интеграции с keycloak станет невозможно добавлять/редактировать/удалять системных пользователей! |
...
Блок кода |
---|
<!-- SSO Settings --> <entry key="sso.enabled">true</entry> <entry key="sso.redirectUri">http://IP-адрес ЛК:8080/wifi-cab/sso</entry> <entry key="sso.clientSecret">HoDKUreDl0xmjUgV7p19YADAT5fvtOOG</entry> <entry key="sso.clientId">wifi-cab</entry> <entry key="sso.localauth.enabled">true</entry> <!-- SSO Auth --> <entry key="sso.auth.server.protocol">http</entry> <entry key="sso.auth.server.address">IP-адрес сервера Keycloak</entry> <entry key="sso.auth.server.port">8282</entry> <entry key="sso.auth.auth.path">/realms/softwlc/protocol/openid-connect/auth</entry> <entry key="sso.auth.logout.path">/realms/softwlc/protocol/openid-connect/logout</entry> <!-- SSO REST --> <entry key="sso.rest.server.protocol">http</entry> <entry key="sso.rest.server.address">IP-адрес сервера Keycloak</entry> <entry key="sso.rest.server.port">8282</entry> <entry key="sso.rest.server.timeout.sec">10</entry> <entry key="sso.rest.protocol.provider">keycloak</entry> <!-- rtk/keycloak --> <entry key="sso.rest.protocol.version">2.0</entry> <!--setting only matters when provider=rtk--> <entry key="sso.rest.username"></entry> <!--setting only matters when provider=rtk--> <entry key="sso.rest.password"></entry> <!--setting only matters when provider=rtk--> <entry key="sso.rest.getToken.path">/realms/SWLCsoftwlc/protocol/openid-connect/token</entry> <entry key="sso.rest.getUserInfo.path">/realms/SWLCsoftwlc/protocol/openid-connect/userinfo</entry> |
...
- <entry key="sso.clientId">wifi-cab</entry> - имя клиента, как оно указано в настройках Keycloak (Clients)
- <entry key="sso.localauth.enabled">true</entry> - разрешение локальной аутентификации в ЛК (для запрета необходимо указать "false")
- <entry key="sso.auth.server.protocol">http</entry> - тип используемого протокола
- <entry key="sso.auth.server.address">IP-адрес сервера Keycloak</entry> - адрес сервера Keycloak
- <entry key="sso.auth.server.port">8282</entry> - порт сервера Keycloak (по умолчанию 8282)
- <entry key="sso.auth.auth.path">/realms/softwlc/protocol/openid-connect/auth</entry> - после /realm/ необходимо указать имя realm, как оно создано в Keycloak
- <entry key="sso.auth.logout.path">/realms/softwlc/protocol/openid-connect/logout</entry> - после /realm/ необходимо указать имя realm, как оно создано в Keycloak
- <entry key="sso.rest.server.address">IP-адрес сервера Keycloak</entry> - адрес сервера Keycloak
- <entry key="sso.rest.server.port">8282</entry> - порт сервера Keycloak (по умолчанию 8282)
- <entry key="sso.rest.protocol.provider">keycloak</entry> - тип используемого сервера "keycloak"
- <entry key="sso.rest.getToken.path">/realms/SWLCsoftwlc/protocol/openid-connect/token</entry> - после /realm/ необходимо указать имя realm, как оно создано в Keycloak
- <entry key="sso.rest.getUserInfo.path">/realms/SWLCsoftwlc/protocol/openid-connect/userinfo</entry> - после /realm/ необходимо указать имя realm, как оно создано в Keycloak
...
Без форматирования |
---|
sudo systemctl restart eltex-wifi-cab |
Настройка конструктора порталов
Настройка взаимодействия с Keycloak выполняться в файле конфигурации "/etc/eltex-portal-constructor/application.conf" в разделе:
...
Без форматирования |
---|
sudo systemctl restart eltex-portal-constructor |
Настройка EMS
Примечание |
---|
После включения интеграции с Keycloak станет невозможно добавлять/редактировать/удалять системных пользователей! |
...
Без форматирования |
---|
sudo systemctl restart eltex-ems |
Решение проблем
Если при попытке зайти в Keycloak или при выполнении авторизации появляется сообщение:
Предупреждение |
---|
По умолчанию в Keycloak в настройке "Require SSL" установлено значение "External requests". Это означает, что подключаться к серверу по протоколу HTTP смогут только пользователи из подсетей "127.0.0.0/8, 10.0.0.0/8, 192.168.0.0/12, 172.16.0.0/12". https://www.keycloak.org/docs/latest/server_admin/#_ssl_modes |
Если данное сообщение появляется при попыке войти в административную консоль Keycloak и не требуется использовать протокол HTTPS - необходимо изменить настройку внутри контейнера:
Раскрыть | ||||||
---|---|---|---|---|---|---|
| ||||||
В данном примере предполагается что используется БД postgres. Проверить имя контейнера с БД postgres:
Выполнить команду для исправления записи в БД:
Перезапустить контейнеры:
|
Если данное сообщение появляется при попытке авторизации пользователя - необходимо открыть Realm и перейдя в раздел Realm settings в настройке "Require SSL" выбрать "None" и нажать "Save".
В случае, если редирект не происходит или страница авторизации Keycloak не открывается необходимо проверить доступность сервера с Keycloak с машины, на которой установлен комплекс SoftWLC командами:
...
Примечание |
---|
В некоторых браузерах при возникновении ошибок в настройке взаимодействия приложений с Keycloak может наблюдаться "белый экран", когда никакой ошибки в браузере не отображается. В этом случае следует смотреть логи соответствующего приложения. |
Личный кабинет
Логи аутентификации пользователей сохраняются в файл "/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
Название | Применение | Обязательность | Использование |
---|---|---|---|
User-Name | Передача имени пользователя | Да | ЛК/КП/NBI/EMS |
Eltex-User-Role | Передача роли пользователя | да | ЛК/КП/NBI |
Eltex-Domain | Передача домена пользователя | Да | ЛК/КП/NBI |
Eltex-User-Timezone | Передача таймзоны пользователя | Да - для ЛК Нет - для КП | ЛК/КП/NBI |
Eltex-EMS-Role | Передача роли в EMS | Да | EMS |
Eltex-EMS-ResendTrap | Настройка профайла пользователя: Пересылать аварии на Email | Нет | EMS |
Eltex-EMS-SendLogs | Настройка профайла пользователя: Пересылать логи на Email | Нет | EMS |
Eltex-EMS-SendOntProblems | Настройка профайла пользователя: Пересылать проблемы ONT на Email | Нет | EMS |
Eltex-EMS-IpList | Настройка профайла пользователя: IP-адрес для режима "multiuser" | Нет | EMS |
...