Авторизация через Keycloak (SSO)

Keycloak — ПО для авторизации по стандарту OAuth2. Подробнее см. документацию Keycloak.

С помощью модуля интеграции вы можете организовать авторизацию ваших сотрудников через Keycloak.

OAuth2 — протокол авторизации, который позволяет одному сервису выдать права на доступ к ресурсам пользователя на другом сервисе. Работа с пользователями и все проверки выполняются сервером авторизации. Сервером авторизации может выступать стороннее приложение, например, Google, Госуслуги (ЕСИА) и пр. или сервер с установленным ПО Keycloak.

Одновременная работа интеграций с LDAP и Keycloak не поддерживается. Если обе интеграции настроены в BILLmanager, сотрудник может зайти в систему при совпадении в LDAP и Keycloak и email, и логина. Если у пользователя при этом в LDAP и Keycloak не совпадают данные ФИО, то в BILLmanager они будут меняться при каждом запуске синхронизации модулей.

Настройка на стороне Keycloak

На стороне Keycloak необходимо:

выполнить настройку пользователя интеграции (Client);
создать роли (Client Role) для сопоставления с отделами в BILLmanager;
назначить роли профилям сотрудников (user).

Чтобы настроить Keycloak для интеграции с BILLmanager:

Авторизуйтесь в системе.
Выберите нужное пространство в боковом меню.
Чтобы создать новое, нажмите Create realm.
В боковом меню перейдите в раздел Clients:
1. Создайте пользователя для интеграции с BILLmanager. Для этого нажмите кнопку Create client:
  1. на вкладке General settings:
    1. Client type — выберите OpenID Connect.
    2. Client ID — укажите идентификатор. Это значение потребуется указать в настройках BILLmanager в качестве ID приложения.
    3. Нажмите Next.
  2. на вкладке Capability config:
    1. Client autentification — активируйте опцию.
    2. Service accounts roles — активируйте опцию.
    3. Нажмите Next.
  3. на вкладке Login settings:
    1. Root URL — укажите адрес BILLmanager в формате https://<billdomain>/billmgr.
    2. Нажмите Save.
2. Перейдите в редактирование созданного пользователя интеграции. Для этого нажмите на Client ID в таблице:
  1. Создайте роли для сопоставления с отделами в BILLmanager: перейдите на вкладку Roles → нажмите Create role.
    Создайте столько ролей, сколько отделов в вашем BILLmanager.
  2. Назначьте роли пользователю интеграции (client) в системе Keycloak: перейдите на вкладку Service accounts roles → кнопка Assign role → установите Filter by clients. Выберите:
    - view-users;
    - view-clients.
  3. Перейдите на вкладку Credentials → сохраните значение поля Client secret.
В боковом меню перейдите в раздел User:
1. Создайте профили сотрудников. Заполните поля:
  - Username;
  - Email — если почта не была указана в профиле на стороне Keycloak, её потребуется указать при попытке авторизации в BILLmanager.
2. Назначьте роли сотрудникам:
  1. Нажмите на имя сотрудника, чтобы открыть настройки его профиля.
  2. Перейдите на вкладку Role mapping → нажмите Assign role → установите Filter by client.
  3. Выберите нужные роли, соответствующие отделам в BILLmanager.

Настройка на стороне BILLmanager

Установка модуля

Чтобы установить модуль, перейдите в раздел Интеграция → Модули → Авторизация через Keycloak → кнопка Установить.

Настройка модуля

Чтобы открыть настройки, перейдите в раздел Интеграция → Модули → Авторизация через Keycloak → нажмите значок :

Настройки интеграции:
1. Keycloak API URL — укажите адрес REST API системы Keycloak.
2. Realm — укажите название пространства в Keycloak.
3. ID приложения — укажите Client ID в Keycloak.
4. UUID приложения — укажите client UUID в Keycloak. Вы можете взять эти данные из адресной строки при редактировании client в Keycloak. Нужное значение расположено между "clients/" и "/settings".
5. Защищённый ключ — укажите секретный ключ приложения (client secret) в Keycloak. Нужное значение находится в Keycloak в разделе Client → редактирование настроек клиента → вкладка Credentials.
6. Список IP-адресов — укажите список IP-адресов, с которых нужно разрешить авторизацию через Keycloak.
  Вы можете указать отдельные адреса — 123.45.67.89, адреса по маске — 123.45.67.0/24, либо диапазон адресов — 123.45.67.89-123.45.67.98.
  Для сотрудников, у которых есть привязка к Keycloak, указанные адреса также будут использованы для ограничения доступа к платформе.
7. Частота выполнения синхронизации — укажите частоту запуска задания cron по синхронизации пользователей. Значение по умолчанию — 0 2 * * * (каждый день в два часа ночи). Если очистить поле, задание выполняться не будет.
Настройки сопоставления отделов и Client Role:
1. Нажмите кнопку Добавить.
2. Отдел — выберите отдел в BILLmanager.
3. Client Role — выберите роль в Keycloak.
4. Нажмите кнопку Ок.
Нажмите кнопку Ок, чтобы сохранить настройки.
Чтобы загрузить данные в BILLmanager из Keycloack, нажмите Синхронизация пользователей.

Доступные действия с настройками сопоставления:

Редактирование — вы можете изменить роль Keycloack, с которой сопоставлен отдел в BILLmanager.
Удалить.

Включение авторизации

Чтобы включить в BILLmanager авторизацию через Keycloak, перейдите в раздел Провайдер → Провайдеры → выберите провайдера → кнопка Изменить → блок Способы регистрации и авторизации → активируйте опцию Keycloak.

После этого на форме авторизации в BILLmanager отобразится значок Keycloak.

Если в настройках модуля указаны разрешённые IP-адреса, значок авторизации через Keyloack будет отображен только при открытии страницы с разрешённого IP-адреса.

Логика работы

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

Авторизация сотрудника в BILLmanager через Keycloak

Условия:

учётная запись (user) сотрудника создана в Keycloak;
учётная запись сотрудника сопоставлена с ролью в Keycloak (для user в Keycloack установлена роль).

Как работает:

Сотрудник открывает страницу авторизации в BILLmanager.
Если в настройках указаны разрешённые IP-адреса, BILLmanager проверяет IP-адрес пользователя. Если IP-адрес входит в список, открывается страница с возможностью авторизоваться через Keycloack.
Сотрудник нажимает значок авторизации через Keycloak.
Открывается страница авторизации в Keycloak, на которой сотрудник вводит свои логин и пароль в системе Keycloak.
Keycloak проверяет учётные данные сотрудника.
Если учётные данные сотрудника введены верно, то Keycloak перенаправляет сотрудника BILLmanager.
BILLmanager проверяет наличие учётной записи сотрудника:
- если учётной записи сотрудника нет в BILLmanager, она будет выгружена из Keycloak. После чего сотрудник перенаправляется в BILLmanager.
- если учётная запись есть в BILLmanager, сотрудник перенаправляется в BILLmanager;
- если учётная запись сотрудника есть в BILLmanager и в Keycloak, но ранее сотрудник не заходил через Keycloak, то этот способ авторизации будет сохранён. Сотрудник перенаправляется в BILLmanager;
- если учётные данные сотрудника введены неверно, на странице авторизации Keycloak или BILLmanager будет отображено сообщение об ошибке.

Выгрузка новой учётной записи сотрудника в BILLmanager из Keycloak

Условия:

учётная запись (user) сотрудника создана в Keycloak;
учётная запись сотрудника сопоставлена с ролью в Keycloak (для user установлена clientRoles).

Как работает:

BILLmanager запрашивает список пользователей из Keycloak. Данные выгружаются при запуске задания синхронизации, либо при попытке авторизации пользователя Keycloak, которого ещё нет в системе BILLmanager.
BILLmanager отбирает новых пользователей.
BILLmanager создаёт новых пользователей, используя информацию из Keycloak. Права доступа назначаются в соответствии с указанным в сопоставлении отделом.

Выгрузка изменений записей сотрудников в BILLmanager из Keycloak

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

Условия:

учётная запись (user) сотрудника изменена в Keycloak;
учётная запись сотрудника есть в BILLmanager;
учётная запись сотрудника была выгружена из Keycloak в BILLmanager.

Как работает:

BILLmanager запрашивает список пользователей из Keycloak.
BILLmanager отбирает тех пользователей, в которых есть различия.
BILLmanager изменяет данные о пользователях, используя информацию из Keycloak.

Дополнительно

Лог-файлы взаимодействия BILLmanager с модулем интеграции Keycloak записываются в файлы:

/usr/local/mgr5/var/omkeycloak.log — запросы к Keycloak: получение токена авторизации, формирование ссылок для перехода в Keycloak, запрос ролей, запрос информации о пользователе;
/usr/local/mgr5/var/billmgr.log — информация об ошибках.