В современном цифровом мире вопросы аутентификации и авторизации пользователей выходят на первый план. Разработчикам и администраторам систем требуется надёжное, гибкое и безопасное решение для управления идентификацией — без избыточных затрат времени на реализацию «с нуля». Именно здесь на помощь приходят специализированные IAM-системы (Identity and Access Management), которые позволяют централизованно управлять учётными записями, правами доступа и политиками безопасности.
Keycloak — один из наиболее популярных open‑source‑продуктов в этой области. Он предоставляет полнофункциональный сервер идентификации и доступа (Identity and Access Management, IAM), позволяющий:
- управлять пользователями и их ролями;
- реализовывать единый вход (Single Sign‑On, SSO) для множества приложений;
- интегрировать внешние провайдеры идентификации (соцсети, корпоративные IDP, например, LDAP или Active Directory);
- настраивать политики безопасности, двухфакторную аутентификацию, брандмауэр для сессий и многое другое.
Keycloak широко применяется в корпоративных средах, где требуется быстро развернуть централизованную систему аутентификации без привязки к конкретному вендору. Благодаря гибкой настройке и поддержке стандартов OAuth 2.0, OpenID Connect и SAML, он легко встраивается в существующую инфраструктуру.
В этой статье мы шаг за шагом развернём Keycloak на сервере с Ubuntu 22.04: начнём с тестового запуска в режиме разработки, а затем перейдём к полноценной production-конфигурации с использованием reverse proxy (Nginx), SSL-сертификата Let’s Encrypt и базы данных PostgreSQL. Также настроим автозапуск через SystemD.
Тестовый запуск Keycloak
Прежде чем приступать к production-развёртыванию, полезно проверить работоспособность Keycloak в упрощённом режиме. Это позволит убедиться, что все зависимости установлены корректно, и познакомиться с интерфейсом.
Страница загрузки Keycloak находится по адресу: https://www.keycloak.org/downloads. Там можно выбрать последнюю стабильную версию (на момент написания статьи — 26.7.0).
Keycloak представляет собой Java-приложение, поэтому его можно запустить так же, как и любое другое Java-приложение (например, Jira или Jenkins). Для работы требуется OpenJDK 21.
Устанавливаем необходимые пакеты:
# apt-get install openjdk-21-jreЗагружаем и распаковываем архив:
# cd /tmp/
# wget https://github.com/keycloak/keycloak/releases/download/26.7.0/keycloak-26.7.0.tar.gz
# tar -xvf ./keycloak-26.7.0.tar.gz
# mv ./keycloak-26.7.0 /opt/keycloakПодготавливаем окружение: создаём отдельного системного пользователя keycloak, назначаем права и запускаем сервер в режиме разработки:
# useradd keycloak
# mkdir /home/keycloak
# chown keycloak:keycloak /home/keycloak
# cd /opt/keycloak/
# chown -R keycloak:keycloak /opt/keycloak/
# su keycloak -s /bin/bash
$ bin/kc.sh start-devОбратите внимание: мы запустили Keycloak с ключом start-dev. Это режим разработки, предназначенный для быстрой проверки работоспособности. В этом режиме используется встроенная база данных H2, а все настройки безопасности упрощены. Для production-среды такой режим не подходит.
Сервис запускается на порту 8080, и мы можем сразу подключиться к веб-интерфейсу управления по адресу http://<IP-сервера>:8080.
Настройка Production Keycloak
Для production-развёртывания необходимо обеспечить безопасное соединение (HTTPS), использовать внешнюю базу данных (например, PostgreSQL) и настроить reverse proxy (Nginx) для балансировки нагрузки и дополнительной защиты.
Регистрация домена и получение SSL-сертификата
Сначала зарегистрируем доменное имя у регистратора (в примере используется kc.interlan.xyz). Затем настраиваем DNS-запись типа A, указывающую на IP-адрес нашего сервера.
После того как домен делегирован, получаем бесплатный SSL-сертификат от Let’s Encrypt с помощью Certbot. Предполагается, что Nginx уже установлен и настроен для работы с доменом (хотя бы базовый конфиг).
Выполняем команду:
# certbot certonly --nginx -d kc.interlan.xyzCertbot автоматически проверит владение доменом и выдаст сертификат. Файлы сертификата будут сохранены в /etc/letsencrypt/live/kc.interlan.xyz/.
Настройка reverse proxy (Nginx)
Конфигурация reverse proxy для Keycloak типовая. Ниже приведён полный конфигурационный файл для Nginx. Он включает перенаправление с HTTP на HTTPS, настройку заголовков для корректной работы прокси, а также поддержку WebSocket (если потребуется).
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
server_name www.kc.interlan.xyz kc.interlan.xyz;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name www.kc.interlan.xyz kc.interlan.xyz;
access_log /var/log/nginx/kc.interlan.xyz-access.log;
error_log /var/log/nginx/kc.interlan.xyz-error.log warn;
ssl_certificate /etc/letsencrypt/live/kc.interlan.xyz/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/kc.interlan.xyz/privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload;" always;
client_max_body_size 64M;
fastcgi_buffers 64 4K;
proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;
gzip on;
gzip_vary on;
gzip_comp_level 4;
gzip_min_length 256;
gzip_proxied expired no-cache no-store private no_last_modified no_etag auth;
gzip_types application/atom+xml application/javascript application/json application/ld+json application/manifest+json application/rss+xml application/vnd.geo+json application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/bmp image/svg+xml image/x-icon text/cache-manifest text/css text/plain text/vcard text/vnd.rim.location.xloc text/vtt text/x-component text/x-cross-domain-policy;
if ($host ~ ^www\.(?<domain>.+)$) {
return 301 $scheme://$domain$request_uri;
}
location / {
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Scheme $scheme;
proxy_pass http://127.0.0.1:8080;
}
}После сохранения конфигурации проверяем её синтаксис и перезагружаем Nginx:
# nginx -t
# systemctl reload nginxТеперь сервис Keycloak должен быть доступен по доменному имени через HTTPS. Однако пока он работает в режиме разработки, поэтому не имеет смысла создавать административного пользователя. Прежде всего необходимо настроить работу с базой данных.
Настройка базы данных PostgreSQL
Keycloak по умолчанию использует встроенную базу H2, которая не подходит для production. Мы будем использовать PostgreSQL или MySQL. Устанавливаем PostgreSQL, если он ещё не установлен:
# apt-get install postgresql postgresql-clientЗапускаем PostgreSQL и создаём базу данных и пользователя:
# sudo -u postgres psqlВ консоли PostgreSQL выполняем:
CREATE USER keycloak_user WITH PASSWORD 'xxxPASSWORDxxx';
CREATE DATABASE keycloak_db OWNER keycloak_user;Выходим из psql (\q).
Теперь редактируем конфигурационный файл Keycloak /opt/keycloak/conf/keycloak.conf. Добавляем следующие строки (заменив пароль на свой):
db=postgres
db-username=keycloak_user
db-password=xxxPASSWORDxxx
db-url=jdbc:postgresql://127.0.0.1/keycloak_dbПосле внесения изменений перезапускаем Keycloak. Поскольку мы запускали его вручную в режиме разработки, просто остановите процесс (Ctrl+C) и запустите снова, но уже без ключа start-dev. Однако для production мы будем использовать SystemD, поэтому пока можно просто проверить, что база данных инициализируется.
Запустите Keycloak от пользователя keycloak:
# su keycloak -s /bin/bash
# cd /opt/keycloak
# bin/kc.sh start-devПри первом запуске Keycloak автоматически создаст необходимые таблицы в PostgreSQL. Вы можете убедиться в этом, подключившись к базе данных:
# sudo -u postgres psql -d keycloak_db -c "\dt"Должен появиться список таблиц, начинающихся с REALM_, USER_ и т.д.
Если вы используете ProxySQL (как в моем случае), то вы получите ошибку.
HHH100046: Could not obtain connection to query JDBC database metadata: org.hibernate.exception.GenericJDBCException: Unable to obtain isolated JDBC connection [Unknown system variable 'query_cache_size']Эта проблема возникает из-за того, что ProxySQL маскируется под старую версию MySQL (обычно 5.5.x или 5.7.x), сообщая её вашему JDBC-драйверу при рукопожатии (handshake).Когда современный JDBC-драйвер (версии 8.x) подключается к БД напрямую, он видит реальную версию MySQL 8.0+, знает, что переменной query_cache_size там больше нет, и не запрашивает её. Но когда он подключается через ProxySQL, прокси сообщает ему: «Я — MySQL 5.5». Драйвер верит этому, пытается выполнить запрос @@query_cache_size для инициализации сессии, а сама база данных (или ProxySQL) отклоняет этот запрос с ошибкой Unknown system variable.
Рекомендую установить отдаваемую ProxySQL версию на реальную.
UPDATE global_variables SET variable_value='8.0.29' WHERE variable_name='mysql-server_version';
LOAD MYSQL VARIABLES TO RUNTIME;
SAVE MYSQL VARIABLES TO DISK;Создание административного пользователя
Для доступа к веб-интерфейсу управления Keycloak необходимо создать административного пользователя. Поскольку сервер пока слушает только localhost (порт 8080), мы воспользуемся SSH-туннелем с пробросом портов. Выполните на своей локальной машине:
$ ssh root@185.135.81.157 -L:8080:127.0.0.1:8080Теперь откройте в браузере http://localhost:8080. Вы увидите страницу создания административного пользователя. Заполните поля (логин, пароль, email) и нажмите «Create».
После этого вы сможете войти в консоль управления Keycloak.
Настройка production-режима и SystemD
Теперь, когда всё работает, переведём Keycloak в полноценный production-режим и настроим автозапуск через SystemD.
Внесём дополнительные изменения в конфигурационный файл /opt/keycloak/conf/keycloak.conf, чтобы Keycloak корректно работал за reverse proxy:
http-enabled=true
proxy-trusted-addresses=185.135.81.157,127.0.0.0/8
proxy-headers=xforwarded
hostname=https://kc.interlan.xyzПояснения:
— http-enabled=true — разрешает HTTP-соединения (они будут обрабатываться Nginx, который уже использует HTTPS).
— proxy-trusted-addresses — список IP-адресов, которым доверяется установка заголовков X-Forwarded-*. Укажите внешний IP вашего сервера и локальные адреса.
— proxy-headers=xforwarded — указывает Keycloak использовать заголовки X-Forwarded-* для определения протокола и хоста.
— hostname — задаёт внешнее имя хоста, которое будет использоваться в ссылках и редиректах.
Теперь создадим SystemD-сервис. Файл /lib/systemd/system/keycloak.service.
[Unit]
Description=Keycloak service
After=syslog.target network.target
[Service]
WorkingDirectory=/opt/keycloak
User=keycloak
ExecStart=/opt/keycloak/bin/kc.sh start
[Install]
WantedBy=multi-user.targetПолучили типовую SystemD-запускалку и теперь перезагружаем конфигурацию SystemD, включаем автозапуск и запускаем сервис:
# systemctl daemon-reload
# systemctl enable keycloak.service
# systemctl start keycloak.serviceПроверяем статус:
# systemctl status keycloak.serviceЕсли всё в порядке, Keycloak будет автоматически запускаться при старте системы.
Заключение
Мы успешно установили и настроили Keycloak на Ubuntu 24.04: от тестового запуска до полноценного production-окружения с reverse proxy, SSL-сертификатом и PostgreSQL. Теперь вы можете использовать Keycloak для централизованного управления доступом к вашим приложениям. Дальнейшие шаги включают настройку realms, клиентов, ролей и интеграцию с внешними провайдерами.
