Keycloak

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

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

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

auth keycloack2

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

  • Client type: openid-connect

  • Client ID: vision-core-client

auth keycloack1

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

  • Client authentication: ON

  • Authorization: OFF

  • Standard Flow: ON

  • Direct Access Grants: ON

  • Implicit Flow: OFF

auth keycloack3

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

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

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

Вкладка «Settings»

auth keycloack4

На вкладке 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.

auth keycloack5

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

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

  • obj_model — администратор объектной модели;

  • role_model — администратор информационной безопасности;

  • vsn_config — администратор конфигурации Визиона, также администратор Grafana.

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

Вкладка «Credentials»

auth keycloack6

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

  • Client Authenticator: Client Id and Secret.

  • Client secret.

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

  • Client ID;

  • Client secret.

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

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

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

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

    auth keycloack7

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

    auth keycloack8

  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
Таблица 1. Параметры запуска скрипта
Параметр Описание Значение по умолчанию

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 создать технического пользователя, учётная запись которого будет использована для получения списка пользователей и ролей, и задать для него пароль.

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

auth rm keycloak 1

В конфигурационном файле Визион требуется задать параметры для сервиса 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.

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