Keycloak — внешние зависимости, время и systemd

Keycloak редко существует сам по себе.

Например:

                  PostgreSQL
                      ↑
                      │
LDAP / FreeIPA ← Keycloak → SMTP
                      │
                      ↓
                external IdP

До установки стоит проверить:

• — DNS;
• — маршрутизацию;
• — firewall;
• — TLS trust;
• — сертификаты;
• — учётные данные;
• — время.

Иначе можно получить ситуацию:

Keycloak → работает

LDAP federation → нет
SMTP → нет
external IdP → нет

Формально сервис установлен.
Практически задача не решена.

19. Синхронизация времени важна

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

iat
exp
nbf

Поэтому:

Keycloak
applications
reverse proxy
external IdP

должны иметь корректное системное время.
Проверяем:

timedatectl

и фактическую синхронизацию NTP/chrony.
Не:

chronyd active

а:

часы действительно синхронизированы.

20. Production-сервер лучше предварительно собрать

Современный Keycloak использует build-time и runtime configuration.
Перед постоянным запуском можно явно выполнить:

bin/kc.sh build

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

bin/kc.sh start --optimized

Смысл:

build
 ↓
подготовка оптимизированного server image
 ↓
start --optimized
 ↓
быстрее и предсказуемее startup

Это особенно полезно, если конфигурация сервера уже определена и не должна пересобираться при каждом запуске.

21. Не все параметры одинаковы

Часть настроек относится к этапу build.
Часть — к runtime.
Поэтому нельзя бездумно считать:
всё, что лежит в keycloak.conf, можно менять в любой момент без последствий.
Если изменяется build-time option, может потребоваться повторный:

kc.sh build

Это важно учитывать при автоматизации и обновлении.

22. keycloak.conf — лучше, чем километровая командная строка

Технически можно запустить:

kc.sh start \
  --hostname=... \
  --db=... \
  --db-url=... \
  --proxy-headers=...

Для теста удобно.
Для постоянного сервиса это быстро становится неудобно.
Основную конфигурацию разумнее хранить в:

keycloak.conf

или отдельном configuration file.
Тогда:

systemd
   ↓
kc.sh start --optimized
   ↓
configuration file

гораздо понятнее для эксплуатации.

23. Но конфигурация имеет приоритеты

Если один параметр задан одновременно:

CLI
environment
keycloak.conf

результат может оказаться не тем, который администратор ожидает.
В Keycloak настройки имеют приоритет.
Упрощённо:

command line
     ↓
environment
     ↓
keycloak.conf

Поэтому если в файле написано:

hostname=sso.example.ru

а systemd передаёт:

KC_HOSTNAME=old-sso.example.ru

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

24. Без контейнера systemd становится частью архитектуры

В контейнере жизненным циклом процесса обычно управляет runtime/orchestrator.
На обычном Linux эту роль удобно передать systemd.
Схема:

Linux boot
   ↓
systemd
   ↓
Keycloak
   ↓
health check
   ↓
ready

Unit должен определить минимум:

• — пользователя;
• — рабочий каталог;
• — команду запуска;
• — источник конфигурации;
• — поведение при ошибке;
• — корректную остановку.

Например, логика может выглядеть:

User=keycloak
ExecStart=.../kc.sh start --optimized
Restart=on-failure

Но это не универсальный unit, который нужно просто скопировать.
Его параметры должны соответствовать конкретной установке.

25. systemctl active опять не будет достаточной проверкой

После установки:

systemctl status keycloak

может показать:

active (running)

Это подтверждает:
процесс Keycloak запущен.
Но ещё не:
Keycloak готов аутентифицировать пользователей.
Лучше пройти несколько уровней:

systemd
  ↓
health/ready
  ↓
OIDC discovery
  ↓
Admin Console
  ↓
test client
  ↓
login flow

То есть проверяем не только процесс, а реальную функцию системы.