Установка Keycloak

В этой шпаргалке очень кратко напишу, как выполняется установка Keycloak. Установка будет выполняться в режиме prod с выделенным сервером баз данных (MariaDB), который расположен на хосте с сервером Keycloak.

В качестве сервера я буду использовать Ubuntu Server 22.04.

Подготовка сервера баз данных

Сначала нужно подготовить сервер баз данных. Keycloak поддерживает несколько внешних серверов баз данных.

Установим сервер MariaDB и настроим его автозапуск:

sudo apt install -y mariadb-server
sudo systemctl enable mariadb

Проверим статус сервера баз данных:

sudo systemctl status mariadb

Выполним первоначальную настройку сервера MariaDB:

mysql_secure_installation
NOTE: RUNNING ALL PARTS OF THIS SCRIPT IS RECOMMENDED FOR ALL MariaDB
      SERVERS IN PRODUCTION USE!  PLEASE READ EACH STEP CAREFULLY!

In order to log into MariaDB to secure it, we'll need the current
password for the root user. If you've just installed MariaDB, and
haven't set the root password yet, you should just press enter here.

Enter current password for root (enter for none): 
OK, successfully used password, moving on...

Setting the root password or using the unix_socket ensures that nobody
can log into the MariaDB root user without the proper authorisation.

You already have your root account protected, so you can safely answer 'n'.

Switch to unix_socket authentication [Y/n] n
 ... skipping.

You already have your root account protected, so you can safely answer 'n'.

Change the root password? [Y/n] y
New password: 
Re-enter new password: 
Password updated successfully!
Reloading privilege tables..
 ... Success!


By default, a MariaDB installation has an anonymous user, allowing anyone
to log into MariaDB without having to have a user account created for
them.  This is intended only for testing, and to make the installation
go a bit smoother.  You should remove them before moving into a
production environment.

Remove anonymous users? [Y/n] y
 ... Success!

Normally, root should only be allowed to connect from 'localhost'.  This
ensures that someone cannot guess at the root password from the network.

Disallow root login remotely? [Y/n] y
 ... Success!

By default, MariaDB comes with a database named 'test' that anyone can
access.  This is also intended only for testing, and should be removed
before moving into a production environment.

Remove test database and access to it? [Y/n] y
 - Dropping test database...
 ... Success!
 - Removing privileges on test database...
 ... Success!

Reloading the privilege tables will ensure that all changes made so far
will take effect immediately.

Reload privilege tables now? [Y/n] y
 ... Success!

Cleaning up...

All done!  If you've completed all of the above steps, your MariaDB
installation should now be secure.

Thanks for using MariaDB!

Создадим отдельную базу данных и пользователя для неё:

mysql -u root -p
CREATE DATABASE kk CHARACTER SET utf8mb3;
CREATE USER kkuser@localhost IDENTIFIED BY 'Qwerty123';
GRANT ALL PRIVILEGES ON kk.* TO 'kkuser'@'localhost';
FLUSH PRIVILEGES;
exit

Загрузка дистрибутива и предварительная сборка

Теперь загрузим дистрибутив и выполним предварительную сборку. Ссылку на актуальную версию дистрибутива можно получить на странице загрузки.

Создадим отдельного пользователя и группу:

groupadd keycloak
useradd -g keycloak -m -s /bin/bash keycloak

Загрузим дистрибутив:

wget https://github.com/keycloak/keycloak/releases/download/22.0.1/keycloak-22.0.1.tar.gz

Распакуем архив:

tar -xvf keycloak-22.0.1.tar.gz

Переместим все файлы сервера в отдельную директорию в каталоге /opt:

sudo mkdir /opt/keycloak
sudo mv keycloak-22.0.1/ /opt/keycloak/
sudo chown -R keycloak:keycloak /opt/keycloak/keycloak-22.0.1/

Также нам понадобится java:

sudo apt install -y openjdk-19-jre

Выполним сборку сервера:

/opt/keycloak/keycloak-22.0.1/bin/kc.sh build --db=mariadb
Updating the configuration and installing your custom providers, if any. Please wait.
2023-07-30 07:40:12,377 INFO  [io.quarkus.deployment.QuarkusAugmentor] (main) Quarkus augmentation completed in 3738ms
Server configuration updated and persisted. Run the following command to review the configuration:

	kc.sh show-config

Если в процессе сборки генерируется ошибка “ERROR: The following build time options have values that differ from what is persisted – the new values will NOT be used until another build is run: kc.health-enabled, kc.metrics-enabled”, то попробуйте дополнительно указать еще ключи в командную строку
–health-enabled=true –metrics-enabled=true
По итогу команда будут следующая:
/opt/keycloak/keycloak-22.0.1/bin/kc.sh build –db=mariadb –health-enabled=true –metrics-enabled=true

Настройка и установка Keycloak

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

Сертификат можно использовать имеющийся, либо выпустить бесплатный сертификат от Let’s Encrypt.

Я складирую сертификаты в директорию /etc/keycloak/certs:

sudo mkdir -p /etc/keycloak/certs

Также настроим соответствующие разрешения для сертификатов:

chmod 400 /etc/keycloak/certs/*
sudo chown -R keycloak:keycloak /etc/keycloak/certs/
ls -l /etc/keycloak/certs/
root@kk:/home/roman# chmod 400 /etc/keycloak/certs/*
root@kk:/home/roman# sudo chown -R keycloak:keycloak /etc/keycloak/certs/
root@kk:/home/roman# ls -l /etc/keycloak/certs/
total 8
-r-------- 1 root root 2074 Jul 30 07:51 itproblog.crt
-r-------- 1 root root 2455 Jul 30 07:51 itproblog.key
root@kk:/home/roman# 

Теперь скорректируем конфигурационный файл:

sudo nano /opt/keycloak/keycloak-22.0.1/conf/keycloak.conf

Необходимо скорректировать в конфигурационном файл параметры типа и подключения к базе данных, прослушиваемого имени и т.д. Пример моего итогового файла конфигурации:

# Database

# The database vendor.
db=mariadb 

# The username of the database user.
db-username=kkuser  

# The password of the database user.
db-password=Qwerty123

# The full database JDBC URL. If not provided, a default URL is set based on the selected database vendor.
db-url=jdbc:mariadb://localhost/kk      

# Observability

# If the server should expose healthcheck endpoints.
health-enabled=true

# If the server should expose metrics endpoints.
metrics-enabled=true

# HTTP

# The file path to a server certificate or certificate chain in PEM format.
https-certificate-file=/etc/keycloak/certs/itproblog.crt

# The file path to a private key in PEM format.
https-certificate-key-file=/etc/keycloak/certs/itproblog.key

# The proxy address forwarding mode if the server is behind a reverse proxy.
#proxy=reencrypt

# Do not attach route to cookies and rely on the session affinity capabilities from reverse proxy
#spi-sticky-session-encoder-infinispan-should-attach-route=false

# Hostname for the Keycloak server.
hostname=kk.itproblog.ru

https-port=443

Также перед первым запуском сервера необходимо указать логин и пароль для администратора. Сделать это можно через переменные окружения. Эта операция разовая, при последующим запусках переменные окружения устаналивать не нужно:

export KEYCLOAK_ADMIN=admin
export KEYCLOAK_ADMIN_PASSWORD=admin

Сначала попробуем запустить сервер интерактивно:

/opt/keycloak/keycloak-22.0.1/bin/kc.sh start --optimized

Ниже приведен листинг успешного запуска сервера:

root@kk:/home/roman# /opt/keycloak/keycloak-22.0.1/bin/kc.sh start --optimized
2023-07-30 08:07:51,980 INFO  [org.keycloak.quarkus.runtime.hostname.DefaultHostnameProvider] (main) Hostname settings: Base URL: <unset>, Hostname: kk.itproblog.ru, Strict HTTPS: true, Path: <request>, Strict BackChannel: false, Admin URL: <unset>, Admin: <request>, Port: -1, Proxied: false
2023-07-30 08:07:52,733 WARN  [io.quarkus.runtime.configuration.DeprecatedRuntimePropertiesRecorder] (main) The 'quarkus.http.ssl.certificate.file' config property is deprecated and should not be used anymore
2023-07-30 08:07:52,733 WARN  [io.quarkus.runtime.configuration.DeprecatedRuntimePropertiesRecorder] (main) The 'quarkus.http.ssl.certificate.key-file' config property is deprecated and should not be used anymore
2023-07-30 08:07:52,900 WARN  [io.quarkus.agroal.runtime.DataSources] (main) Datasource <default> enables XA but transaction recovery is not enabled. Please enable transaction recovery by setting quarkus.transaction-manager.enable-recovery=true, otherwise data may be lost if the application is terminated abruptly
2023-07-30 08:07:53,386 WARN  [org.infinispan.PERSISTENCE] (keycloak-cache-init) ISPN000554: jboss-marshalling is deprecated and planned for removal
2023-07-30 08:07:53,460 INFO  [org.infinispan.CONTAINER] (keycloak-cache-init) ISPN000556: Starting user marshaller 'org.infinispan.jboss.marshalling.core.JBossUserMarshaller'
2023-07-30 08:07:53,538 INFO  [org.infinispan.CLUSTER] (keycloak-cache-init) ISPN000088: Unable to use any JGroups configuration mechanisms provided in properties {}. Using default JGroups configuration!
2023-07-30 08:07:53,645 INFO  [org.infinispan.CLUSTER] (keycloak-cache-init) ISPN000078: Starting JGroups channel `ISPN`
2023-07-30 08:07:53,646 INFO  [org.jgroups.JChannel] (keycloak-cache-init) local_addr: dd4eac50-dca9-4043-8100-56bcb4be0e25, name: kk-41945
2023-07-30 08:07:53,650 WARN  [org.jgroups.protocols.UDP] (keycloak-cache-init) JGRP000015: the send buffer of socket MulticastSocket was set to 1MB, but the OS only allocated 212.99KB
2023-07-30 08:07:53,651 WARN  [org.jgroups.protocols.UDP] (keycloak-cache-init) JGRP000015: the receive buffer of socket MulticastSocket was set to 20MB, but the OS only allocated 212.99KB
2023-07-30 08:07:53,651 WARN  [org.jgroups.protocols.UDP] (keycloak-cache-init) JGRP000015: the send buffer of socket MulticastSocket was set to 1MB, but the OS only allocated 212.99KB
2023-07-30 08:07:53,651 WARN  [org.jgroups.protocols.UDP] (keycloak-cache-init) JGRP000015: the receive buffer of socket MulticastSocket was set to 25MB, but the OS only allocated 212.99KB
2023-07-30 08:07:53,657 INFO  [org.jgroups.protocols.FD_SOCK2] (keycloak-cache-init) server listening on *.18223
2023-07-30 08:07:55,661 INFO  [org.jgroups.protocols.pbcast.GMS] (keycloak-cache-init) kk-41945: no members discovered after 2001 ms: creating cluster as coordinator
2023-07-30 08:07:55,669 INFO  [org.infinispan.CLUSTER] (keycloak-cache-init) ISPN000094: Received new cluster view for channel ISPN: [kk-41945|0] (1) [kk-41945]
2023-07-30 08:07:55,683 INFO  [org.infinispan.CLUSTER] (keycloak-cache-init) ISPN000079: Channel `ISPN` local address is `kk-41945`, physical addresses are `[10.10.10.87:33759]`
2023-07-30 08:07:55,965 INFO  [org.keycloak.connections.infinispan.DefaultInfinispanConnectionProviderFactory] (main) Node name: kk-41945, Site name: null
2023-07-30 08:07:56,019 INFO  [org.keycloak.broker.provider.AbstractIdentityProviderMapper] (main) Registering class org.keycloak.broker.provider.mappersync.ConfigSyncEventListener
2023-07-30 08:07:56,689 INFO  [io.quarkus] (main) Keycloak 22.0.1 on JVM (powered by Quarkus 3.2.0.Final) started in 5.431s. Listening on: https://0.0.0.0:443
2023-07-30 08:07:56,689 INFO  [io.quarkus] (main) Profile prod activated. 
2023-07-30 08:07:56,689 INFO  [io.quarkus] (main) Installed features: [agroal, cdi, hibernate-orm, jdbc-h2, jdbc-mariadb, jdbc-mssql, jdbc-mysql, jdbc-oracle, jdbc-postgresql, keycloak, logging-gelf, micrometer, narayana-jta, reactive-routes, resteasy, resteasy-jackson, smallrye-context-propagation, smallrye-health, vertx]

Проверка

Теперь перейдем по тому имени, которое мы с вами настроили в конфигурационном файл:

https://kk.itproblog.ru/

Должна отобразиться стартовая страница Keycloak.

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

В случае успешной аутентификации вы попадете на главную страницу панели администрирования:

Настройка юнита для запуска сервера

Последний штрих – это настройка юнита для автоматического запуска сервера. Потому что запуска сервер каждый раз интерактивно руками недопустимо.

Создадим новый юнит:

sudo touch /lib/systemd/system/keycloak.service
sudo chmod 664 /lib/systemd/system/keycloak.service

Содержимое файла keycloak.service:

[Unit]
Description=Keycloak Server
After=network.target mariadb.service

[Service]
User=keycloak
Group=keycloak
SuccessExitStatus=0 143
ExecStart=/opt/keycloak/keycloak-22.0.1/bin/kc.sh start --optimized

[Install]
WantedBy=multi-user.target

Дополнительно необходимо разрешить java выполнять привязку для портов:

sudo setcap CAP_NET_BIND_SERVICE=+eip /usr/lib/jvm/java-19-openjdk-amd64/bin/java

Теперь попробуем настроить автоматический запуск сервиса и запустим его:

sudo systemctl daemon-reload
sudo systemctl enable keycloak.service
sudo systemctl start keycloak.service
sudo systemctl status keycloak.service

Установка Keycloak завершена.

Установка Keycloak: 5 комментариев

  1. /opt/keycloak/keycloak-22.0.1/bin/kc.sh start –optimized
    тут походу надо ключ -Е написать, чтобы передать админа

  2. Имхо, в гайде ошибочка небольшая:
    Когда собираешь сервер нужно дополнительно указать еще ключи в командную строку
    –health-enabled=true –metrics-enabled=true, что в итоге выглядит вот так:
    /opt/keycloak/keycloak-22.0.1/bin/kc.sh build –db=mariadb –health-enabled=true –metrics-enabled=true

    Иначе конфиг с указанным конфигом сервер не запустится, а будет выдавать вот такой “отлуп”:
    root@host: # /opt/keycloak/keycloak-26.0.5/bin/kc.sh start –optimized
    ERROR: The following build time options have values that differ from what is persisted – the new values will NOT be used until another build is run: kc.health-enabled, kc.metrics-enabled

    1. Добрый день! Спасибо за замечание. С момента публикации статьи прошло уже более года. Что-то в процессе установки могло поменяться, но я добавлю соответствующее примечание.

      1. добавлю, что данную ошибку словил на версии 26.0.5, 26.0.4
        что про другие релизы – не знаю, не пробовал

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *