Как установить Keycloak на Ubuntu и Debian

Keycloak – система управления идентификацией и доступом с открытым исходным кодом. Система позволяет централизовать аутентификацию пользователей, управлять учётными записями и организовать единый вход (Single Sign-On, SSO) в веб-приложения и корпоративные сервисы.

При помощи Keycloak можно использовать одну учётную запись для доступа к нескольким приложениям, настроить многофакторную аутентификацию и интегрировать существующие каталоги пользователей, например, Active Directory или LDAP. Для взаимодействия с приложениями поддерживаются протоколы OpenID Connect, OAuth 2.0 и SAML 2.0.

В статье разберём, как установить Keycloak на виртуальный выделенный сервер, работающий под управлением Ubuntu или Debian.

Как установить Keycloak на Ubuntu и Debian

Установка и предварительная настройка Java и PostgreSQL

Перед началом работ по установке программного обеспечения обновите списки пакетов в системе:

$ sudo apt update

Актуальная на момент написания статьи версия Keycloak требует установки Java 25 или более поздней поддерживаемой версии. В данном случае используйте OpenJDK 25:

$ sudo apt install openjdk-25-jdk

После завершения установки проверьте версию Java:

$ java -version

Для рабочей установки рекомендуется использовать СУБД PostgreSQL, а не встроенную файловую базу, предназначенную для разработки. Keycloak поддерживает PostgreSQL и использует его для хранения пользователей, клиентов, настроек и других данных. Следующей командой установите PostgreSQL:

$ sudo apt install postgresql

В результате в системе будет создана служба postgresql, которая сразу после инсталляции будет запущена и установлена в автозагрузку. Чтобы убедиться в этом, выведите на экран её текущее состояние:

$ systemctl status postgresql

После чего подключитесь к командной строке PostgreSQL:

$ sudo -u postgres psql

Подключившись, создайте пользователя PostgreSQL. В данном случае keycloak – это имя создаваемой учётной записи, а Keycloak_P@ssw0rd – её пароль.

CREATE USER keycloak WITH PASSWORD 'Keycloak_P@ssw0rd';

Данный пользователь нужен приложению Keycloak для подключения к СУБД.

Затем создайте базу данных. Следующая команда создаст базу данных с именем keycloak и назначит её владельцем пользователя keycloak:

CREATE DATABASE keycloak OWNER keycloak;

После чего отключитесь от командной оболочки PostgreSQL:

\q

Установка Keycloak

На следующем шаге создайте в системе отдельного системного пользователя keycloak, от имени которого будет запускаться сервер Keycloak:

$ sudo useradd --system --home-dir /opt/keycloak --shell /usr/sbin/nologin keycloak

Здесь:

• --system – параметр, который говорит о том, что создаваемый пользователь является системной учётной записью, предназначенной для работы служб и приложений;
• --home-dir /opt/keycloak – домашний каталог пользователя, в котором будут размещаться файлы приложения;
• --shell /usr/sbin/nologin – параметр, запрещающий интерактивный вход в систему под именем создаваемой учётной записи;
• keycloak – имя создаваемого пользователя.

Дистрибутивы Keycloak в виде архивов размещены на странице сервиса в GitHub. Для загрузки файла дистрибутива используется утилита curl. Следующей командой установите данную утилиту в систему:

$ sudo apt install curl

На своём локальном компьютере откройте браузер и перейдите на GitHub-страницу релизов Keycloak. Здесь выберите версию и скопируйте в буфер обмена ссылку на загрузку файла архива с расширением tar.gz.

Затем вернитесь к терминалу виртуального сервера и при помощи утилиты curl и скопированной ссылки загрузите дистрибутив Keycloak в текущий каталог:

$ curl -fLO https://github.com/keycloak/keycloak/releases/download/26.8.0/keycloak-26.8.0.tar.gz

Дождитесь окончания загрузки и разархивируйте файл в каталог /opt:

$ sudo tar -xvzf keycloak-26.8.0.tar.gz -C /opt/

Затем переименуйте полученный при разархивировании каталог в keycloak:

$ sudo mv /opt/keycloak-26.8.0/ /opt/keycloak

После чего измените владельца каталога /opt/keycloak и всех файлов и подкаталогов внутри него на пользователя и группу keycloak:

$ sudo chown -R keycloak:keycloak /opt/keycloak

Запустите скрипт kc.sh, который входит в состав Keycloak, от имени системного пользователя keycloak, для того, чтобы вывести версию Keycloak:

$ sudo -u keycloak /opt/keycloak/bin/kc.sh --version

Предварительная настройка конфигурации Keycloak

Далее откройте конфигурационный файл Keycloak:

$ sudo nano /opt/keycloak/conf/keycloak.conf

Приведите содержимое данного файла к следующему виду:

db=postgres
db-username=keycloak
db-password=Keycloak_P@ssw0rd
db-url=jdbc:postgresql://localhost:5432/keycloak

hostname=localhost
http-enabled=true
http-host=127.0.0.1
http-port=8080

Данная конфигурация содержит следующие параметры:

• db=postgres – указывает, что для хранения данных Keycloak используется PostgreSQL;
• db-username – задаёт имя пользователя PostgreSQL, от имени которого Keycloak подключается к базе данных;
• db-password – задаёт пароль пользователя PostgreSQL, который должен совпадать с паролем, установленным при создании учётной записи в СУБД;
• db-url=jdbc:postgresql://localhost:5432/keycloak – определяет адрес подключения к базе данных, где localhost – сервер базы данных на этой же машине, 5432 – порт PostgreSQL, keycloak – имя базы данных;
• hostname – задаёт имя хоста, которое Keycloak будет использовать при формировании URL-адресов и обработке запросов, в данной конфигурации для первоначальной проверки указано локальное имя;
• http-enabled=true – включает HTTP для доступа к веб-интерфейсу и API Keycloak;
• http-host=127.0.0.1 – ограничивает прослушивание HTTP локальным сетевым интерфейсом сервера;
• http-port=8080 – задаёт TCP-порт, на котором Keycloak будет принимать HTTP-запросы.

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

$ sudo chown keycloak:keycloak /opt/keycloak/conf/keycloak.conf
$ sudo chmod 600 /opt/keycloak/conf/keycloak.conf

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

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

На следующем шаге создайте каталог keycloak в директории /etc:

$ sudo mkdir -p /etc/keycloak

В этом каталоге создайте файл, в котором будут содержаться переменные окружения для службы Keycloak:

$ sudo nano /etc/keycloak/keycloak.env

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

KC_BOOTSTRAP_ADMIN_USERNAME=kcadmin
KC_BOOTSTRAP_ADMIN_PASSWORD=Admin_P@ssw0rd

Поскольку в файле хранится пароль, после его сохранения необходимо ограничить доступ к данному файлу:

$ sudo chown root:root /etc/keycloak/keycloak.env
$ sudo chmod 600 /etc/keycloak/keycloak.env

Запуск Keycloak в качестве системного сервиса

Чтобы Keycloak работал как системный сервис, создайте для него юнит-файл:

$ sudo nano /etc/systemd/system/keycloak.service

В файл вставьте следующий текст:

[Unit]
Description=Keycloak Identity and Access Management
After=network-online.target postgresql.service
Wants=network-online.target
Requires=postgresql.service

[Service]
Type=simple
User=keycloak
Group=keycloak
EnvironmentFile=/etc/keycloak/keycloak.env
WorkingDirectory=/opt/keycloak
ExecStart=/opt/keycloak/bin/kc.sh start --optimized
Restart=on-failure
RestartSec=5
TimeoutStartSec=300
TimeoutStopSec=60
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Закройте файл с сохранением изменений, после чего обновите конфигурацию systemd:

$ sudo systemctl daemon-reload

Затем установите новую службу в автозагрузку с одновременным её стартом:

$ sudo systemctl enable --now keycloak

Чтобы убедиться в том, что служба стартовала без ошибок, выведите её текущее состояние:

$ systemctl status keycloak

Если служба стартовала без ошибок, на локальном компьютере откройте ещё один терминал. Здесь при помощи следующей команды установите SSH-соединение с удалённым сервером и создайте туннель, перенаправляющий обращения к порту 8080 на локальном компьютере на порт 8080 удалённого сервера:

ssh -L 8080:127.0.0.1:8080 your-user@X.X.X.X

В данной команде замените your-user на имя вашего пользователя в системе, а X.X.X.X – на IP-адрес виртуальной машины.

Затем откройте браузер и перейдите по ссылке http://localhost:8080/admin/. При первом подключении необходимо будет авторизоваться под учётной записью администратора, созданной при настройке Keycloak. В нашем примере – это пользователь kcadmin.

В результате вы попадёте в административную консоль Keycloak – веб-интерфейс для управления пользователями, учётными записями, клиентами, ролями и настройками аутентификации. Адрес localhost в данном случае указывает на ваш собственный компьютер, а благодаря SSH-туннелю запросы перенаправляются на Keycloak, установленный на удалённом сервере.

Заключение

Далее для использования Keycloak в рабочей инфраструктуре рекомендуется выполнить следующие действия:

1. Привязать к IP-адресу виртуального сервера доменное имя для настройки доступа по HTTPS.
2. Настроить HTTPS-доступ, например, с использованием Nginx в качестве обратного прокси и установкой TLS-сертификата.
3. Настроить резервное копирование PostgreSQL.
4. Создать отдельный Realm – изолированную область, в которой находятся пользователи, роли и настройки приложений. Для корпоративной инфраструктуры можно создать отдельный Realm для организации.
5. Для каждого сервиса настроить клиент Keycloak с подходящими параметрами OpenID Connect или SAML.
6. При необходимости интегрировать Active Directory, что позволит использовать существующие корпоративные учётные записи.