Интеграция СУСВ с внешним Keycloak

Модуль интеграции с внешним Keycloak входит в состав интерфейса РОСА Виртуализация и доступен по умолчанию после установки Системы. Установка отдельного дистрибутива или выполнение дополнительных шагов для подключения модуля не требуется.

Для перехода к настройкам интеграции с внешним Keycloak нужно открыть веб-интерфейс Cockpit на виртуальной машине менеджера виртуализации по адресу https://<адрес_менеджера>:9090 (рисунок 146).

Рисунок 146 – Веб-интерфейс Cockpit

В навигационном меню Cockpit следует выбрать раздел "Интеграция Keycloak", после чего отобразится интерфейс модуля, позволяющий выполнить настройку подключения и проверить его состояние (рисунок 147).

Рисунок 147 – Интеграция с внешним Keycloak

Модуль "Интеграция с внешним Keycloak" предоставляет следующие основные функции:

Отображение состояния интеграции ‒ отображает текущее состояние интеграции с внешним Keycloak, включая:
- статус активности интеграции (активна/не активна);
- тип подключения(внешняя/внутренняя);
- параметры подключения (URL Keycloak, realm, client ID);
- актуальность и применяемость конфигурации.
Настройка и активация интеграции ‒ с помощью мастера настройки пользователь может:
- включить интеграцию с внешним Keycloak;
- задать параметры подключения;
- выполнить импорт сертификата;
- применить конфигурацию для oVirt Engine и OVN.
Откат интеграции ‒ позволяет выполнить откат настроек аутентификации и вернуть встроенный механизм аутентификации Системы, при этом пользователь информируется о возможной кратковременной недоступности веб-интерфейса.

Отображение состояния интеграции

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

В зависимости от конфигурации и доступности сервисов возможны три состояния интеграции:

Интеграция не настроена (рисунок 148) ‒ в данном состоянии интеграция с внешним Keycloak отсутствует и не активирована.

Характерные признаки состояния:

отображается статус "Внешний Keycloak не настроен: Не активно";
параметры подключения отсутствуют;
поля "Тип", "Keycloak URL", "Realm" и "Client ID" не заданы.

Рисунок 148 – Интеграция с внешним Keycloak не настроена

Данное состояние является начальным и соответствует ситуации, когда настройка интеграции ещё не выполнялась.

Интеграция активна ‒ в случае успешной настройки и применения конфигурации модуль отображает активное состояние интеграции.

В зависимости от используемого механизма аутентификации возможны два варианта отображения:

Используется встроенный Keycloak (рисунок 149) ‒ если в системе активен встроенный механизм аутентификации СУСВ, отображается информация о встроенном Keycloak:
- статус "Используется встроенная Keycloak: Активно";
- тип "Встроенная Keycloak";
- отображаются параметры подключения (Keycloak URL, Realm, Client ID);
- выводится предупреждение о невозможности подключения внешнего Keycloak до отключения встроенной интеграции.

Данное состояние означает, что Cистема использует встроенный механизм аутентификации.

Рисунок 149 – Встроенный Keycloak активен

Подключён внешний Keycloak (рисунок 150) ‒ если интеграция с внешним сервером Keycloak выполнена успешно, отображается следующее состояние:
- статус "Внешний Keycloak подключён: Активно";
- тип "Внешняя Keycloak";
- отображаются параметры подключения (Keycloak URL, Realm, Client ID).

Это состояние подтверждает, что аутентификация пользователей oVirt Engine и OVN выполняется через внешний сервер Keycloak.

Рисунок 150 – Интеграция с внешним Keycloak активна

Ошибка получения состояния интеграции (рисунок 151) ‒ в случае возникновения ошибки при получении данных с серверной части отображается состояние ошибки.

Характерные признаки:

выводится сообщение "Сервер недоступен";
отображается уведомление о невозможности получить статус интеграции;
указывается возможная причина (временная недоступность сервера или проблемы с сетью);
пользователю рекомендуется обратиться к системному администратору.

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

Рисунок 151 – Ошибка получения состояния интеграции

Настройка и активация интеграции

Настройка интеграции выполняется с помощью мастера. Для запуска мастера нужно нажать "Открыть мастер настройки" в разделе интеграции с внешним Keycloak. Начальное окно мастера с четырьмя шагами настроек показано на рисунке 152.

Рисунок 152 – Мастер настройки

Шаг 1 ‒ Параметры Keycloak

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

Обязательные поля:

Keycloak base URL — базовый URL внешнего Keycloak, например https://keycloak.example.com:8443/;
Keycloak IP — IP-адрес сервера Keycloak;
Realm — имя Realm в Keycloak;
Client ID — идентификатор клиента в Keycloak;
Client Secret — секрет клиента (отображается скрыто).

При необходимости можно показать/скрыть значение с помощью пиктограммы просмотра.

До запуска проверки отображается информационное сообщение "Проверка Keycloak не выполнялась" с рекомендацией нажать кнопку проверки после ввода параметров.

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

сервер Keycloak доступен по указанному адресу;
указанные Realm и параметры клиента корректны;
возможна аутентификация через Client ID/Client secret (если включены необходимые настройки клиента).

Если все параметры указаны корректно, и проверка выполнена успешно, отображается сообщение "Keycloak успешно проверен" (рисунок 153). В этом случае становится доступен переход к следующему шагу мастера по кнопке Дальше.

Рисунок 153 – Успешная проверка Keycloak

Если соединение с Keycloak установлено, но часть проверки выполнить не удалось, отображается сообщение "Проверка выполнена с предупреждением" (рисунок 154).

Типовой случай в качестве примера: для клиента отключены Service Accounts, из-за чего невозможно подтвердить корректность Client ID и Client Secret, а в сообщении отображается рекомендация включить Service Accounts в настройках клиента Keycloak.

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

Рисунок 154 – Проверка выполнена с предупреждением

Если успешно выполнить проверку не удалось, отображается сообщение "Не удалось проверить Keycloak" (рисунок 155).

Возможные причины:

указан неверный URL или IP Keycloak;
сервер Keycloak недоступен по сети;
некорректно указаны Realm, Client ID или Client secret;
используется неверный протокол/порт (например, ожидается HTTPS, но доступен только HTTP).

В этом случае необходимо проверить введённые параметры и повторить проверку подключения.

Рисунок 155 – Проверка не удалась

Шаг 2 ‒ Параметры OVN и сертификат

На втором шаге мастера выполняется настройка параметров OVN и импорт сертификата Keycloak, необходимого для корректного взаимодействия сервисов ovirt-provider-ovn и механизма SSO (рисунок 156).

Рисунок 156 – Параметры OVN и сертификат

Параметры OVN для настройки:

OVN admin user — учётная запись администратора OVN, от имени которой будет выполняться настройка интеграции. Указанный пользователь должен обладать необходимыми правами для применения конфигурации.
Способ импорта сертификата ‒ для доверенного взаимодействия с сервером Keycloak необходимо наличие корректного TLS-сертификата. Модуль поддерживает три способа импорта сертификата:

Автоматическое получение сертификата с Keycloak по URL ‒ сертификат автоматически запрашивается с сервера Keycloak по указанному адресу "URL для получения сертификата", который, как правило, совпадает со значением "Keycloak base URL", указанным на первом шаге. Этот способ рекомендуется использовать, если:

сервер Keycloak доступен по сети;
используется стандартная TLS-конфигурация;
нет необходимости в ручном управлении сертификатами.

Загрузка файла сертификата (PEM) ‒ сертификат загружается вручную в виде файла. Допустимы следующие форматы файлов сертификатов: .pem, .crt, .cer, .txt. Возможные ошибки при загрузке:

Недопустимый формат файла ‒ если выбран файл неподдерживаемого типа, отображается сообщение: "Недопустимый формат файла. Разрешены файлы сертификатов (.pem, .crt, .cer, .txt).";
Некорректный сертификат PEM ‒ если файл имеет допустимое расширение, но его содержимое не соответствует формату PEM (повреждённый файл или неверная структура), отображается сообщение "Файл не является корректным сертификатом в формате PEM.".

В обоих случаях необходимо выбрать корректный файл сертификата и повторить загрузку.

Использовать системный CA / ранее импортированный truststore ‒ используется сертификат, уже присутствующий в системном truststore или доверенный системным центром сертификации (CA). Этот способ рекомендуется, если:

сертификат Keycloak уже был импортирован ранее;
используется корпоративный или системный CA;
нет необходимости повторно добавлять сертификат.

Поле "Пароль truststore" — пароль для доступа к хранилищу доверенных сертификатов ‒ является обязательным для всех способов импорта и используется при применении конфигурации.

Примечание ‒ Указанные на данном шаге параметры будут использованы для настройки ovirt-provider-ovn и механизма SSO в сторону Keycloak.

Шаг 3 ‒ Подтверждение

На третьем шаге мастера пользователю отображается предупреждение и краткое резюме конфигурации, которая будет применена к Системе (рисунок 157).

В верхней части экрана отображается предупреждающее сообщение "Внимание: изменение настроек аутентификации". В предупреждении указывается, что:

подключение внешнего Keycloak изменяет механизм аутентификации oVirt Engine;
при ошибке конфигурации веб-интерфейс может стать недоступен;
рекомендуется заранее обеспечить альтернативный доступ к хосту Engine (например, по SSH) для возможности ручного отката настроек.

Также на этом шаге в окне отображается краткое резюме конфигурации со сводной информацией по всем параметрам, заданным на предыдущих шагах мастера.

Под резюме отображается информационное сообщение о том, что после завершения мастера будут:

обновлены конфигурационные файлы ovirt-engine;
обновлена конфигурация ovirt-provider-ovn;
при необходимости обновлён truststore.

Для продолжения настройки необходимо нажать кнопку Подключить, после чего мастер перейдёт к шагу применения настроек.

Рисунок 157 – Этап подтверждения

Шаг 4 ‒ Применение настроек

На четвёртом шаге мастера выполняется непосредственное применение конфигурации и запуск процесса интеграции с внешним Keycloak.

После подтверждения параметров система автоматически начинает процесс настройки. В интерфейсе отображается информационное сообщение "Выполняется интеграция с внешней Keycloak…" (рисунок 158).

В этот момент выполняются следующие действия:

обновляются конфигурационные файлы ovirt-engine;
настраивается интеграция ovirt-provider-ovn;
производится настройка и обновление truststore;
применяется механизм аутентификации через внешний Keycloak;
перезапускаются сервисы.

Рисунок 158 – Процесс интеграции

В случае успешного применения конфигурации отображается сообщение "Интеграция с внешней Keycloak успешно выполнена" (рисунок 159).

После этого работу с мастером можно завершить, нажав кнопку Закрыть.

В результате в разделе "Состояние интеграции" будет отображаться активная интеграция с внешним Keycloak.

Рисунок 159 – Интеграция успешна

Если в процессе применения конфигурации возникает ошибка, отображается сообщение "Ошибка при выполнении интеграции", и в блоке сообщения указываются (рисунок 160):

общее описание ошибки;
подробная информация о причине (например, ошибка импорта сертификата, неверный пароль truststore и т. д.).

Рекомендации по устранению ошибки:

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

При необходимости рекомендуется дополнительно проверить логи keycloak-connect для более детального анализа причины сбоя.

Рисунок 160 – Ошибка при выполнении интеграции

Откат интеграции

Функция отката интеграции предназначена для восстановления предыдущих настроек аутентификации в случае возникновения проблем после подключения внешнего Keycloak. Процедура отказа запускается нажатием кнопки Откатить интеграцию в основном окне "Интеграция с внешним Keycloak". В открывшемся диалоговом окне необходимо подтвердить действие, нажав кнопку Откатить интеграцию (рисунок 161).

Рисунок 161 – Подтверждение отката интеграции

Откат рекомендуется выполнять в следующих ситуациях:

После успешной установки интеграции веб-интерфейс менеджера виртуализации становится недоступен.
Возникают ошибки в работе сервиса ovirt-provider-ovn.
Изменились или стали некорректными параметры внешнего Keycloak (URL, Realm, Client, сертификаты).
Требуется временно вернуть встроенный механизм аутентификации Системы.

Откат позволяет безопасно вернуться к состоянию, которое использовалось до подключения внешнего Keycloak.

После подтверждения выполнения отката:

модальное окно закрывается;
в разделе "Состояние интеграции" отображается индикатор загрузки, указывающий на выполнение операции отката (рисунок 162);
выполняется восстановление конфигурации аутентификации и связанных компонентов.

Во время выполнения операции возможна кратковременная недоступность веб-интерфейса.

Рисунок 162 – Процесс отката

При успешном завершении отката:

в разделе "Состояние интеграции" отображается состояние, соответствующее варианту "Интеграция не настроена";
Система возвращается к предыдущему механизму аутентификации;
внешний Keycloak больше не используется для аутентификации.