Keycloak
Примечание
Инструкция подготовлена на примере Keycloak версии 20.0.2.

Настройка Keycloak#

  1. Создание клиента.
  2. Настройка параметров клиента.
  3. Назначение ролей пользователей.
  4. Конфигурация Визиона для работы с Keycloak.

Создание клиента#

Необходимо выбрать пространство vision.

Перейти в раздел Clients и нажать на кнопку Create client. Заполнить поля следующими значениями:

  • Client type: openid-connect
  • Client ID: vision-core-client

Перейти на следующую страницу при помощи кнопки Next. Выбрать параметры:

  • Client authentication: ON
  • Authorization: OFF
  • Standard Flow: ON
  • Direct Access Grants: ON
  • Implicit Flow: OFF

Для завершения создания клиента необходимо нажать на кнопку Save.

Настройка параметров клиента#

После создания клиента откроется страница Client details.

Вкладка «Settings»#

На вкладке Settings в подразделе Access settings необходимо указать адреса приложения:

  • Root URL: https://<ip_vision_vm>.

  • Home URL (Base URL в ранних версиях): https://<ip_vision_vm>.

  • Valid Redirect URIs:

    • https://<ip_vision_vm>/vision/api/v1/auth/login
    • https://<ip_vision_vm>/vision/api/v1/auth/login-grafana

  • Web Origins: https://<ip_vision_vm>.

  • Admin URL: https://<ip_vision_vm>.

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

Вкладка «Roles»#

Необходимо создать роли администратора клиента, которые затем можно назначать пользователям Keycloak. Имена ролей чувствительны к регистру. Для создания роли необходимо нажать на кнопку Create role.

Необходимо создать следующие роли:

  • obj_model — администратор объектной модели;
  • role_model — администратор информационной безопасности;
  • vsn_config — администратор конфигурации Визиона, также администратор Grafana.

Также можно создать пользовательские роли. Распределение их полномочий производится после их добавления в Визион. Управление ролевой моделью Визион описано в Руководстве Администратора .

Вкладка «Credentials»#

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

  • Client Authenticator: Client Id and Secret
  • Client secret: *****

При конфигурации Визиона для работы с Keycloak потребуются следующие данные клиентов:

  • Client ID
  • Client secret

Назначение ролей пользователям#

Порядок действий для назначения роли пользователям:

  1. Необходимо перейти в раздел Users

  2. Выбрать пользователя или создать нового при помощи кнопки Add user

  3. Перейти во вкладку Role mapping и нажать на кнопку Assign role

  4. Нажать на выпадающий список фильтра и выбрать Filter by clients

  5. Отметить необходимые роли и нажать на кнопку Assign

Конфигурация Визиона для работы с Keycloak#

Необходимо изменить параметры файла конфигурации Визиона /opt/skala-r/etc/vision/server/vision_core/config.yml.

В ключе “auth” необходимо указать:

  • enabled - установить значение true
  • auth_type - keycloak
  • auth_server - URL Keycloak, например https://192.168.1.1:8080.
  • admin_server - для Keycloak указывается тот же URL что и для auth_server, например https://192.168.1.1:8080.
  • realm - имя пространства.
  • client_id - ID клиента в пространстве.
  • client_secret - значение является ключом из хранилища секретов. Не изменять.

Пример секции авторизации:

auth:
  enabled: true
  auth_type: keycloak
  auth_server: https://192.168.1.1:8080
  admin_server: https://192.168.1.1:8080
  realm: vision
  client_id: vision-core-client
  client_secret: vault.auth.client_secret

Необходимо указать реальное значение Client_secret клиента.

  1. Необходимо создать копию файла хранилища секретов:

    cp /opt/skala-r/vision/.secrets_vault /opt/skala-r/vision/.secrets_vault_bak

  2. Открыть хранилище секретов командой:

    ansible-vault edit /opt/skala-r/vision/.secrets_vault

    Для оперирования содержимым хранилища требуется ключ, выдаваемый разработчиком Визиона.

  3. Для ключа vault.auth.client_secret установить значение Client secret из раздела Credentials клиента.

  4. Сохранить файл и выполнить скрипт:

    /opt/skala-r/vision/tools/update_server_configs.sh

    vision_core будет перезапущен в процессе. Для применения настроек аутентификации к Grafana и переключения режима отображения дашбордов.

    • при выключенной аутентификации - дашборды доступны для просмотра всем
    • при включенной аутентификации - дашборды доступны для просмотра только назначенным ролям;

    Для включения/выключения аутентификации в Визионе необходимо запускать скрипт /opt/skala-r/vision/tools/update_server_configs.sh от пользователя root.

  5. Необходимо проверить успешный запуск vision_core командой:

    systemctl status vision_core.service

  6. Следует убедиться, что в логе нет ошибок после перезапуска:

    journalctl -fu vision_core -n 20

Обратите внимание на то, что при изменении настроек в /opt/skala-r/etc/vision/server/vision_core/config.yml и после перезапуска vision_core настройки в конфигурационном файле grafana не меняются. Конфигурирование grafana происходит после запуска скрипта /opt/skala-r/vision/tools/update_server_configs.sh.

Настройка Keycloak при помощи скрипта#

Необходимые условия для запуска скрипта#

  1. Успешная работа скрипта возможна в составе дистрибутива Визион, без переноса скрипта в иные среды.

  2. Запуск скрипта возможен только под пользователем с правами root.

  3. Для запуска необходима утилита jq. Утилита включена в поставку Визиона. Следует предварительно установить зависимости Визиона перед запуском скрипта, если данная утилита не установлена, либо установить ее вручную.

  4. Для запуска скрипта необходимы следующие данные:

    • адрес keycloak с протоколом (http, https)
    • id клиента cli администратора - по умолчанию admin-cli
    • данные учетной записи администратора keycloak (username, password)
    • имя создаваемого реалма Визиона
    • имя создаваемого клиента Визиона
    • значение секрета клиента Визиона
    • адрес сервера Визион

Значения по умолчанию#

В скрипте для некоторых аргументов подготовлены значения по умолчанию:

  • id клиента cli администратора - admin-cli
  • данные учетной записи администратора keycloak (username, password) - admin, admin
  • имя создаваемого реалма Визиона - vision
  • имя создаваемого клиента Визиона - vision-core-client
  • значение секрета клиента Визиона - генерируется при запуске, будет выведен в консоль

Примечание

  • Если пространство уже существует, скрипт продолжит работать с ним.
  • Если клиент уже существует, то работа скрипта будет завершена с ошибкой.

Параметры запуска скрипта#

Для запуска необходимо перейти в директорию auth/keycloak/ дистрибутива при помощи команды:

cd <vision-distrib-path>/auth/keycloak

Параметры запуска скрипта:

  • auth-server — адрес сервера Keycloak. Обязательный параметр.

  • admin-username — login администратора. По умолчанию admin.

  • admin-password — пароль администратора. По умолчанию admin.

  • admin-client-id — идентификатора клиента CLI администратора. По умолчанию admin-cli.

  • realm — название пространства. По умолчанию vision.

  • core-client-id — название клиента. По умолчанию vision-core-client.

  • core-client-secret — секрет клиента. При отсутствии будет сгенерирован.

  • vision-address — адрес сервера Визиона, например, https://192.168.190.190.

Результат работы скрипта#

Пример только с обязательными параметрами

./setup_keycloak.sh \
   --auth-server http://192.168.190.198:8180 \
   --vision-address https://192.168.190.196

Будут использованы следующие аргументы:
auth-server           :        http://192.168.190.198:8180
admin-username        :        admin
admin-password        :        admin
admin-client-id       :        admin-cli
realm                 :        vision
core-client-id        :        vision-core-client
core-client-secret    :        c0fe8c1f99055df8e84e9e2e650d7968
vision-address        :        https://192.168.190.196
====================================
 Конфигурирование реалма в keycloak
====================================
Проверка доступности keycloak...
Получение access_token...
Создание реалма - vision
Реалм создан.
Реалм доступен по следующей ссылке:
http://192.168.190.198:8180/auth/admin/master/console/#/realms/vision
Создание клиента в реалме - vision-core-client
Клиент создан.
Получение UUID клиента
UUID клиента 7bbb2017-ebfa-4e6a-9fef-2723493b0182
Добавление базовых ролей администраторов:
   Добавлена роль {"name": "vsn_config"}
   Добавлена роль {"name": "role_model"}
   Добавлена роль {"name": "obj_model"}
Успешно установлены следующие параметры:
realm                 :        vision
core-client-id        :        vision-core-client
core-client-secret    :        c0fe8c1f99055df8e84e9e2e650d7968

Настройка Keycloak и Визион для функционала автоматической рассылки уведомлений#

Необходимо в реалме master в Keycloak создать технического пользователя, учетная запись которого будет использована для получения списка пользователей и ролей и задать для него пароль.

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

В конфигурационном файле Визион требуется задать параметры для сервиса vision_iamsyncer.service, который запрашивает данные пользователей необходимые для рассылки у провайдера аутентификации и передает из в сервис vision_core.

Параметры:

  • iamsyncer_systemd_service - название сервиса, запрашивающего данные пользователей у провайдера аутентификации (изменять не требуется)
  • user_update_enabled - включение режима сбора данных пользователей (true) или выключение (false)
  • tech_auth_client_id - идентификатор клиента для сбора данных пользователей (изменять не требуется)
  • tech_auth_username - имя технического пользователя
  • tech_auth_password - ключ в secret vault, где хранится пароль технического пользователя
  • fetch_interval - интервал времени (в секундах), через который запускается каждый последующий процесс сбора данных пользователей.

Пример заполнения:

auth:
---
  iamsyncer_systemd_service: vision_iamsyncer.service
  user_update_enabled: true
  tech_auth_client_id: 'admin-cli'
  tech_auth_username: 'vision-api-reader'
  tech_auth_password: vault.auth.tech_auth_password
  fetch_interval: 3600

Пароль технического пользователя необходимо добавить в secrets_vault. Для этого необходимо открыть хранилище секретов командой:

ansible-vault edit /opt/skala-r/vision/.secrets_vault

Для ключа vault.auth.tech_auth_password установить значение пароля, заданного в разделе credentials технического пользователя.

После всех изменений необходимо рестартовать сервис Визион командой

systemctl restart vision_core

В случае, если в провайдере аутентификации произошли изменения и администратор не хочет ждать следующего запуска процесса сбора данных, можно рестартовать сервис vision_iamsyncer командой

systemctl restart vision_iamsyncer

Поведение Визиона при интеграции Keykloak с Active Directory#

Keycloak поддерживает интеграцию с Active Directory (далее AD). Ниже перечислены особенности, которые необходимо учитывать при работе Keycloak с AD.

  • при блокировке пользователя в AD - пользователь не может войти в Визион - будет возникать ошибка с указанием на неверные логин или пароль

  • при исключении из группы (или добавлении) в AD - данные в Keycloak обновятся при плановой синхронизации данных из AD

  • при исключении из всех групп связанных с ролями Визиона - отключение пользователя произойдет после синхронизации Keycloak с AD при новой попытке входа в систему (если в момент синхронизации была активная сессия, пользователь сможет пользоваться Визионом до истечения срока жизни токена)

  • Время отключения пользователя можно регулировать:

    • через включение параметра Periodic changed users sync и указания Changed users sync period в Keycloak в User federation → LDAP provider → Synchronization settings. Чем меньше значение, тем чаще будут синхронизироваться пользователи между AD и keycloak;

    • через изменение в Keycloak параметра Realm settings → Tokens → Access token → Access Token Lifespan, который управляет, как часто будут обновляться токен пользователя и его полномочия в виде ролей.

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