Развертывание внешнего Keycloak

Сервис Keycloak может быть развернут как на отдельном физическом сервере, так и на ВМ, находящейся вне кластера управляемого СУСВ (oVirt).

Рекомендованная к использованию версия Keycloak — 15 и выше.

Сервер должен соответствовать следующим требованиям:

• процессор: архитектура х86_64;
• количество ядер: не менее 2;
• оперативная память: не менее 4 ГБ;
• свободное дисковое пространство: не менее 40 ГБ;
• сетевой интерфейс: не менее 1 Гбит/с;
• Сеть: доступ из oVirt Engine по HTTPS (порт 8443 или 443);
• ОС: CentOS Stream 8 / Rocky Linux 8;
• привод DVD / порт USB – для установки ПО.

Приведенные далее рекомендации основаны на версии Keycloak 15.1.1 и ОС CentOS Stream 8. Настройки на других версиях могут иметь некоторые отличия. Для уточнения необходимо обращаться к документации по применяемым программным продуктам.

Подготовка окружения

Необходимо выполнить следующие подготовительные действия:

1. создать пользователя и группы:

sudo groupadd -r keycloak
sudo useradd -m -d /var/lib/keycloak -s /sbin/nologin \
-r -g keycloak keycloak

2. создать каталог под Keycloak:

sudo mkdir -p /opt/keycloak

3. загрузить дистрибутив Keycloak:

sudo wget https://github.com/keycloak/keycloak/releases/ \
download/15.1.1/keycloak-15.1.1.zip -P /opt/keycloak

4. распаковать дистрибутив Keycloak:

sudo unzip /opt/keycloak/keycloak-15.1.1.zip -d \
/opt/keycloak
cd /opt

5. назначить права пользователю Keycloak:

sudo chown -R keycloak:keycloak keycloak
sudo chmod o+x /opt/keycloak/keycloak-15.1.1/bin/

Установка и настройка дополнительного ПО

Для обеспечения работы Keycloak требуется установить Java и внешнюю базу данных PostgreSQL. Далее описаны необходимые действия по установке ПО и настройке дополнительных зависимостей:

1. Установить OpenJDK 11. Keycloak 15.x работает только на Java 8 или Java 11. Для CentOS 8 рекомендуется использовать OpenJDK 11.

Репозитории на зеркалах CentOS отключены, поэтому необходимо подключиться к доступному репозиторию:

sed -i 's/mirrorlist/#mirrorlist/g' \
/etc/yum.repos.d/CentOS-*
sed -i 's|#baseurl=http://mirror.centos.org|\
baseurl=http://vault.centos.org|g' /etc/yum.repos.d/CentOS-*

Установить Java:

sudo dnf -y install java-11-openjdk

Проверить версию:

java -version
openjdk version "11.x.x"

2. Установить PostgreSQL 14. Keycloak поддерживает PostgreSQL 10+, но оптимально использовать PostgreSQL 14 (стабильный и совместимый пакет для CentOS 8).

• подключить официальный репозиторий PostgreSQL:

sudo dnf install -y \
https://download.postgresql.org/pub/repos/yum/reporpms/\
EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm

• отключить встроенный модуль PostgreSQL:

sudo dnf -qy module disable postgresql

• установить сервер и клиент PostgreSQL 14:

sudo dnf -y install postgresql14-server postgresql14

• инициализировать кластер базы данных:

sudo /usr/pgsql-14/bin/postgresql-14-setup initdb

• добавить в автозагрузку и запустить сервис:

sudo systemctl enable postgresql-14
sudo systemctl start postgresql-14

• проверить состояние сервиса:

systemctl status postgresql-14

Примечание – Создавать базу данных и пользователя вручную НЕ требуется. Keycloak создаст их автоматически при первом запуске — при условии, что параметры подключения корректно указаны в конфигурационном файле (рассмотрены далее).

3. Настроить SSL для Keycloak.

Keycloak должен работать по протоколу HTTPS, иначе oVirt Engine не примет соединение. Можно использовать:

• готовый сертификат (рекомендовано);
• самоподписанный (для тестовой среды).

1. создать каталог SSL (если его нет):

sudo mkdir -p  \
/opt/keycloak/keycloak-15.1.1/standalone/configuration/ssl

2. перейти в каталог SSL:

cd /opt/keycloak/keycloak-15.1.1/standalone/configuration/ssl

3. для тестовой среды можно создать самоподписанный сертификат и приватный ключ:

sudo openssl req -x509 -sha256 -nodes -days 365 \
-newkey rsa:2048 \
-keyout \
/opt/keycloak/keycloak-15.1.1/standalone/configuration \
/ssl/server.key.pem \
-out \
/opt/keycloak/keycloak-15.1.1/standalone/configuration \
/ssl/server.crt.pem

В процессе выполнения команда запросит ввод значений:

• Common Name (CN) — необходимо ввести, должно совпадать с доменным именем Keycloak, например: keycloak.home.local;
• остальные поля можно оставить пустыми.

После выполнения будут созданы:

• server.key.pem — приватный ключ;
• server.crt.pem — самоподписанный сертификат.

4. Создать контейнер PKCS12.

cd /opt/keycloak/keycloak-15.1.1/ \
standalone/configuration/ssl
sudo openssl pkcs12 -export \
-in server.crt.pem \
-inkey server.key.pem \
-out server.p12 \
-name server \
-passout pass:password

5. Импортировать PKCS12 в Java Keystore Keycloak.

sudo keytool -importkeystore \
-srckeystore server.p12 -srcstoretype PKCS12 \
-srcstorepass password \
-destkeystore application.keystore -deststoretype JKS \
-deststorepass password

Примечание – Пароль указывается в конфигурационном файле standalone.xml.

Настройка Keycloak

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

1. В файле конфигурации standalone.xml, расположенном в папке /opt/keycloak/keycloak-15.1.1/standalone/configuration/:

• Указать в файле пользователя и пароль для автоматического создания БД Keycloak (рисунок 120).

Рисунок 120 – Имя пользователя и пароль для БД Keycloak

• Указать доменное имя для Keycloak (рисунок 121). Для примера использовано имя keycloak.home.local. При настройке необходимо указать ваш реальный домен Keycloak. Домен должен быть прописан в DNS (или в /etc/hosts).

Рисунок 121 – Доменное имя для Keycloak

2. Создать администратора Keycloak.

cd /opt/keycloak/keycloak-15.1.1/bin
sudo ./add-user-keycloak.sh -r master -u admin

3. Открыть порт 8443 для взаимодействия по протоколу HTTPS.

sudo firewall-cmd --permanent --zone=public \
--add-port=8443/tcp
sudo firewall-cmd --reload

4. Запустить сервис Keycloak.

sudo /opt/keycloak/keycloak-15.1.1/bin/standalone.sh \
-b 0.0.0.0

Дальнейшая настройка Keycloak проводится в веб-интерфейсе сервиса:

1. Войти в веб-интерфейс (рисунок 122), для чего:

• в браузере перейти по адресу доменного имени Keycloak, например: https:// keycloak.home.local:8443;
• указать Логин: admin;
• ввести Пароль: указанный при создании администратора.

Рисунок 122 – Вход в Keycloak

2. Создать realm. В главном меню нажать Add realm (рисунок 123). Задать имя "ovirt-internal" для нового realm. Дальнейшая настройка будет производиться в нем (рисунок 124).

Рисунок 123 – Добавить realm

Рисунок 124 – Имя ovirt-internal для нового realm

3. Создать группу администраторов.

В разделе "Groups" нажать New, ввести имя группы ovirt-administrator (рисунок 125).

Рисунок 125 – Создать группу администраторов

8. Создать учетную запись администратора.

В разделе "Users" нажать Add user, ввести имя пользователя "admin@ovirt", Email: "admin@localhost" (важно для авторизации в Grafana), в выпадающем списке "Groups" выбрать ранее созданную группу "ovirt-administrator" (рисунок 126).

Рисунок 126 – Создать администратора

9. Настроить учетную запись администратора, выполнив необходимые действия в разделе "Users":

• во вкладке "Users/Credentials" задать пользователю пароль нажатием кнопки Set password. Включенный переключатель "Temporary" указывает, что при первом входе пользователю необходимо будет ввести новый пароль (рисунок 127). Ввод подтвердить нажатием кнопки Save.

Рисунок 127 – Задать пароль администратора

• в разделе "Roles" нажать Add Role (рисунок 128).

Рисунок 128 – Раздел Roles

Ввести Role Name: "grafana-admin" (рисунок 129). Ввод подтвердить нажатием кнопки Save.

Рисунок 129 – Добавить роль

Аналогично добавить роли grafana-editor и grafana-viewer (рисунок 130).

Рисунок 130 – Добавленные роли Grafana

10. Настроить Client Scopes:

• перейти в раздел "Client Scopes" и нажать Create (рисунок 131).

Рисунок 131 – Раздел Client Scopes

• ввести Name: "ovirt-app-admin", остальные параметры оставить по умолчанию. Нажать Save (рисунок 132).

Рисунок 132 – Добавить client scope

• аналогично добавить client scope (рисунок 133):
  • ovirt-app-api;
  • ovirt-app-portal;
  • ovirt-ext=auth:identity;
  • ovirt-ext=auth:sequence-priority=~;
  • ovirt-ext=revoke:revoke-all;
  • ovirt-ext=token-info:authz-search;
  • ovirt-ext=token-info:public-authz-search;
  • ovirt-ext=token-info:validate;
  • ovirt-ext=token:login-on-behalf;
  • ovirt-ext=token:password-access.

Рисунок 133 – Добавленные client scope

11. Добавить клиента.

• перейти в раздел "Clients" и нажать Create (рисунок 134).

Рисунок 134 – Раздел Clients

• ввести Client ID: "ovirt-engine-internal" (рисунок 135). В качестве "Root URL" указать "https://FQDN" хоста СУСВ. Ввод подтвердить нажатием кнопки Save.

Рисунок 135 – Добавление клиента

Общие настройки клиента выглядят как показано на рисунке 136 и требуют корректировки.

Рисунок 136 – Текущие настройки клиента

• внести следующие изменения (рисунок 137):

Рисунок 137 – Обновленные настройки клиента

1. Access type: confidential;
2. Valid Redirect URLs: "https://FQDN/" изменить на "https://FQDN";
3. Base URL: https://FQDN;
4. Backchannel Logout Session Required: OFF,

где FQDN — это доменное имя хоста СУСВ.

Ввод подтвердить нажатием кнопки Save.

Необходимо обратить внимание, что на вкладке "Credential" раздела "Clients" размещена информация об аутентификации клиента в том числе поле Secret, которое может использоваться при дальнейшей настройке интеграции с сервисом (рисунок 138).

Рисунок 138 – Secret клиента

12. Настроить Client Scopes клиента.

Перейти на вкладку "Client Scopes" раздела "Clients" (рисунок 139).

Рисунок 139 – Текущие настройки Client Scopes клиента

Необходимо перевести все доступные "Optional Client Scopes" из "Available Client Scopes" в "Assigned Optional Client Scopes" (рисунок 140).

Рисунок 140 – Измененные настройки Client Scopes клиента

13. Добавить клиенту протоколы:

• перейти на вкладку "Mappers" раздела "Clients" и нажать кнопку Create (рисунок 141).

Рисунок 141 – Вкладка Mappers

• создать протокол username со следующими параметрами (рисунок 142):

Рисунок 142 – Создание протокола username

• Name: username;
• Mapper Type: User Property;
• Property: username;
• Token Claim Name: preferred_username;
• Claim JSON Type: String.

Ввод подтвердить нажатием кнопки Save.

• нажать кнопку Create и создать протокол groups со следующими параметрами (рисунок 143):

Рисунок 143 – Создание протокола groups

• Name: groups;
• Mapper Type: Group Membership;
• Token Claim Name: groups.

Ввод завершить нажатием кнопки Save.

• нажать кнопку Create и создать протокол realm role со следующими параметрами (рисунок 144):

Рисунок 144 – Создание протокола realm role

• Name: realm role;
• Mapper Type: User Realm Role;
• Token Claim Name: realm_access.roles;
• Claim JSON Type: String.

Ввод завершить нажатием кнопки Save.

14. Изменить у клиента срок обновления токена доступа.

Перейти на вкладку "Settings" клиента "ovirt-engine-internal" в разделе "Clients" (рисунок 145). Установить значение параметра "Access Token Lifespan" 10 дней. Ввод подтвердить нажатием кнопки Save.

Рисунок 145 – Изменение Access Token Lifespan

На этом настройка параметров Keycloak в административном веб-интерфейсе закончена и необходимо переходить к настройке интеграции на хосте СУСВ.