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:

  1. Авторизуйтесь в системе.
  2. Выберите нужное пространство в боковом меню.
    Чтобы создать новое, нажмите Create realm.
  3. В боковом меню перейдите в раздел 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.
  4. В боковом меню перейдите в раздел User:
    1. Создайте профили сотрудников. Заполните поля:
      • Username;
      • Email — если почта не была указана в профиле на стороне Keycloak, её потребуется указать при попытке авторизации в BILLmanager.
    2. Назначьте роли сотрудникам:
      1. Нажмите на имя сотрудника, чтобы открыть настройки его профиля.
      2. Перейдите на вкладку Role mapping → нажмите Assign role → установите Filter by client.

      3. Выберите нужные роли, соответствующие отделам в BILLmanager.

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

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

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

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

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

  1. Настройки интеграции:
    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 * * * (каждый день в два часа ночи). Если очистить поле, задание выполняться не будет.
  2. Настройки сопоставления отделов и Client Role:
    1. Нажмите кнопку Добавить.
    2. Отдел — выберите отдел в BILLmanager.
    3. Client Role — выберите роль в Keycloak.
    4. Нажмите кнопку Ок.
  3. Нажмите кнопку Ок, чтобы сохранить настройки.
  4. Чтобы загрузить данные в BILLmanager из Keycloack, нажмите Синхронизация пользователей.

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

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

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

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

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

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

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

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

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

Условия:

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

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

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

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

Условия:

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

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

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

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

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

Условия:

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

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

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

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

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

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