Инфраструктура Elph использует для авторизации пользователей Keycloak, одну из реализаций технологии Single Sign-On (SSO). Поэтому для добавления пользователя Elph необходимо добавить его в Keycloak. Keycloak — продукт с открытым кодом для реализации SSO с возможностью управления доступом. Keycloak поставляется совместно с Elph Chat Server, со всеми необходимыми настройками.  

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

Web-интерфейс Keycloak находится по адресу https://<ip-elph-proxy>/elph/auth/.
Для начала работы необходимо авторизоваться под учетной записью с правами администратора. После успешной авторизации будет отображена приветственная страница, в левой части которой расположено меню для управления различными объектами Keycloak.

Создание пользователей вручную

Для добавления пользователя необходимо выбрать домен, настроенный для работы с Elph. Этот домен должен соответствовать домену на IP-АТС ECSS-10. Для этого перейдите в меню «Manage Realms» и выберите свой домен.

После выбора домена откроется приветственная страница: «Welcome to <имя вашего домена>».

Далее перейдите в меню «Users». На этой странице будут отображены все пользователи, добавленные в этом домене, поле для поиска пользователя по имени и кнопка для добавления пользователя.

Нажмите на кнопку — отобразится страница с полями ввода параметров пользователя:

• Username — обязательно;
• Email — не обязательно;

• First/Last/Middle name — не обязательно к заполнению, используется для отображения в Elph;

• Phone Number — обязательно;

• Avatar URL — не обязательно к заполнению, используется для отображения в Elph;

• Title — не обязательно к заполнению, используется для отображения в Elph;

• SIP настройки пользователя(в соответствии с настройками абонента ECSS-10):
  • SIP login — обязательно;
  • SIP Password — обязательно.

Аватары пользователей можно хранить в корне папки /var/lib/ecss/ecss-elph-api/ на ECSS-10. Тогда в поле Avatar URL достаточно будет указать только имя файла. Также можно ссылаться на внешние источники, указывая прямую ссылку на изображение, например: http://eltex-co.ru/avatar.jpg. Поддерживаемые форматы: jpg, png, gif. Размеры и пропорции возможны любые, клиентское приложение само обрежет изображение под нужный размер. Рекомендуются квадратные изображения. Для удобства рекомендуется задавать такое же имя файла аватара, как и номер телефона пользователя, например 1001.jpg.

Заполните поля и нажмите кнопку .

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

Появятся поля для ввода пароля и переключатель «Temporary», при включении которого пользователь должен будет сменить свой пароль при следующем входе в систему.

Импорт пользователей из LDAP

Также можно настроить импорт пользователей из LDAP в Keycloak. Для этого необходимо перенастроить Elph Chat Server, указав следующие значения в .env файле:

• LDAP_HOST
• LDAP_CONNECTION_URL
• LDAP_BIND_DN
• LDAP_BIND_CREDENTIALS
• LDAP_PROVIDER_UI_DISPLAY_NAME
• LDAP_USERS_DN
• LDAP_USERNAME_ATTRIBUTE
• LDAP_USER_RDN_ATTRIBUTE
• LDAP_USER_UUID_ATTRIBUTE
• LDAP_USER_OBJ_CLASSES
• LDAP_CUSTOM_USER_FILTER

Пример:

LDAP_HOST="192.168.108.182"
LDAP_CONNECTION_URL="ldap://${LDAP_HOST}"
LDAP_BIND_DN="cn=admin,dc=testing,dc=local"
LDAP_BIND_CREDENTIALS="password"
LDAP_PROVIDER_UI_DISPLAY_NAME="myLDAP"
LDAP_USERS_DN="dc=testing,dc=local"
LDAP_USERNAME_ATTRIBUTE="uid"
LDAP_USER_RDN_ATTRIBUTE="uid"
LDAP_USER_UUID_ATTRIBUTE="entryUUID"
LDAP_USER_OBJ_CLASSES="inetOrgPerson,organizationalPerson"
LDAP_CUSTOM_USER_FILTER="(&(objectClass=inetOrgPerson)(mail=*)(telephoneNumber=*))"

Обратите внимание, что для работы с Elph у пользователей LDAP обязательно должны быть атрибуты:

• mail
• telephoneNumber
• avatarURL

После перенастройки .env файла необходимо перезапустить контейнеры ECSS Chat Server:

<path-to-install-script>/ecss-elph-chat-server.sh down
<path-to-install-script>/ecss-elph-chat-server.sh up

Процесс импорта можно отслеживать в логах контейнера keycloak-configurator:

docker logs elph-keycloak-configurator -f

После успешного импорта в Keycloak добавятся все пользователи из LDAP, а также будет обеспечена минимальная синхронизация между LDAP и Keycloak, а именно:

• синхронизация вновь добавленных пользователей;
• синхронизация пользователей при использовании поиска в меню «Users».

Синхронизация Elph Chat Server с Keycloak

Автоматическая синхронизация

По умолчанию Elph Chat Server синхронизирует БД пользователей с Keycloak каждые 10 минут. Вы можете включить/выключить синхронизацию или изменить интервал между синхронизациями. Для этого необходимо перенастроить Elph Chat Server, указав следующие значения в .env файле для docker-compose:

KEYCLOAK_ELPH_CHAT_SYNC_ENABLED=true
KEYCLOAK_ELPH_CHAT_SYNC_INTERVAL=10000 #значение в миллисекундах

После перенастройки .env файла необходимо перезапустить контейнеры ECSS Chat Server:

<path-to-install-script>/ecss-elph-chat-server.sh down
<path-to-install-script>/ecss-elph-chat-server.sh up

Ручная синхронизация

При необходимости вы можете вручную запустить синхронизацию с Keycloak с базой данных Elph Chat Server. Для этого необходимо:

Синхронизация базы данных Elph Chat Server с Keycloak

Для синхронизации необходимо чтобы на Elph Chat Server был создан пользователь admin.help.bot.

Включение admin.help.bot описано на странице «v. 2.12.0. Публичные настройки Chat Server».

В первую очередь необходимо авторизоваться как admin.help.bot с помощью POST запроса:

curl -X POST -H "Content-Type: application/json" -d \
'{"user": "admin.help.bot", "password": "password"}' \
-c cookies.txt \
https://<elph-proxy_ipaddress>/elph_chat/api/v1/login

Если у вас самоподписанный сертификат, необходимо отключить проверку сертификатов curl с помощью опции: -k
Результат:

{"status":"success","data":{"userId":"admin.help.bot","authToken":"your-auth-token","authTokenExpires":1765264202000,"me":{"_id":"admin.help.bot","roles":["admin","bot"],"active":true,"createdAt":"2025-12-08T02:36:45.559Z","type":"bot","preferences":[{"key":"showFolders","value":["c","a"]}],"name":"Система","username":"admin.help.bot","statusText":"Система Elph-chat","_updatedAt":"2025-12-09T06:09:58.023Z","avatarUrl":"avatars/systemuser.png"}}

После этого синхронизируем БД ECSS Chat Server с Keycloak:

curl -X POST -b cookies.txt \
https://<elph-proxy_ipaddress>/elph_chat/api/v1/keycloak.sync

Результат:

{"success":true}

При успешной синхронизации в поиске при создании чата пользователь начнет отображаться в формате: Имя@Номер.

Синхронизация базы данных ECSS Address book с Keycloak

Перейдите в контейнер address-book-server:

$ docker exec -it address-book-server bash

Перейдите в оболочку Erlang:

# ./ecss_address_book remote --name ecss_address_book

И выполните команду для запуска миграции Keycloak (дождитесь завершения процесса):

EcssAddressBookCore.Actions.KkImport.import

Общее количество импортируемых контактов можно посмотреть с помощью команды:

EcssAddressBookDb.Actions.Contacts.count(%{})

Чтобы выйти из оболочки Erlang и из контейнера, нажмите Ctrl-C два раза, затем Ctrl-D.

Подробнее про настройку ECSS Address Book с Keycloak на странице «Настройка режима авторизации».