Установка базового кластера с Keycloak

Назначение и ограничения

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

Инструкция описывает только отличия от базового сценария: дополнительный узел Keycloak в инвентаре Ansible, сертификат Keycloak, установку и настройку Keycloak, а также параметры zakroma_storage_gateway.auth. Общие шаги установки Закрома.Хранение и сервиса ZDS выполняются по базовой инструкции.

Перед началом убедитесь, что:

• для Keycloak выделен отдельный узел, а его FQDN разрешается со всех узлов кластера и с рабочих мест администраторов;
• на сервере PostgreSQL существует база keycloak и пользователь с правами на неё;
• подготовлен TLS-сертификат и ключ для FQDN Keycloak.

Устанавливаемые компоненты

Схема установки

Три узла с совмещёнными сервисами Закрома.Хранение и ZDS используют отдельные серверы Keycloak и PostgreSQL. Внешний балансировщик и DNS Round-Robin направляют клиентские подключения к узлам кластера и не устанавливаются Ansible-ролями из этой инструкции.

Обозначения Server1–Server5 условные. Используйте имена узлов из таблицы и файла inventories/base-cluster/hosts.

Установка

1. Подготовка поставки и инвентаря Ansible

Получите и распакуйте архив поставки по базовой инструкции. Затем отредактируйте inventories/base-cluster/hosts: в отличие от базового сценария добавьте узел Keycloak в группу certificates и оставьте группу keycloak. Замените имена узлов и IP-адреса значениями из вашей инфраструктуры.

Copy
1[certificates]
2rutherford-1 ansible_host=192.168.1.1
3rutherford-2 ansible_host=192.168.1.2
4rutherford-3 ansible_host=192.168.1.3
5rutherford-4 ansible_host=192.168.1.4
6
7[keycloak]
8rutherford-1 ansible_host=192.168.1.1
9
10[zakroma-storage]
11rutherford-2 ansible_host=192.168.1.2
12rutherford-3 ansible_host=192.168.1.3
13rutherford-4 ansible_host=192.168.1.4
14
15# Не изменяйте zakroma_zds_node_name после ввода кластера в эксплуатацию.
16[zakroma-zds-v2-ec]
17rutherford-2 ansible_host=192.168.1.2 zakroma_zds_node_name=rutherford-2
18rutherford-3 ansible_host=192.168.1.3 zakroma_zds_node_name=rutherford-3
19rutherford-4 ansible_host=192.168.1.4 zakroma_zds_node_name=rutherford-4

Проверьте SSH-доступ и выполнение Python-модулей Ansible:

Copy
1ANSIBLE_CONFIG=ansible.cfg ansible -m ping -i inventories/base-cluster/hosts all

Ожидаемый результат: каждый узел, включая узел Keycloak, отвечает SUCCESS и pong.

2. Распространение сертификатов по узлам

Поместите сертификаты и ключи для Keycloak и для сервисов Закрома.Хранение в каталог files на управляющем сервере. Затем отредактируйте inventories/base-cluster/group_vars/certificates.yml: добавьте в соответствующие параметры доступа к файлам для использования данных сертификатов сервисами.

Copy
1---
2certificates_copy_source_path: "files"
3
4host_cert_config:
5  rutherford-1: # узел Keycloak из инвентаря Ansible
6    certs:
7      - src_dir: "{{ certificates_copy_source_path }}"
8        dest_dir: "/opt/certs/"
9        cert_file: "keycloak.crt"
10        key_file: "keycloak.key"
11        owner: "keycloak"
12        group: "keycloak"
13        cert_permissions: "0644"
14        key_permissions: "0600"
15  rutherford-2: # узел Закрома.Хранение из инвентаря Ansible
16    certs:
17      - src_dir: "{{ certificates_copy_source_path }}"
18        dest_dir: "/opt/certs/"
19        cert_file: "zakroma.crt"
20        key_file: "zakroma.key"
21        owner: "zakroma"
22        group: "zakroma"
23        cert_permissions: "0644"
24        key_permissions: "0600"
25  # Повторите блок для rutherford-3 и rutherford-4 по образцу rutherford-2.

Запустите плейбук распространения сертификатов:

Copy
1ANSIBLE_CONFIG=ansible.cfg ansible-playbook \
2  -i inventories/base-cluster/hosts \
3  playbooks/sample-play-copy-certificates.yml

На узле Keycloak проверьте файлы, владельца и права:

Copy
1sudo stat -c '%U:%G %a %n' /opt/certs/keycloak.crt /opt/certs/keycloak.key

Ожидаются владелец keycloak, права 644 для сертификата и 600 для ключа.

3. Установка Keycloak

В этом сценарии Keycloak устанавливается на отдельный узел из группы keycloak. Если в инфраструктуре уже есть совместимый Keycloak, пропустите установку и перейдите к разделу «Подготовка realm и клиента».

realm — область пользователей и настроек Keycloak, client — приложение Закрома.Хранение, service account — служебная учётная запись клиента для синхронизации пользователей, а mapper — правило добавления данных пользователя в токен.

Отредактируйте inventories/base-cluster/group_vars/keycloak.yml. Измените адрес PostgreSQL, базовый домен, учётные данные базы и bootstrap-администратора; остальные параметры поставки сохраните без изменений.

Copy
1# Адрес (хост) PostgreSQL, к которому будет подключаться Keycloak.
2postgres_host: "<POSTGRESQL_FQDN>"
3
4# Базовый домен, используемый в URL для Keycloak.
5base_domain: "<BASE_DOMAIN>"
6
7# Имя пользователя базы данных (PostgreSQL), под которым Keycloak будет подключаться.
8keycloak_quarkus_db_user: "<KEYCLOAK_DB_USER>"
9
10# Пароль пользователя базы данных (PostgreSQL).
11keycloak_quarkus_db_pass: "<KEYCLOAK_DB_PASSWORD>"
12
13# Пользователь - администратор системы
14keycloak_quarkus_bootstrap_admin_user: "<KEYCLOAK_ADMIN>"
15
16# Пароль учётной записи администратора Keycloak
17keycloak_quarkus_bootstrap_admin_password: "<KEYCLOAK_ADMIN_PASSWORD>"

Пароли — секреты. Зашифруйте их так же, как пароль PostgreSQL в базовой инструкции: ANSIBLE_CONFIG=ansible.cfg ansible-vault encrypt_string --name keycloak_quarkus_db_pass, затем вставьте полученный !vault-блок вместо открытого значения.

Пути сертификата и ключа в переменных keycloak_quarkus_cert_file и keycloak_quarkus_key_file должны совпадать с настройками шага распространения сертификатов; в поставке это /opt/certs/keycloak.crt и /opt/certs/keycloak.key.

Запустите плейбук установки Keycloak:

Copy
1ANSIBLE_CONFIG=ansible.cfg ansible-playbook \
2  -i inventories/base-cluster/hosts \
3  playbooks/sample-play-keycloak.yml

3.1. Проверка установки Keycloak

На узле Keycloak проверьте сервис:

Copy
1sleep 5
2sudo systemctl status --no-pager --full keycloak.service
3sudo systemctl is-enabled keycloak.service

Ожидаются состояние Active: active (running) с указанием времени работы сервиса и результат enabled для проверки автозапуска.

С машины оператора проверьте TLS и доступность realm. Укажите CA, которым подписан сертификат Keycloak:

Copy
1curl --fail --silent --show-error \
2  --cacert <CA_CERTIFICATE> \
3  https://keycloak.zakroma.internal:8443/realms/master/.well-known/openid-configuration \
4  | jq -e '.issuer, .token_endpoint'

Ожидается JSON с адресами realm master. Если используется другой realm, замените master в URL.

Административный интерфейс доступен по адресу https://keycloak.zakroma.internal:8443/admin/. Для входа используйте bootstrap-логин и пароль, заданные в inventories/base-cluster/group_vars/keycloak.yml.

3.2. Подготовка realm и клиента

Подготовить Keycloak можно двумя способами:

• импортировать realm из поставки — подходит для нового тестового стенда;
• создать realm и client вручную — подходит для существующего Keycloak и production-контура.

В обоих вариантах имена realm и client должны совпадать с параметрами zakroma_storage_gateway.auth.keycloak.

3.3. Импорт realm из поставки

В поставке файл files/keycloak/realm.json содержит realm master, confidential client zakroma, client role clouduser, включённые Direct Access Grants и service account.

Для нового стенда запустите:

Copy
1ANSIBLE_CONFIG=ansible.cfg ansible-playbook \
2  -i inventories/base-cluster/hosts \
3  playbooks/sample-play-keycloak-copy-realm.yml

Импорт изменяет realm master Плейбук останавливает Keycloak и импортирует files/keycloak/realm.json с параметром --override true. Не запускайте его для существующего Keycloak без проверки файла и резервной копии realm. Для общего или production-сервиса используйте ручную настройку.

После импорта проверьте в административном интерфейсе:

• realm master существует и включён;
• client zakroma включён;
• у client включены Client authentication, Authorization, Standard flow, Direct access grants и Service accounts roles;
• у client существует роль clouduser;
• service account клиента имеет realm role admin;
• mapper username добавляет claim username в access token.

Подготовленный realm выдаёт service account широкую роль admin, чтобы сохранить совместимость со всеми операциями Gateway 2.9.3. Сокращённый набор realm-management roles из инструкции Закрома.Диска не переносится: Закрома.Хранение дополнительно получает клиентов и пользователей, синхронизирует роли/группы и завершает пользовательские сессии. Least-privilege набор для этих операций нужно проверять отдельно на стенде.

3.4. Ручная настройка realm и клиента

Если готовый realm не используется:

1. Войдите в административный интерфейс Keycloak.
2. Используйте master для полного соответствия примеру поставки либо создайте отдельный realm, например zakroma. Во втором случае укажите это же имя в auth.keycloak.realm.
3. Откройте Clients и создайте client с Client ID: zakroma.
4. Включите:
   • Client authentication: On;
   • Authorization: On;
   • Standard flow: On;
   • Direct access grants: On;
   • Service accounts roles: On.
5. Для этого сценария назначьте service account клиента широкую административную роль: для импортированного realm master — realm role admin, для отдельного realm — client role realm-management: realm-admin. Не используйте bootstrap-пользователя Keycloak как service account.
6. Откройте Clients -> zakroma -> Client scopes -> zakroma-dedicated.
7. Добавьте mapper By configuration -> User Attribute:
   • Name: username;
   • User Attribute: username;
   • Token Claim Name: username;
   • Claim JSON Type: String;
   • Add to access token: On.
8. Откройте Realm Settings -> Tokens и установите Access Token Lifespan: 10 minutes.

3.5. Выбор пользователей по роли или группе

Закрома.Хранение синхронизирует только разрешённых пользователей Keycloak. Выберите одну стратегию:

Для тестового пользователя:

1. Откройте Users -> Add user и создайте пользователя, например zakromaadmin.
2. В Credentials -> Set password задайте пароль и выключите Temporary.
3. Назначьте client role clouduser либо добавьте пользователя в разрешённую группу.
4. Значение zakroma_storage_gateway.default_admin должно совпадать с именем разрешённого пользователя.

Если Keycloak получает пользователей из LDAP/AD, сначала настройте User Federation и синхронизацию в Keycloak. В эту статью не переносятся LDAP-мапперы Закрома.Диска: их параметры зависят от схемы каталога. Общие варианты описаны в Настройке авторизации.

3.6. Проверка входа тестового пользователя

До установки Закрома.Хранение проверьте password grant. Команда не выводит токены и запрашивает секреты интерактивно:

Copy
1read -rsp 'Keycloak client secret: ' KEYCLOAK_CLIENT_SECRET
2echo
3read -rsp 'Test user password: ' KEYCLOAK_TEST_PASSWORD
4echo
5
6curl --fail --silent --show-error \
7  --cacert <CA_CERTIFICATE> \
8  --data-urlencode 'grant_type=password' \
9  --data-urlencode 'client_id=zakroma' \
10  --data-urlencode "client_secret=${KEYCLOAK_CLIENT_SECRET}" \
11  --data-urlencode 'username=zakromaadmin' \
12  --data-urlencode "password=${KEYCLOAK_TEST_PASSWORD}" \
13  https://keycloak.zakroma.internal:8443/realms/<REALM>/protocol/openid-connect/token \
14  | jq -e 'has("access_token") and has("refresh_token")'
15
16unset KEYCLOAK_CLIENT_SECRET KEYCLOAK_TEST_PASSWORD

Ожидаемый результат — true.

4. Настройка Закрома.Хранение для Keycloak

Выполняйте настройку Закрома.Хранение по базовой инструкции: подключение к PostgreSQL, домен и TLS настраиваются без изменений. Gateway при этом работает с включённым TLS — эта конфигурация рекомендуется для установки; подготовьте соответствующие сертификаты для используемых FQDN. Отличие от базового сценария только в авторизации: при редактировании inventories/base-cluster/group_vars/zakroma-storage.yml вместо локальной авторизации выберите Keycloak.

Фрагменты ниже находятся внутри существующей секции zakroma_storage_gateway. Не заменяйте ими всю переменную: измените соответствующие ключи в существующем файле, ориентируясь по именам переменных.

Сначала выберите Keycloak провайдером аутентификации и пользователей. Имя default_admin должно совпадать с разрешённым пользователем, созданным в разделе 3.5:

Copy
1  default_admin: zakromaadmin
2  auth:
3    auth_provider: keycloak
4    user_provider: "keycloak"

Затем внутри zakroma_storage_gateway.auth настройте подключение к Keycloak:

Copy
1    # Контекст перед блоком: конец настроек OIDC.
2    #   redirect_uri: ""
3    #   auth_type: "password"
4
5    # Настройки Keycloak
6    keycloak:
7      # Стратегия синхронизации пользователей: roles или groups
8      sync_strategy: roles
9      permission:
10        # Client role, разрешающая вход при sync_strategy: roles
11        role: clouduser
12        # Корневая группа, разрешающая вход при sync_strategy: groups
13        group: zakromausers
14      # URL установленного или внешнего Keycloak
15      connection_url: "https://keycloak.{{ zakroma_storage_base_domain }}:8443"
16      # master — для realm из поставки; укажите другое имя при ручной настройке
17      realm: master
18      # Client secret клиента zakroma
19      secret: "<KEYCLOAK_CLIENT_SECRET>"
20      client_id: zakroma
21      redirect_uri: ""
22      listing_page_size: 100
23
24    # Контекст после блока: начало настроек LDAP.
25    #   ldap:
26    #     permission:

При sync_strategy: roles используется только permission.role, при sync_strategy: groups — только permission.group. default_admin должен входить в выбранную роль или группу.

<KEYCLOAK_CLIENT_SECRET> — секрет клиента zakroma из Keycloak. Зашифруйте его через ansible-vault encrypt_string по примеру из базовой инструкции.

5. Продолжение установки по базовой инструкции

Дальнейшие шаги не отличаются от базового сценария. Вернитесь к базовой инструкции и выполните:

1. Настройку сервиса ZDS.
2. Проверку конфигурации.
3. Распространение лицензии.
4. Preflight-проверки Закрома.Хранение и ZDS.
5. Установку Закрома.Хранение и сервиса ZDS.
6. Проверку готовности и функциональную проверку S3.

Проверка авторизации после установки

После проверок готовности из базовой инструкции дополнительно проверьте авторизацию через Keycloak:

1. Войдите в Admin UI пользователем default_admin с паролем из Keycloak.
2. Убедитесь, что в списке пользователей отображаются только пользователи разрешённой роли или группы.

Подробная проверка сервисов приведена в Проверке статуса сервисов.