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

Для поддержки технологии 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-контейнере. Подробнее про возможные концепции старта сервиса можно посмотреть в официальной документации к сервису.

Минимальные требования к хостовой машине, на которой выполняется запуск контейнера: 4G RAM, 4 CPU, 50Gb HDD.

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

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

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

Установка docker.

Установка плагина compose.

Далее создать на хостовой машине папку:

sudo mkdir /opt/keycloak

В этой папке создать файл docker-compose.yml:

version: "3.9"
services:
  keycloak-postgres:
    image: library/postgres:${KC_POSTGRES_IMAGE_TAG:-15}
    container_name: ${POSTGRES_CONTAINER_NAME:-postgres}
    restart: unless-stopped
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: postgres
    healthcheck:
      test: pg_isready -d postgres
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 5s
    ports:
      - ${KC_POSTGRES_PORT_MAPPING:-5435}:5432
    volumes:
      - postgres:/var/lib/postgresql/data
    deploy:
      resources:
        limits:
          memory: 256M

  keycloak:
    image: quay.io/keycloak/keycloak:20.0.5
    container_name: keycloak
    restart: unless-stopped
    command:
      - start --auto-build --db postgres --hostname-strict-https false 
        --hostname-strict false --http-enabled true --import-realm 
        --spi-login-protocol-openid-connect-suppress-logout-confirmation-screen=true 
        --spi-login-protocol-openid-connect-legacy-logout-redirect-uri=true 
        --spi-user-profile-legacy-user-profile-read-only-attributes *_RES_ACCESS_MODE
    environment:
      KC_DB_URL: jdbc:postgresql://keycloak-postgres:5432/postgres
      KC_DB_USERNAME: postgres
      KC_DB_PASSWORD: postgres
      KC_DB_SCHEMA: public
      KC_FEATURES: preview
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    ports:
      - 8282:8080
    depends_on:
      keycloak-postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://0.0.0.0:8080/realms/master"]
      start_period: 10s
      interval: 30s
      retries: 3
      timeout: 5s

volumes:
  postgres:

выполнить запуск командой:

sudo docker compose up -d

после запуска контейнера следует дождаться полного старта сервиса и убедиться, что он находиться в состоянии "healthy":

$ sudo docker compose ps
NAME                IMAGE                              COMMAND                  SERVICE             CREATED             STATUS                PORTS
keycloak            quay.io/keycloak/keycloak:20.0.5   "/opt/keycloak/bin/k…"   keycloak            2 days ago          Up 2 days (healthy)   8443/tcp, 0.0.0.0:8282->8080/tcp, :::8282->8080/tcp
postgres            library/postgres:15                "docker-entrypoint.s…"   keycloak-postgres   2 days ago          Up 2 days (healthy)   0.0.0.0:5435->5432/tcp, :::5435->5432/tcp

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

Настройка Keycloak

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

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

Данные для входа указаны в конфигурации docker-compose.yml в переменных окружения KEYCLOAK_ADMIN и KEYCLOAK_ADMIN_PASSWORD (по умолчанию admin / admin).

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

Создание Realm

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

Для одного комплекса SoftWLC достаточно одного realm.

Для создания нового realm требуется нажать на список с выбором текущего realm (сразу после старта сервиса будет выбран единственный realm "master") и в открывшемся меню нажать кнопку "Create Realm":

В параметрах при создании нового realm достаточно указать только его имя. Имя может быть произвольным, здесь и в дальнейшем будет использовано имя realm "softwlc".

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

Создание Clients

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

Для настройки взаимодействия сервисов SoftWLC с Keycloak потребуется создать три clients:

• wifi-cab - для взаимодействия с ЛК;
• portal-constructor - для взаимодействия с КП;
• ems - для взаимодействия с EMS.

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

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

В открывшемся окне вводим в поле "Client ID": "wifi-cab" и нажимаем клавишу "Next":

В следующем окне включаем настройку "Client authentication" и контролируем, что включена "Authentication flow": "Standard flow":

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

Откроются дополнительные настройки. Во вкладке "Settings" задаем параметр "Valid redirect URIs": "http://<IP-адрес сервера SoftWLC>:8080/wifi-cab/sso":

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

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

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

В открывшемся окне вводим в поле "Client ID": "portal-constructor" и нажимаем клавишу "Next":

В следующем окне включаем настройку "Client authentication", контролируем, что включена "Authentication flow": "Standard flow":

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

Откроются дополнительные настройки. Во вкладке "Settings" задаем параметр "Valid redirect URIs": "http://<IP-адрес сервера SoftWLC>:8080/epadmin/sso":

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

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

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

В открывшемся окне вводим в поле "Client ID": "ems" и нажимаем клавишу "Next":

В следующем окне НЕ включаем настройку "Client authentication", контролируем, что включена "Authentication flow": "Standard flow":

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

Откроются дополнительные настройки. Во вкладке "Settings" задаем параметр "Valid redirect URIs": "http://localhost":

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

Настройка mappers

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

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

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

Для добавления атрибутов переходим в realm "softwlc", открываем client "wifi-cab" и открываем вкладку "Client scopes":

В данной вкладке открываем "Assigned client scope" и нажимаем "wifi-cab-dedicated":

Нажимаем кнопку "Configure a new mapper":

Выбираем в колонке "Name" "User Attribute".

В открывшемся окне заполняем поля названием атрибута (в приведенном примере Eltex-User-Role):

"Name" : "Eltex-User-Role"

"User-Attribute": "Eltex-User-Role"

"Token Claim Name": "Eltex-User-Role"

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

Аналогично добавляем атрибуты "User-Name" и "Eltex-User-Timezone".

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

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

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

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

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

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

Домен пользователя определяется настройками роли. Настройка атрибутов выполняется в clients "ems".

Последовательность действий при добавлении мапперов аналогична ЛК и КП. Состояние мапперов для client "ems" после настройки:

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

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

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

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

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

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

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

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

в поле name указать имя группы "wifi-cab" и нажать кнопку "Create".

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

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

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

нажать "Create group".

В открывшемся окне ввести имя группы "default_provider". Имя группы может быть любым, рекомендуется использовать имя, совпадающее с названием роли в ЛК/EMS:

и нажать кнопку "Create".

После создания подгруппы раскрываем группу "wifi-cab" и нажимаем на ранее созданную подгруппу "default_provider":

Вводим:

• "Key": "Eltex-User-Role"
• "Value": "default_provider"

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

После сохранения автоматически внизу добавиться новая строка для ввода следующего значения. Аналогичным образом добавим значения для атрибутов "Eltex-Domain" и "Eltex-User-Timezone". После этого список атрибутов примет вид:

Аналогичным образом создаем подгруппу и настраиваем ее для КП. Итоговый вид:

Так же создаем подгруппу "SuperUser" для группы "ems" и добавляем в нее необходимые атрибуты:

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

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

Для добавления пользователя необходимо открыть realm "softwlc" и нажать "Users":

В открывшемся окне нажать кнопку "Create new user" и ввести в поле "Username" имя пользователя (в приведенном примере user):

нажать кнопку "Create".

После создания пользователя автоматически откроются его свойства (User details), в них переходим на вкладку "Attributes":

Вводим:

• "Key": "User-Name"
• "Value": "user"

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

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

вводим и подтверждаем пароль, нажимаем кнопку "Save".

Переходим на вкладку Groups и нажимаем кнопку "Join Group", раскрываем группу "wifi-cab" и выбираем подгруппу "default_provider":

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

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

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

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

Документация Keycloak по настройке интеграции с LDAP.

Интеграция с LDAP может иметь разную конфигурацию и при необходимости можно выбрать иные настройки.

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

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

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

Откроем realm "softwlc" и перейдем на вкладку "User federation":

В открывшейся вкладке нажимаем на кнопку "Add Ldap providers" и заполняем параметры взаимодействия с LDAP:

В настройках "Connection URL", "Bind DN", "Bind credentials", "Users DN" необходимо указать параметры подключения к определенному LDAP, в приведенном примере приведены тестовые данные.

После выполнения настроек нажимаем кнопку "Save".

После сохранения настроек рекомендуется проверить соединение и возможность подключения к LDAP со стороны Keycloak:

• для проверки соединения необходимо в разделе "Connection and authentication settings" нажать на кнопку "Test connection";
• для проверки аутентификации под используемой УЗ надо нажать на кнопку "Test authentication".

В случае успешного подключения вверху справа появиться сообщение 

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

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

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

• Добавление пользователей из LDAP в Keycloak
• Добавление пользователей LDAP в группы Keycloak
• Добавление нужных атрибутов в рамках Keycloak

Откроем созданный коннект подключения к LDAP и в нем перейдем во вкладку "Mappers":

Нажмем на кнопку "Add mapper". В открывшемся окне введем:

• Name: "group-mapper"
• Mapper type: выберем "group-ldap-mapper" - после этого раскроется полный список параметров настройки:

настроим параметры:

• LDAP Groups DN: "ou=eltexGroups,ou=eltex.dc=eltex,dc=loc" - пространство, где будем выполняться поиск групп;
• Group Name LDAP: "cn" - название параметра, где указано имя группы;
• Group Object Classes: "posixGroup" - название параметра, указывающего признак группы;
• Preserve Group Interface: отключить;
• Ignore Missing Groups:  включить игнорирование отсутствующих групп;
• Membership LDAP Attribute: "memberUid" - название параметра, указывающего признак вхождения в группу;
• Membership Attribute Type: "UID"  - указывает каким типом добавлен пользователь в группу;
• Membership User LDAP Attribute: "uid" - имя пользователя в LDAP по которому идет маппинг в группу.

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

После сохранения настроек переходим в добавленный LDAP, раскрываем меню справа вверху и выбираем "Sync all users":

В случае успешной синхронизации вверху справа появиться сообщение вида: .

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

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

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

Выполним настройку для client "wifi-cab". Для этого откроем "Clients" - "wifi-cab" - "Client scopes" - "wifi-cab-dedicated" - атрибут "User-Name":

заменим значение "User Attribute" на "firstName" и нажмем кнопку "Save".

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

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

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

На примере группы wifi-cab: нажимаем "Groups" - "wifi-cab" переходим в подгруппу "default_provider" - "Members" и нажимаем кнопку "Add member":

выбираем пользователя "eltex" (в приведенном примере данные пользователи импортированы из LDAP) и нажимаем кнопку "Add".

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

Настройка NBI

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

# SSO settings
sso.enabled=true
sso.clientSecret=
sso.clientId=

# SSO REST
sso.rest.server.protocol=http
sso.rest.server.address=<IP-адрес сервера Keycloak>
sso.rest.server.port=8282
sso.rest.server.timeout.sec=10
# possible value for sso.rest.protocol.provider are "rtk", "keycloak"
sso.rest.protocol.provider=keycloak
#the "version" settings only matter when "provider=rtk"
sso.rest.protocol.version=2.0
#the "username" settings only matter when "provider=rtk"
sso.rest.username=
#the "password" settings only matter when "provider=rtk"
sso.rest.password=

# SSO SETTINGS
sso.rest.getToken.path=/realms/softwlc/protocol/openid-connect/token
sso.rest.getUserInfo.path=/realms/softwlc/protocol/openid-connect/userinfo

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

• sso.enabled=true - включение возможности входа по SSO
• sso.rest.server.address=<IP-адрес сервера Keycloak>
• sso.rest.server.port=8282 - порт сервера Keycloak, по умолчанию 8282
• sso.rest.protocol.provider=keycloak - тип используемого SSO сервера - "keycloak"
• sso.rest.getToken.path=/realms/softwlc/protocol/openid-connect/token - после /realm/ необходимо указать имя realm, как оно создано в Keycloak
• sso.rest.getUserInfo.path=/realms/softwlc/protocol/openid-connect/userinfo - после /realm/ необходимо указать имя realm, как оно создано в Keycloak

Выполнить рестарт сервиса:

sudo systemctl restart tomcat8

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

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

    <!-- 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/softwlc/protocol/openid-connect/token</entry>
    <entry key="sso.rest.getUserInfo.path">/realms/softwlc/protocol/openid-connect/userinfo</entry>

• <entry key="sso.enabled">true</entry> - включение возможности входа по SSO
• <entry key="sso.redirectUri">http://IP-адрес ЛК:8080/wifi-cab/sso</entry> - адрес ЛК для обратного редиректа. Данная настройка должна совпадать с настройкой указанной в realm в разделе Settings в параметре Valid redirecr URLs.
• <entry key="sso.clientSecret">HoDKUreDl0xmjUgV7p19YADAT5fvtOOG</entry> - secret, необходимый для взаимодействия с realm. Находится в настройках клиента wifi-cab " в разделе Credentials" в поле "Client secret".

• <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/softwlc/protocol/openid-connect/token</entry> - после /realm/ необходимо указать имя realm, как оно создано в Keycloak
• <entry key="sso.rest.getUserInfo.path">/realms/softwlc/protocol/openid-connect/userinfo</entry> - после /realm/ необходимо указать имя realm, как оно создано в Keycloak

Другие параметры SSO не требуют изменений.

Выполнить рестарт сервиса:

sudo systemctl restart eltex-wifi-cab

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

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

sso {
    enabled = true

    # enable or disable local login
    localLoginAllowed = true

    # rtk, keycloak
    provider = keycloak

    # Must be in double quotes. Only for 'rtk' provider
    version = "1.0"

    rest {
        scheme = http
        host = <IP-адрес сервера Keycloak>
        port = 8282
        sso_api_path = /realms/softwlc/protocol/openid-connect
    }
    auth {
        scheme = http
        host = <IP-адрес сервера Keycloak>
        port = 8282
        authentication_path = /realms/softwlc/protocol/openid-connect/auth
        logout_path = /realms/softwlc/protocol/openid-connect/logout
    }


    params {
        client_id = portal-constructor
        # URL of epadmin, URL must be in double quotes (!!!)
        redirect_uri = "http://<IP-адрес КП>:8080/epadmin/sso"
        client_secret = N0F5T5QIFed7629AYqGTDNzD0eseVFZH
    }
}

• enabled = true - включение возможности входа по SSO
• localLoginAllowed = true - разрешение локальной аутентификации в КП (для запрета надо указать "false")
• provider = keycloak - тип используемого SSO сервера - "keycloak"
• scheme = http - использовать http протокол
• host = <IP-адрес сервера Keycloak> - адрес сервера Keycloak
• port = 8282 - порт сервера Keycloak (по умолчанию 8282)
• sso_api_path = /realms/softwlc/protocol/openid-connect - после /realm/ необходимо указать имя realm, как оно создано в Keycloak
• authentication_path = /realms/softwlc/protocol/openid-connect/auth - после /realm/ необходимо указать имя realm, как оно создано в Keycloak
• logout_path = /realms/softwlc/protocol/openid-connect/logout - после /realm/ необходимо указать имя realm, как оно создано в Keycloak
• client_id = portal-constructor - имя клиента, как оно указано в настройках Keycloak (Clients)

• redirect_uri = "http://<IP-адрес КП>:8080/epadmin/sso" - адрес КП для обратного редиректа. Данная настройка должна совпадать с настройкой, указанной в realm в разделе Settings в параметре Valid redirecr URLs.

  Настройка обязательно должна указываться в кавычках!

• client_secret = N0F5T5QIFed7629AYqGTDNzD0eseVFZH - secret, необходимый для взаимодействия с realm. Находиться в настройках realm portal-constructor "Credentials" в поле "Client secret".

Выполнить рестарт сервиса:

sudo systemctl restart eltex-portal-constructor

Настройка EMS

Настройка взаимодействия с Keycloak выполняться в файле конфигурации "/usr/lib/eltex-ems/conf/system-config.txt" в разделе:

# sso
sso.enabled=true
sso.provider=keycloak
sso.callback-host=localhost
sso.callback-port=45969
sso.keycloak.realm=softwlc
sso.keycloak.auth-server-url=http://<IP-адрес сервера keycloak>:8282
sso.keycloak.ssl-required=external
sso.keycloak.resource=ems
sso.keycloak.public-client=true
sso.keycloak.use-resource-role-mappings=true
sso.keycloak.enable-pkce=true

• sso.enabled=true - включение возможности входа по SSO
• sso.provider=keycloak - тип используемого SSO сервера - "keycloak"
• sso.callback-host=localhost - без изменений
• sso.callback-port=45969 - без изменений
• sso.keycloak.realm=softwlc - имя realm, взаимодействие с которым настроено в Keycloak
• sso.keycloak.auth-server-url=http://<IP-адрес сервера keycloak>:8282 - адрес сервера Keycloak:порт
• sso.keycloak.ssl-required=external - без изменений
• sso.keycloak.resource=ems - имя клиента, как оно указано в настройках Keycloak (Clients)
• sso.keycloak.public-client=true - без изменений
• sso.keycloak.use-resource-role-mappings=true - без изменений
• sso.keycloak.enable-pkce=true - без изменений

Выполнить рестарт сервиса:

sudo systemctl restart eltex-ems

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

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

Если данное сообщение появляется при попыке войти в административную консоль 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 командами:

curl http://<IP-адрес сервера keycloak>:8282/realms/softwlc/.well-known/openid-configuration
curl http://<IP-адрес сервера keycloak>:8282/realms/softwlc/protocol/openid-connect/certs

Так же проверить из браузера с ПК пользователя доступность сервера Keycloak.

В случае недоступности по указанным ссылкам сервера Keyclok необходимо провести диагностику сетевой связности, ограничения устанавливаемые файрволом на сети.

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

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

1. Если при попытке аутентификации пользователя в логах наблюдаются ошибки вида:

2023-04-04T19:12:00,928 [qtp1949709901-22666] ERROR default WiFiCustomerSsoServlet.handleGetUserInfoResponse(line:301). Attributes were not found or they are incorrect: [Eltex-User-Role]

то это говорит о том, что есть проблема с определенным атрибутом. Необходимо проверить его присутствие и корректность настройки в мапперах в "clients - wifi-cab", проверить настройки атрибутов группы и пользователя.

2. Если в логах наблюдается ошибка вида:

2023-04-04T19:19:40,214 [qtp1949709901-20961] ERROR default WiFiCustomerSsoServlet.handleGetUserInfoResponse(line:301). Attributes were not found or they are incorrect: [Eltex-Domain]

и при этом атрибут "Eltex-Domain" везде настроен - необходимо проверить в настройках атрибута в мапперах "clients - wifi-cab" включено ли для него свойство "Multivalued".

3. Если в логах наблюдается ошибка вида:

2023-04-04T19:24:05,122 [qtp1949709901-20961] ERROR default SsoKeycloakAccessControl.signIn(line:46). Authorization error message from NBI: Ошибка получения списка системных ролей
ERR209: Auth-роль 'default_platform_admin1' не существует

это означает, что выдаваемая пользователю системная роль не существует. Необходимо проверить значение атрибута "Eltex-User-Role" и соответствие его реально существующей роли в ЛК.

4. Если в логах наблюдается ошибка вида:

2023-04-10T09:34:27,789 [qtp1201991394-33] ERROR default WiFiCustomerSsoServlet.authAfterRedirect(line:279). Failed with token request. Response: {"error_description":"Invalid client or Invalid client credentials","error":"unauthorized_client"}; code: 401

то необходимо проверить в файле настроек ЛК значение параметра "sso.clientSecret" - совпадает ли его значение со значение в настройке realm wifi-cab "Credentials" в поле "Client secret".

5. Если в логах наблюдается ошибка вида:

2023-04-10T10:01:23,158 [qtp421293587-33] ERROR default WiFiCustomerSsoServlet.authAfterRedirect(line:279). Failed with token request. Response: {"error":"Protocol not found"}; code: 404

а в браузере пользователь сразу видит ошибку вида "The page isn't redirecting properly"  - необходимо проверить корректность параметра "sso.rest.getToken.path" в файле настроек ЛК: проверить правильность имени realm, наличие лишних символов.

Если пользователь видит данную ошибку после ввода логина / пароля на сервере Keycloak - необходимо проверить корректность параметра "sso.rest.getToken.path" в файле настроек ЛК: проверить правильность имени realm, наличие лишних символов.

6. Если при авторизации на странице Keycloak появляется ошибка вида:

то необходимо проверить корректность значения параметров ЛК: "sso.redirectUri" и "sso.clientId". Так же необходимо проверить в настройках Keycloak во вкладке "Settings" для Client "wifi-cab" корректность параметра "Valid redirect URIs".

7. Если при авторизации на странице Keycloak появляется ошибка вида:

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

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

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

1. Если при попытке аутентификации пользователя в логах наблюдается:

2023-04-04T19:32:50,697 [qtp1959910454-503] ERROR org.eltex.portal.admin.auth.sso.strategies.KeyCloakSsoAuthorization KeyCloakSsoAuthorization.authorize(line:111). Role not found or invalid. Check Eltex-User-Role attribute

то необходимо проверить наличие и корректность настройки маппинга атрибута в мапперах "clients - portal-constructor", проверить настройки атрибутов группы и пользователя.

2. Если в логах наблюдается ошибка вида:

2023-04-04T19:37:43,466 [qtp1959910454-66] ERROR org.eltex.portal.admin.auth.sso.strategies.KeyCloakSsoAuthorization KeyCloakSsoAuthorization.authorize(line:136). There are no scopes for user or value is invalid. Check Eltex-Domain attribute

и при этом атрибут "Eltex-Domain" везде настроен - необходимо проверить в настройках атрибута в мапперах "clients - portal-constructor" включено ли для него свойство "Multivalued".

3. Если при попытке авторизации пользователь видит в браузере:

а в логах КП наблюдаются сообщения вида:

2023-04-10T11:05:38,654 [qtp1664576493-34] ERROR org.eltex.portal.admin.auth.sso.strategies.SsoAuthorization SsoAuthorization.getTokenPairByCode(line:119). org.springframework.web.client.HttpClientErrorException$NotFound: 404 Not Found: [{"error":"HTTP 404 Not Found"}]
2023-04-10T11:05:38,655 [qtp1664576493-34] ERROR org.eltex.portal.admin.auth.sso.strategies.SsoAuthorization SsoAuthorization.getUserInfoByAuthCodeFlow(line:149). Can't get token pair

то необходимо проверить корректность значения параметра настроек КП "sso_api_path": корректность имени используемого "Realm" (в приведенной инструкции "softwlc"), корректность введенной строки, отсутствие лишних символов.

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

2023-04-10T11:27:12,402 [qtp1664576493-34] ERROR org.eltex.portal.admin.auth.sso.strategies.SsoAuthorization SsoAuthorization.getTokenPairByCode(line:119). org.springframework.web.client.HttpClientErrorException$Unauthorized: 401 Unauthorized: [no body]
2023-04-10T11:27:12,402 [qtp1664576493-34] ERROR org.eltex.portal.admin.auth.sso.strategies.SsoAuthorization SsoAuthorization.getUserInfoByAuthCodeFlow(line:149). Can't get token pair

то необходимо проверить корректность значения параметра настроек КП "client_secret" и соответствие его настройке в Keycloak realm "wifi-cab" "Credentials" в поле "Client secret".

5. Если при попытке авторизации пользователь видит в браузере:

и в логах КП наблюдаются сообщения вида:

2023-04-10T11:12:11,724 [pool-2-thread-1] ERROR org.eltex.logging.client.LogServiceClient LogServiceClient.lambda$sendAsync$0(line:271). Failed to send message with code: UNAVAILABLE

то необходимо проверить корректность значения параметра настроек КП "authentication_path": корректность имени Realm, корректность введенной строки, отсутствие лишних символов.

Если данное сообщение наблюдается при выходе пользователя из КП - необходимо проверить корректность значения параметра настроек КП "logout_path".

6. Если при попытке авторизации пользователь видит в браузере:

то необходимо проверить в настройках КП параметры "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".

1. Если при попытке аутентификации пользователь видит:

2023-04-05T19:02:56,077 [GuiHandler2v_0] INFO  Kernel ObjectHandler.handleCommand(line:215). Error: command = [ Command: action = AUTH_SSO_USER; objectType = SYSTEM; sessionId = -1; guiModuleId = null; clientInetAddress = 100.110.0.150; addToResponse = false; needLogs = true; function = Function{mode=USER, type=LOGIN, objId=-1, treeObj=null, tabName='AUTH_USER', methodName='AUTH_USER', description='Авторизация', object=null, processId='null', logs=null}; commandId = CMD:AUTH_SSO_USER_admin_SYSTEM_2023-04-05_19:02:55.345; additionalCommands.size = 0 ], пользователь не существует

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

2. Если в логах наблюдается ошибка:

2023-04-05T19:14:32,479 [GuiHandler2v_0] INFO  Kernel ObjectHandler.handleCommand(line:215). Error: command = [ Command: action = AUTH_SSO_USER; objectType = SYSTEM; sessionId = -1; guiModuleId = null; clientInetAddress = 100.110.0.150; addToResponse = false; needLogs = true; function = Function{mode=USER, type=LOGIN, objId=-1, treeObj=null, tabName='AUTH_USER', methodName='AUTH_USER', description='Авторизация', object=null, processId='null', logs=null}; commandId = CMD:AUTH_SSO_USER_admin_SYSTEM_2023-04-05_19:14:32.418; additionalCommands.size = 0 ], Аутентификация из GUI роли SuperUser1

то необходимо проверить соответствие системной роли выдаваемой пользователю в настройках Keycloak и ее наличия в EMS.

3. Если при попытке зайти пользователь видит:

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

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

4. Если при попытке зайти в EMS в браузере открывается страница Keycloak, но в ней отображается ошибка вида:

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

Eltex-radius-NBI

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

Взаимодействие с данным сервисом выполняются ЛК, КП и EMS. Он не имеет своего client в keycloak, поэтому при возникновении ошибок необходимо в первую очередь проверить корректность настроек приложений, которые обращаются к нему.

1. Если в приведенном ниже логе:

2023-04-05T19:29:49,831 [http-nio-8080-exec-10] ERROR Kernel Northbound.handle(line:246). Failed. commander GetAuthRoleCmd; request [AUTH_ROLE: test223, CLIENT_NAME: test tester, LOCALE: ru_RU, CLIENT_IP: 100.123.0.2]
org.eltex.radius.nbi.exception.EltexException: Auth-роль 'test' не существует

то необходимо проверить присутствие и корректность настройки в мапперах атрибута "Eltex-User-Role" в "clients - wifi-cab", так же проверить настройки данного атрибута в группе пользователя и его наличие данной роли в ЛК.

2. Если в логах наблюдается ошибка вида:

2023-04-10T13:37:01,039 [http-nio-8080-exec-9] ERROR Kernel SSOTools.handleGetUserInfoResponse(line:51). Failed with user info request. Response: {"error":"HTTP 404 Not Found"}; code: 404

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

Приложения

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