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

Центральный Пульт поддерживает авторизацию посредством сервера Keycloak.

Поддерживается интеграция только с Keycloak версии 21.1.1.

Настройка сервера

Для настройки взаимодействия между сервером системы Центральный Пульт и внешним сервером Keycloak необходимо получить хотя бы один из параметров:

Realm Certificate, которым сервер Keycloak подписывает пользовательские токены,
файл настроек соединения для Backend-клиента.

Настройка клиента и получение параметров осуществляются в консоли администратора Keycloak.

Realm Certificate

Для получения Realm Certificate необходимо:

Выбрать требуемую область (Realm) из списка (здесь - SAYMON):

Выбор области в Keycloak
В секции Realm settings на вкладке Tokens уточнить алгоритм подписи токенов в поле Default Signature Algorithm (здесь - RS256):

Выбор алгоритма подписи токенов
На вкладке Keys найти cертификат для данного алгоритма:

Вкладка Keys
Кнопка в соответствующей строке открывает искомый сертификат:

Сертификат ключа на вкладке Keys

Данные рекомендуется сохранить в файл keycloak_realm_certificate.

Backend-клиент

Клиенты - это параметры соединения с Keycloak-сервером для внешних приложений, которые авторизуют пользователей.

Главной особенностью Backend-клиента является наличие собственной аутентификации: такой клиент получает конфиденциальный доступ по секретному ключу.

Для настройки Backend-клиента необходимо:

Выбрать требуемую область (Realm) из списка (здесь - SAYMON):

Выбор области в Keycloak
В секции Clients нажать кнопку :

Секция Clients
Ввести имя Backend-клиента в поле Client ID:

Создание клиента, вкладка General Settings

и нажать кнопку .
Слайдер Client authentication установить в положение On:

Создание клиента, вкладка Capability config

и нажать кнопку .
B списке Action выбрать Download adapter config:

Кнопка Download adapter config
Нажать кнопку , чтобы получить файл настроек соединения для Backend-клиента в формате JSON:

Файл настроек соединения для Backend-клиента

Конфигурация сервера Центральный Пульт

Для взаимодействия с сервером Keycloak на сервере "Центральный Пульт" необходимо:

Добавить раздел Keycloak в конфигурационный файл сервера /etc/saymon/saymon-server.conf:

"keycloak": {
  "realm_certificate": "<данные keycloak_realm_certificate>",
  "realm_certificate_file": "/etc/saymon/keycloak_realm_certificate",
  "config_file": "/etc/saymon/keycloak_backend.json"
}

где:

realm_certificate - данные Keycloak Realm Certificate;
realm_certificate_file - путь к файлу с Keycloak Realm Certificate;

config_file - путь к файлу настроек соединения, сгенерированному сервером Keycloak для Backend-клиента.

Параметры перечислены в порядке понижения приоритета при одновременном указании. Для работы с Keycloak достаточно указать один из параметров.

Перезапустить службу saymon-server:
```
$ sudo service saymon-server restart
```

Настройка web-интерфейса

Для возможности авторизации пользователей посредством Keycloak через web-интерфейс системы Центральный Пульт необходимо получить файл настроек соединения Frontend-клиента.

Настройка клиента и получение файла настроек соединения осуществляются в консоли администратора Keycloak.

Frontend-клиент

Главной особенностью Frontend-клиента является отсутствие собственной аутентификации: данный клиент получает публичный доступ.

Для настройки Frontend-клиента необходимо:

Выбрать требуемую область (Realm) из списка (здесь - SAYMON):

Выбор области в Keycloak
В секции Clients нажать кнопку :

Секция Clients
Ввести имя Frontend-клиента в поле Client ID:

Создание клиента, вкладка General Settings

и нажать кнопку .
Слайдер Client authentication установить в положение Off:

Создание клиента, вкладка Capability config

и нажать кнопку .
На вкладке Settings в разделе Access settings указать корректные URI-адреса, с которых будет осуществляться доступ к Keycloak-серверу, и на которые будут перенаправляться пользователи после успешной аутентификации и выхода:

Раздел Access Settings

и нажать кнопку .
B списке Action выбрать Download adapter config:

Кнопка Download adapter config
Нажать кнопку , чтобы получить файл настроек соединения для Frontend-клиента в формате JSON:

Файл настроек соединения для Frontend-клиента

Конфигурация web-интерфейса системы Центральный Пульт

Для активации формы авторизации через Keycloak в web-интерфейсе системы необходимо:

Добавить на сервере системы Центральный Пульт раздел Authentication в конфигурационный файл клиента /etc/saymon/saymon-client.yaml:
```
authentication:
  availableMethods:
    - native
    - keycloak
  methodByDefault: keycloak
  services:
    keycloak:
      configUri: saymon.local/keycloak_frontend.json
      legacySupport: false
```
где:
- availableMethods - список доступных для пользователей методов аутентификации;
- methodByDefault - метод аутентификации, который будет предложен пользователю сразу при отображении аутентификационной формы;
- configUri - файл настроек соединения, сгенерированный сервером Keycloak для Frontend-клиента.
  
  Файл настроек соединения для Frontend-клиента необходимо поместить в каталог /etc/saymon.
Обновить страницу системы Центральный Пульт в web-браузере.