title: Keycloak
titleIcon: "fa-solid fa-eye"

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

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

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

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

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

Перейти на следующую страницу при помощи кнопки btn:[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.

Создайте роли администраторов Визион:

  • inventory — администратор инвентаря;

  • 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.

  • realm — имя пространства.

  • client_id — ID клиента в пространстве.

  • client_secret — значение является ключом из хранилища секретов. Не изменять.

Пример заполнения секции auth:

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

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

Параметр Описание Значение по умолчанию
admin-client-id ID клиента CLI администратора admin-cli
admin-password Пароль администратора admin
admin-username Имя пользователя администратора admin
auth-server Адрес Keycloak, обязателен —
core-client-id Название клиента vision-core-client
core-client-secret Секрет клиента. При отсутствии будет сгенерирован —
realm Название пространства vision
vision-address Адрес сервера Визиона

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

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

./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"}
   Добавлена роль {"name": "inventory"}
Успешно установлены следующие параметры:
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 — ключ в хранилище секретов, где хранится пароль технического пользователя.

  • fetch_interval — интервал времени (в секундах), через который запускается каждый последующий процесс сбора данных пользователей.

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

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

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

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

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

  • При изменении списка групп пользователя в AD данные в Keycloak обновятся при плановой синхронизации данных.

  • При исключении пользователя из всех групп, связанных с ролями Визиона, отключение пользователя произойдёт после синхронизации 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;

  • по истечении срока жизни активного токена;

  • при принудительной синхронизации Keycloak с AD.

Пока сессия активна, а срок действия токена не истёк, к пользователю будут применяться роли, назначенные ему на момент выдачи токена.