Keycloak на Ubuntu 24.04: пошаговая установка

MAATRIX

Если у вас три-пять внутренних сервисов и у каждого свой логин-пароль, а сотрудники хранят пароли в блокноте — рано или поздно это закончится инцидентом. Keycloak закрывает эту проблему: один сервер выдаёт токены по OAuth2/OIDC или SAML, а все приложения (Grafana, GitLab, свой бэкенд, внутренние панели) доверяют ему, а не проверяют пароли сами. Ниже — установка с нуля на чистой Ubuntu 24.04: PostgreSQL, systemd-сервис, reverse-proxy с SSL и первый realm с клиентом.

Что такое Keycloak и зачем он нужен

Keycloak — open-source identity-провайдер от Red Hat (сейчас развивается под эгидой CNCF), написан на Quarkus. Он умеет:

• OAuth2 / OpenID Connect для современных приложений и API;
• SAML 2.0 для legacy-систем, которые всё ещё на нём завязаны;
• федерацию с внешним LDAP/Active Directory;
• социальные логины (Google, GitHub и т. д.) как identity brokering;
• MFA (TOTP, WebAuthn), политики паролей, аудит входов.

Смысл в том, чтобы у вас в инфраструктуре была одна точка правды про пользователей и права, а не N сервисов с N локальными базами паролей. Это особенно оправдано, если приложений больше двух-трёх — на одном сервисе городить SSO обычно избыточно, но это тот случай, когда порог окупаемости достигается быстро.

Ресурсы под Keycloak в продакшене: от 2 vCPU / 4 ГБ RAM для небольшой команды (до пары сотен пользователей) до 4+ vCPU / 8 ГБ для нагрузки с активным API-трафиком — сам Keycloak на JVM ест память заметно, плюс отдельная база. Дальше — установка на VPS с Ubuntu 24.04 (Noble Numbat).

Подготовка сервера и Java

Keycloak работает на JVM, актуальные ветки требуют Java 21. Ставим OpenJDK и обновляем систему:

apt update && apt upgrade -y
apt install -y openjdk-21-jre-headless curl unzip
java -version

Должно показать openjdk version "21...". Дальше создаём отдельного системного пользователя — Keycloak не должен работать под root:

useradd -m -d /opt/keycloak -s /usr/sbin/nologin keycloak

Скачиваем дистрибутив с официального сайта проекта (проверьте актуальную версию на странице релизов — на момент написания это ветка 26.x):

cd /opt
curl -LO https://github.com/keycloak/keycloak/releases/download/26.0.0/keycloak-26.0.0.tar.gz
tar -xzf keycloak-26.0.0.tar.gz
mv keycloak-26.0.0 keycloak
chown -R keycloak:keycloak /opt/keycloak
rm keycloak-26.0.0.tar.gz

Версию подставьте актуальную — номер релиза мог измениться с момента публикации этой статьи.

PostgreSQL как база под Keycloak

Встроенная H2-база годится только для теста — в проде нужен полноценный PostgreSQL. Если ставите с нуля, см. пошаговую установку PostgreSQL на Ubuntu 24.04. Дальше создаём базу и пользователя специально под Keycloak:

sudo -u postgres psql <<EOF
CREATE DATABASE keycloak;
CREATE USER keycloak WITH ENCRYPTED PASSWORD 'смените_на_свой_пароль';
GRANT ALL PRIVILEGES ON DATABASE keycloak TO keycloak;
ALTER DATABASE keycloak OWNER TO keycloak;
EOF

Если PostgreSQL и Keycloak на одном сервере, pg_hba.conf можно оставить на md5/scram-sha-256 для локальных подключений — переписывать на trust не нужно, это дыра в безопасности, даже если сервер «внутренний».

Настройка и первый запуск Keycloak

Конфиг лежит в /opt/keycloak/conf/keycloak.conf. Правим под свою базу и домен:

# /opt/keycloak/conf/keycloak.conf
db=postgres
db-username=keycloak
db-password=смените_на_свой_пароль
db-url=jdbc:postgresql://localhost:5432/keycloak

hostname=auth.example.com
http-enabled=true
http-port=8080
proxy-headers=xforwarded

hostname — это домен, по которому пользователи будут заходить (укажите свой, реально привязанный к серверу). proxy-headers=xforwarded нужен, потому что перед Keycloak будет стоять nginx, и он должен доверять заголовкам X-Forwarded-*.

Собираем оптимизированный образ (Keycloak на Quarkus кэширует конфигурацию на этапе build) и запускаем bootstrap-администратора:

cd /opt/keycloak
sudo -u keycloak bin/kc.sh build

export KC_BOOTSTRAP_ADMIN_USERNAME=admin
export KC_BOOTSTRAP_ADMIN_PASSWORD='сложный_пароль'
sudo -u keycloak -E bin/kc.sh start --optimized

Первый запуск стоит сделать в интерактивном режиме, чтобы увидеть логи и убедиться, что нет ошибок подключения к базе. После проверки останавливаем (Ctrl+C) и переводим на systemd.

systemd-сервис и автозапуск

Создаём unit-файл:

# /etc/systemd/system/keycloak.service
[Unit]
Description=Keycloak Identity Provider
After=network.target postgresql.service

[Service]
Type=simple
User=keycloak
Group=keycloak
Environment=KC_BOOTSTRAP_ADMIN_USERNAME=admin
Environment=KC_BOOTSTRAP_ADMIN_PASSWORD=сложный_пароль
ExecStart=/opt/keycloak/bin/kc.sh start --optimized
Restart=on-failure
RestartSec=10
LimitNOFILE=102642

[Install]
WantedBy=multi-user.target

Хранить пароль администратора прямо в unit-файле — временное решение для первого запуска. После создания реального admin-пользователя через веб-консоль переменные KC_BOOTSTRAP_ADMIN_* из сервиса лучше убрать — они нужны только для самого первого bootstrap.

systemctl daemon-reload
systemctl enable --now keycloak
systemctl status keycloak

Если сервис не поднимается, первым делом смотрите journalctl -u keycloak -n 100 --no-pager — почти всегда причина в недоступности PostgreSQL или неверном пароле в конфиге.

Reverse-proxy с SSL

Keycloak по умолчанию слушает http на 8080 — наружу его пускать нельзя, нужен nginx с SSL спереди. Если сайт ещё не настроен на этом сервере, базовая установка веб-сервера описана в статье про настройку LEMP на Ubuntu 24.04. Конфиг для Keycloak:

server {
    listen 80;
    server_name auth.example.com;
    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    server_name auth.example.com;

    ssl_certificate     /etc/letsencrypt/live/auth.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/auth.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffer_size 128k;
        proxy_buffers 4 256k;
    }
}

Сертификат получаем через certbot:

apt install -y certbot python3-certbot-nginx
certbot --nginx -d auth.example.com

После этого не забудьте закрыть порт 8080 для внешнего мира на уровне firewall — снаружи должен быть доступен только 443. Если UFW ещё не настроен, см. пошаговую настройку firewall на Ubuntu 24.04:

ufw allow 443/tcp
ufw allow 80/tcp
ufw deny 8080/tcp

Первый realm и клиент OIDC

Заходим на https://auth.example.com, логинимся под bootstrap-администратором. Дальше стандартный путь настройки:

1. В master realm лучше не работать с обычными пользователями — создайте отдельный realm (например, company) через выпадающий список слева.
2. В новом realm откройте Clients → Create client, задайте Client ID (например, grafana), тип OpenID Connect.
3. Включите Client authentication (confidential-клиент для серверных приложений) или оставьте public — если это SPA без бэкенда.
4. Укажите Valid redirect URIs — реальный callback-адрес вашего приложения, без wildcard в проде.
5. На вкладке Credentials скопируйте Client secret — он понадобится в конфиге приложения.
6. В Users создайте тестового пользователя, задайте пароль на вкладке Credentials (снимите Temporary, если не хотите принудительной смены при первом входе).

Дальше в самом приложении (Grafana, свой бэкенд и т. д.) указываете стандартные OIDC-параметры: Issuer URL вида https://auth.example.com/realms/company, Client ID и Client secret из шага 5. Большинство современных сервисов имеют готовую интеграцию с generic OIDC — отдельный плагин под Keycloak обычно не нужен.

Для MFA откройте Authentication → Required actions и включите Configure OTP — это добавит TOTP при следующем входе пользователя, без правки конфигов приложений.

Частые вопросы