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

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

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

Используйте существующий Keycloak, доступный по HTTPS из Pod Закрома.Хранение. Его установка, подготовка базы данных, обновление и резервное копирование в этот сценарий не входят.

Неймспейсы, база данных PostgreSQL для Закрома.Хранение, Ingress, ZDS и схема EC 2+1 остаются без изменений.

В примере Admin UI использует форму входа с логином и паролем (authType: password), а Gateway проверяет их через Keycloak.

Подготовка Keycloak

Используйте существующий совместимый Keycloak. Подготовьте realm и клиент по разделам Ручная настройка realm и клиента и Выбор пользователей по роли или группе. Шаги установки Keycloak и импорта realm через Ansible из VM-инструкции не выполняйте.

Проверьте обязательные настройки:

• realm, например zakroma, и клиент zakroma существуют;
• у клиента включены аутентификация клиента, Direct Access Grants и service account; полномочия service account соответствуют операциям синхронизации из инструкции настройки realm;
• mapper username добавляет claim username в access token;
• Access Token Lifespan согласован с настройкой клиента; в примере ручной подготовки используется 10 minutes;
• тестовый пользователь zakromaadmin имеет постоянный пароль и client role clouduser либо входит в выбранную разрешающую группу;
• HTTPS-сертификат Keycloak соответствует FQDN, а цепочке доверяет контейнер Gateway.

Согласуйте с администратором Keycloak назначение широких административных полномочий service account из исходной инструкции. Не используйте для этого bootstrap-администратора. Общие варианты описаны в Настройке авторизации.

Ключ подписи токенов realm

В административном интерфейсе Keycloak откройте Realm settings → Keys. Выберите активный RSA-ключ подписи токенов и сохраните:

1. kid — идентификатор выбранного ключа.
2. Его публичный ключ либо сертификат в PEM. Это не client secret и не приватный ключ realm.

Если сохранён сертификат files/keycloak-realm.crt, на рабочем месте администратора извлеките из него публичный ключ:

Copy
1openssl x509 -in files/keycloak-realm.crt -pubkey -noout > files/keycloak-realm.pub
2openssl pkey -pubin -in files/keycloak-realm.pub -noout

Ожидаемый результат: публичный ключ сохранён в files/keycloak-realm.pub, команда проверки завершилась без ошибок. Если экспортирован непосредственно публичный ключ, сохраните его в этот файл с PEM-заголовком.

После ротации ключа в Keycloak обновите список доверенных публичных ключей Gateway. Сохраните прежний ключ на период действия ранее выпущенных токенов. Закрытый ключ realm копировать не нужно.

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

Выполните шаги 1–4 базовой инструкции. Сохраните настройки подключения к PostgreSQL, доменов, лицензии, TLS на Ingress и собственную ключевую пару JWT Gateway.

В настроенном файле storage/values-storage.yaml измените параметры существующего блока global.config:

• для adminUi.authType оставьте password;
• в default_admin.login укажите пользователя Keycloak, который станет первым администратором;
• в auth.auth_provider и auth.user_provider укажите keycloak;
• очистите список локальных пользователей, задав auth.file.list: [];
• в auth.keycloak задайте параметры подключения, client secret и правила отбора пользователей;
• в jwt.keys укажите идентификатор и публичный ключ подписи токенов realm.

Ниже приведены параметры, которые нужно изменить в global.config. Остальные настройки оставьте без изменений.

Copy
1global:
2  config:
3    adminUi:
4      authType: "password"
5    default_admin:
6      login: "zakromaadmin"
7    auth:
8      auth_provider: "keycloak"
9      user_provider: "keycloak"
10      file:
11        list: []
12      keycloak:
13        url: "https://keycloak.example.internal"
14        realm: "zakroma"
15        clientId: "zakroma"
16        secret: "<KEYCLOAK_CLIENT_SECRET>"
17        sync_strategy: "roles"
18        user_role: "clouduser"
19        user_group: "zakromausers"
20        redirect_uri: ""
21        listing_page_size: 100
22    jwt:
23      keys:
24        - kid: "<KEYCLOAK_KID>"
25          rsa_public_key: "<KEYCLOAK_REALM_PUBLIC_KEY>"

В Helm-чарте 6.0.4 укажите роль в global.config.auth.keycloak.user_role, а не в global.config.user_role. Для адреса Keycloak и идентификатора клиента используйте url и clientId. Имена параметров отличаются от VM-инструкции, поэтому не копируйте из неё блок авторизации в values.

Публичные ключи realm из global.config.jwt.keys дополняют первую ключевую пару из zakroma-storage-gateway.config.jwt.keys. Сохраните собственную локальную пару; не заменяйте её демонстрационным ключом чарта.

Защита чувствительных данных

Client secret хранится в storage/values-storage.yaml открытым текстом. Ограничьте доступ к файлу, параметрам Helm-релиза и ConfigMap по рекомендациям базовой инструкции. Не публикуйте сформированные манифесты с реальными секретами.

Вставьте публичный ключ realm в storage/values-storage.yaml. Идентификатор <KEYCLOAK_KID> замените значением из Keycloak:

Copy
1python3 - <<'PY'
2from pathlib import Path
3import yaml
4path = Path('storage/values-storage.yaml')
5values = yaml.safe_load(path.read_text())
6key = values['global']['config']['jwt']['keys'][0]
7key['rsa_public_key'] = Path('files/keycloak-realm.pub').read_text().strip().replace('\n', r'\n')
8path.write_text(yaml.safe_dump(values, allow_unicode=True, sort_keys=False))
9PY

Настройка доверия к сертификату Keycloak

Если сертификат Keycloak подписан внутренним CA, подготовьте files/ca-certificates.crt. Сохраните в файле полный набор доверенных CA контейнера и добавьте цепочку Keycloak.

На рабочем месте администратора создайте ConfigMap с подготовленным файлом:

Copy
1kubectl -n zakroma-storage create configmap ca-certificates \
2  --from-file=ca-certificates.crt=files/ca-certificates.crt

В том же файле storage/values-storage.yaml добавьте CA в списки volumes и volumeMounts блока zakroma-storage-gateway. Ниже приведены полные списки для базового примера с лицензией. Остальные параметры Gateway, включая config.jwt и service, сохраните без изменений:

Copy
1zakroma-storage-gateway:
2  volumes:
3    - name: licence
4      secret:
5        secretName: licence
6    - name: ca-certificates
7      configMap:
8        name: ca-certificates
9  volumeMounts:
10    - name: licence
11      mountPath: /opt/application/licence
12      subPath: licence
13      readOnly: true
14    - name: ca-certificates
15      mountPath: /etc/ssl/certs/ca-certificates.crt
16      subPath: ca-certificates.crt
17      readOnly: true

Если все необходимые CA уже присутствуют в образе, ConfigMap и монтирование CA не требуются. После изменения ConfigMap, смонтированного через subPath, пересоздайте Pod для обновления файла.

Проверка подключения

До установки проверьте вход тестового пользователя по разделу Проверка password grant. Выполняйте команды с рабочего места с доступом к Keycloak, заменив URL на https://keycloak.example.internal/realms/zakroma/protocol/openid-connect/token, пользователя и CA значениями этого сценария. Ожидается true; токены не выводите и не сохраняйте в журнал.

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

Продолжите установку с шага 5 базовой инструкции: настройте ZDS и выполните последующие шаги. В командах Helm для Закрома.Хранение используйте storage/values-storage.yaml с подготовленными настройками Keycloak.

Проверьте конфигурацию:

Copy
1helm lint charts/zakroma-storage-6.0.4.tgz \
2  -f storage/values-storage.yaml

Ожидаемый результат — helm lint завершается без ошибок.

Выполните helm template из шага 6 без изменения команды: она использует тот же файл. Сохраните вывод манифестов во временный каталог с ограниченным доступом, как в базовой инструкции.

Для установки на шаге 9 и повторного Helm upgrade используйте:

Copy
1helm upgrade --install zakroma-storage charts/zakroma-storage-6.0.4.tgz -n zakroma-storage \
2  -f storage/values-storage.yaml \
3  --wait --timeout 10m

Файл zds/values-zds.yaml и команды релиза ZDS оставьте без изменений. Файл storage/values-storage.yaml передавайте только релизу Закрома.Хранение. При повторном запуске сохраните настройки Keycloak и собственные ключи JWT.

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

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

1. Войдите в Admin UI пользователем default_admin с паролем из Keycloak.
2. Убедитесь, что синхронизированы пользователи разрешённой роли или группы.
3. Проверьте отказ при входе тестового пользователя без разрешающей роли/группы.
4. Выполните S3-тест, затем повторный upgrade и повторный вход, сохранив профиль Keycloak.

При ошибке проверьте имя realm, client secret, полномочия service account, mapper username, kid и публичный ключ, цепочку TLS-сертификата и синхронизацию времени.

Проверьте журналы Gateway командой kubectl -n zakroma-storage logs deployment/zakroma-storage-gateway. Перед передачей журнала в техническую поддержку удалите чувствительные данные. Подробности приведены в инструкции по получению журналов приложения.