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

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

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

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

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

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

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

Настройка 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 рекомендуется настраивать индивидуально для пользователя.

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

...

нажимаем кнопку "Save". Имя пользователя и значение атрибута могут не совпадать. При аутентификации необходимо вводить в качестве имени пользователя значение указанное в атрибуте "User-Name".

Что бы задать/изменить пароль пользователя переходим на вкладку "Credentials" и нажимаем кнопку "Set password":

Image Added

вводим и подтверждаем пароль, нажимаем кнопку "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

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

...

    <!-- 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

...

sudo systemctl restart eltex-ems

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

Если при попытке зайти в Keycloak или при выполнении авторизации появляется сообщение:

Image Added

Если данное сообщение появляется при попыке войти в административную консоль Keycloak и не требуется использовать протокол HTTPS - необходимо изменить настройку внутри контейнера:

sudo docker ps
CONTAINER ID   IMAGE                              COMMAND                  CREATED       STATUS                PORTS                                                 NAMES
40aab4f3d28b   quay.io/keycloak/keycloak:20.0.5   "/opt/keycloak/bin/k…"   13 days ago   Up 6 days (healthy)   8443/tcp, 0.0.0.0:8282->8080/tcp, :::8282->8080/tcp   keycloak
9f6deac8dd6c   postgres:15                        "docker-entrypoint.s…"   13 days ago   Up 6 days (healthy)   0.0.0.0:5435->5432/tcp, :::5435->5432/tcp             postgres

sudo docker exec -it postgres psql -U postgres -w postgres -c "update realm set ssl_required='NONE' where name='master';"
UPDATE 1

cd /opt/keycloak/
sudo docker-compose stop && sudo docker-compose up -d
Stopping keycloak ... done
Stopping postgres ... done
Starting postgres ... done
Starting keycloak ... done

Если данное сообщение появляется при попытке авторизации пользователя - необходимо открыть Realm и перейдя в раздел Realm settings в настройке "Require SSL" выбрать "None" и нажать "Save".

В случае, если редирект не происходит или страница авторизации 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

...