Настройка интеграции Keycloak с TrueConf Server

Корпоративный мессенджер с видеосвязью TrueConf Server поддерживает беспарольную аутентификацию через технологию единого входа (Single Sign-On, SSO) с использованием Keycloak в качестве сервера авторизации. Для реализации этой схемы требуется предварительная интеграция Keycloak со службой каталогов (например, OpenLDAP или Active Directory) по протоколу LDAP.

В этой статье мы рассмотрим базовую установку Keycloak, а также подключим службу каталогов по LDAP и настроим интеграцию с TrueConf Server.

Установка Keycloak

Рекомендованные системные требования:

• Операционная система: Linux (с поддержкой JDK 17+), Windows (рекомендуется 10+ версия)
• Оперативная память: 2 ГБ
• Пространство жесткого диска: от 3 ГБ
• Поддерживаемые СУБД: PostgreSQL (рекомендуется), MySQL/MariaDB, Microsoft SQL Server, Oracle

Установку удобнее производить на вашем сервере LDAP/AD.

В данной статье рассмотрим нативную установку Keycloak на физическую машину. Для этого предварительно вам понадобится скачать и установить Java Development Kit (JDK).

Windows:

• После установки JDK запустите Powershell и объявите переменную JAVA_HOME с помощью команды (вместо "path_to_JDK" введите полный путь установки JDK):

[Environment]::SetEnvironmentVariable
("JAVA_HOME", "path_to_JDK", "Machine")

• Скачайте пакет Keycloak по ссылке.
• Распакуйте архив в удобную вам папку.
• Перезапустите Powershell и запустите сервер Keycloak с помощью команды:
cd path_to_keycloak\keycloak\bin .\kc.bat start-dev

1 2	cd path_to_keycloak\keycloak\bin .\kc.bat start-dev

Где path_to_keycloak – полный путь к файлу kc.bat.

Linux:

• После установки JDK объявите переменную запустите Powershell и объявите переменную JAVA_HOME:
• echo 'JAVA_HOME=""' | sudo tee /etc/default/keycloak-env
• Скачайте пакет Keycloak по ссылке.
• Распакуйте архив в удобную вам папку.
• Запустите сервер Keycloak:
cd path_to_keycloak\keycloak\bin .\kc.bat start-dev

1 2	cd path_to_keycloak\keycloak\bin .\kc.bat start-dev

Где path_to_keycloak – полный путь к файлу kc.bat.

Мы запускаем dev-режим, в котором удобнее проводить первичную пробную настройку из-за отсутствия необходимости настройки HTTPS и доменного имени.

Подробнее про конфигурацию и первичную настройку Keycloak, а также как использовать режим production вы можете прочитать в официальной документации сервера.

Откройте в браузере страницу http://HOST:PORT, где:

• HOST – адрес сервера (например, localhost);
• PORT – порт Keycloak (по умолчанию 8080).

На открывшейся странице нажмите Administration Console, после чего укажите логин и пароль для администратора (в dev-режиме Keycloak – admin / admin).

Интеграция Keycloak со службой каталогов по протоколу LDAP

Для настройки LDAP в разделе Configure зайдите в раздел User federation, в меню Add new provider выберите пункт LDAP.

Вы увидите страницу настройки интеграции LDAP, укажите в соответствующие поля следующие обязательные для интеграции данные:

• UI display name – название интеграции;
• Vendor – выберите семейство LDAP каталога (Active Directory, Red Hat Directory Server, Tivoli, Novell eDirectory, Other);
• Connection URL – ссылка на LDAP каталог;
• Bind DN – уникальное имя учётной записи, от имени которой выполняется привязка к каталогу;
• Bind credentials – пароль от учётной записи привязки;
• Edit mode – возможность вносить изменения в каталог LDAP (рекомендуем для первой настройки использовать READ_ONLY)
• Users DN – Уникальное имя контейнера (или поддерева), в котором находятся записи пользователей.

Остальные настройки оставьте по умолчанию (или введите свои если вы модифицировали свой каталог LDAP)

После указания параметров проверьте связь c каталогом и возможность аутентификации по кнопкам Test connection и Test authentication, затем сохраните их по кнопке Save.

Создание клиента в Keycloak

Создание Realm

Для создания корректной интеграции с TrueConf Server, вам необходимо создать realm trueconf в Keycloak:

• Нажмите на название выбранного realm (по умолчанию master).



• Выберите пункт Create realm.



• На странице создания в поле Realm name введите trueconf.



• В контекстном меню выбора realm нажмите trueconf.

Создание интеграции TrueConf Server

В панели управления вашим TrueConf Server перейдите в раздел Пользователи → Аутентификация, в группе Способы аутентификации нажмите кнопку Добавить.

В открывшемся окне выберите Keycloak, после чего введите название клиента trueconf:

После нажмите Сохранить.

Создание клиента (подключения к серверу Keycloak)

В разделе Manage → Clients и создайте новое приложение на кнопку Create client.

В поле Client ID введите название trueconf и затем нажмите кнопку Next.

На втором шаге Capability config отключите параметр Client authentication (обязательно) и Direct access grants (опционально), остальные настройки оставьте по умолчанию.

В разделе Login settings в поле Valid redirect URIs введите ссылку из поля Redirect URI в параметрах интеграции Keycloak на TrueConf Server, и сохраните по кнопке Save.

Настройка маппинга

После перейдите в раздел Client scopes и выберите profile, после чего перейдите на вкладку Mappers, выберите Add mapper и нажмите From predefined mappers.

В открывшемся окне выберите upn и нажмите Add.

Вернитесь на вкладку User federation, затем Mappers ⭢ Add mapper, задайте имя upn и выберите тип user-attribute-ldap-mapper из списка.

В поле User Model Attribute введите upn, в LDAP Attribute введите параметр который используется на вашем сервере (например uid, sAMAccountName, уточняйте в документации вашего LDAP вендора)

Настройка SSO в TrueConf Server

Для дальнейшей настройки SSO зайдите в Configure ⭢ Realm settings ⭢ Endpoints ⭢ OpenID Endpoint Configuration

В открывшемся JSON-файле найдите строки:

• "authorization_endpoint"
• "token_endpoint"
• "end_session_endpoint"

Вставьте полученные ссылки в соответствующие поля в настройке интеграции:

• "authorization_endpoint" — в URL формы авторизации
• "token_endpoint" — в URL для получения токена доступа
• "end_session_endpoint" — в URL для завершения сеанса

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

Готово! Теперь пользователи вашего сервера могут использовать Keycloak для входа на TrueConf Server. Для дальнейшей настройки рекомендуем обратиться к официальной документации Keycloak.