Пошаговая инструкция · Самостоятельная установка
Как установить Keycloak на Ubuntu: вход через HTTPS и PostgreSQL
Пошаговая инструкция для самостоятельной установки. Запустим Keycloak в рабочем режиме за Nginx, создадим отдельную область для пользователей и проверим OpenID Connect. Базу и административный доступ оставим закрытыми, а обновление подготовим через восстановление копии.
Что подготовить и как читать инструкцию #
В этой инструкции один Keycloak обслуживает вход в приложения небольшой команды. У него отдельная PostgreSQL и постоянный адрес https://sso.example.com. Это база для корпоративного входа, а не готовая отказоустойчивая инфраструктура: если остановится единственный сервер, новые входы станут недоступны. Для критичных сервисов заранее планируют резервный узел и обслуживание базы.
Подготовьте чистую Ubuntu 26.04 LTS по общей инструкции: SSH, Docker Engine, Compose v2, Nginx, домен и firewall. Контейнер приносит Java и серверные зависимости; устанавливать Java из Ubuntu для этого варианта не нужно. Совместимость контейнерного метода не означает, что нами проведено испытание выбранного хоста под реальной нагрузкой.
Команды выполняйте в терминале сервера после подключения по SSH, если шаг не указывает другое место. sudo даёт команде права администратора. Действия в браузере выполняйте на своём компьютере. Домены, IP-адреса и значения ВАШ_ПАРОЛЬ из примеров заменяйте своими до выполнения команды.
Двигайтесь по одному шагу и проверяйте результат перед следующим. Блок с <<EOF или другим именем завершения копируйте целиком: он записывает содержимое одного файла. При работе в nano сохраняйте файл клавишами Ctrl+O, Enter и выходите Ctrl+X. Если прервали SSH-сеанс, снова перейдите в указанный каталог; переменные предыдущего сеанса потребуется задать заново.
Настройка внешнего доступа использует обратный прокси Nginx и Certbot для Nginx. Приложение остаётся доступным на локальном порту; снаружи открыт его HTTPS-домен.
Шаг 1. Подготовьте каталог Keycloak #
Создадим отдельную папку. В ней будут .env и compose.yaml; все команды Compose дальше относятся к этой папке.
mkdir -p ~/services/keycloak
cd ~/services/keycloakТекущий каталог — ~/services/keycloak.
Шаг 2. Создайте два независимых пароля #
DB_PASSWORD защищает базу, BOOTSTRAP_PASSWORD предназначен временной административной записи. Генератор создаёт их один раз для новой установки.
umask 077
printf 'DB_PASSWORD=%s
BOOTSTRAP_PASSWORD=%s
' "$(openssl rand -hex 24)" "$(openssl rand -hex 24)" > .envОба значения заполнены и различаются.
Шаг 3. Запишите описание базы и Keycloak #
Откройте nano compose.yaml, вставьте YAML и замените sso.example.com своим доменом. Используется обычный start, а не режим разработки start-dev. Внутренний HTTP доступен только через 127.0.0.1:8087; снаружи будет HTTPS.
services:
db:
image: postgres:17-alpine
restart: unless-stopped
environment:
POSTGRES_DB: keycloak
POSTGRES_USER: keycloak
POSTGRES_PASSWORD: ${DB_PASSWORD:?set database password}
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U keycloak -d keycloak']
interval: 10s
timeout: 5s
retries: 10
keycloak:
image: quay.io/keycloak/keycloak:26.8.0
command: start
restart: unless-stopped
mem_limit: 2g
environment:
KC_DB: postgres
KC_DB_URL: jdbc:postgresql://db:5432/keycloak
KC_DB_USERNAME: keycloak
KC_DB_PASSWORD: ${DB_PASSWORD}
KC_HOSTNAME: https://sso.example.com
KC_HTTP_ENABLED: 'true'
KC_PROXY_HEADERS: xforwarded
KC_BOOTSTRAP_ADMIN_USERNAME: bootstrap-admin
KC_BOOTSTRAP_ADMIN_PASSWORD: ${BOOTSTRAP_PASSWORD:?set bootstrap password}
ports:
- '127.0.0.1:8087:8080'
depends_on:
db:
condition: service_healthy
volumes:
pgdata:Настроены PostgreSQL и Keycloak 26.8.0; пароли берутся из .env.
Шаг 4. Проверьте YAML и переменные #
Compose проверяет структуру файла до запуска. Отступы нельзя заменять произвольным форматированием.
docker compose config --quietconfig --quiet завершился без ошибки.
Шаг 5. Скачайте контейнеры #
Загрузим обе выбранные версии. На этом шаге приложение ещё не открывается пользователям.
docker compose pullpull завершился успешно.
Шаг 6. Запустите Keycloak #
Первый запуск создаёт базу и временного администратора. Не меняйте пароль PostgreSQL в .env после создания базы без отдельной процедуры смены.
docker compose up -dКонтейнеры созданы; дождитесь проверки состояния.
Шаг 7. Проверьте локальный ответ #
ps показывает сервисы, logs — подготовку и ошибки, curl проверяет HTTP на самом сервере.
docker compose ps
docker compose logs --tail=120 keycloak
curl -I http://127.0.0.1:8087/Keycloak не перезапускается и отвечает локально; ошибка базы требует проверить пароль и имя db.
Шаг 8. Сохраните сайт Nginx #
Установите Nginx и Certbot по подготовке Ubuntu, если ещё не установили. Откройте sudo nano /etc/nginx/sites-available/keycloak и вставьте файл ниже. Замените все домены своими. Nginx передаёт приложению домен, адрес клиента и протокол; Upgrade и Connection сохраняют WebSocket. До получения сертификата условие $scheme блокирует обычные HTTP-запросы кодом 403, чтобы вход не происходил без шифрования.
/etc/nginx/sites-available/keycloakmap $http_upgrade $keycloak_connection_upgrade {
default upgrade;
"" close;
}
server {
listen 80;
server_name sso.example.com;
client_max_body_size 100m;
location / {
if ($scheme = http) { return 403; }
proxy_pass http://127.0.0.1:8087;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $keycloak_connection_upgrade;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_buffering off;
}
}
Сохраните Ctrl+O, Enter, Ctrl+X. В файле пока нет путей к сертификатам: Nginx сможет проверить его до выпуска HTTPS.
Шаг 9. Подключите сайт и проверьте HTTP #
Ссылка подключает сохранённый сайт. nginx -t проверяет все настройки сервера; && разрешает перечитать их только при успешной проверке. curl проверяет ответ для вашего домена. При ошибке остановитесь, исправьте указанную строку и повторите проверку.
sudo ln -sfn /etc/nginx/sites-available/keycloak /etc/nginx/sites-enabled/keycloak
sudo nginx -t && sudo systemctl reload nginx
curl -I http://sso.example.com/Ожидается successful от nginx -t и HTTP 403 для обычного запроса: до HTTPS это намеренная блокировка. DNS должен указывать на сервер, TCP 80/443 — быть доступен у провайдера. Ничего не вводите в форму входа по HTTP.
Шаг 10. Получите сертификат и включите HTTPS #
Каждое имя из команды должно указывать на этот сервер. Certbot проверит домены, сам добавит сертификат в сайт Nginx и включит перенаправление HTTP → HTTPS. Укажите свою почту при запросе и подтвердите условия Let’s Encrypt. Это отдельное действие после успешной проверки HTTP.
sudo /snap/bin/certbot --nginx -d sso.example.com --redirectCertbot сообщил об успешной установке. Откройте HTTPS-адрес со своего компьютера: браузер не должен предупреждать о сертификате. Для закрытой панели используйте разрешённый IP. При ошибке исправьте DNS, в том числе AAAA, либо доступ к TCP 80; не повторяйте запросы выпуска подряд.
Шаг 11. Проверьте продление сертификата #
Certbot из snap создаёт службу автоматического продления. Dry-run выполняет пробное продление: настоящие сертификаты не заменяются. Затем проверьте, что таймер планирует следующий запуск. Сохраняйте доступ к TCP 80 для следующих проверок домена.
sudo /snap/bin/certbot renew --dry-run
systemctl list-timers --all 'snap.certbot.renew*'Пробное продление успешно, у таймера есть следующий запуск. Если тест не прошёл, проверьте /var/log/letsencrypt/letsencrypt.log; сначала исправьте причину. После этого можно создавать учётную запись и приглашать пользователей.
Шаг 12. Войдите временным администратором #
Откройте административную консоль https://sso.example.com/admin/ и войдите bootstrap-admin с BOOTSTRAP_PASSWORD из .env. Убедитесь, что браузер не перенаправляется на localhost или HTTP.
Административная консоль доступна на вашем HTTPS-домене.
Шаг 13. Создайте постоянного администратора #
В realm master создайте отдельную административную запись, выдайте необходимые права и включите MFA. Сначала проверьте вход в отдельном окне, сохранив текущую сессию.
Постоянный администратор входит и может управлять системой; коды восстановления сохранены.
Шаг 14. Удалите временный доступ #
После успешной проверки удалите bootstrap-admin. В compose.yaml уберите KC_BOOTSTRAP_ADMIN_USERNAME и KC_BOOTSTRAP_ADMIN_PASSWORD, в .env — BOOTSTRAP_PASSWORD. Пересоздайте контейнер командой ниже.
docker compose up -d keycloakПостоянный администратор входит, временная запись больше не работает.
Шаг 15. Создайте realm сотрудников #
Realm — отдельное пространство пользователей и клиентов. Создайте company; master оставьте для управления сервером. Выключите свободную регистрацию, задайте политику паролей и защиту от перебора.
В выпадающем списке выбран company, а не master.
Шаг 16. Добавьте обычного пользователя #
В realm company создайте тестовую учётную запись. Задайте временный пароль и действие смены при первом входе; при необходимости добавьте настройку OTP. SMTP задаётся в настройках realm и проверяется тестовым письмом.
Пользователь выполняет смену пароля; приглашение и восстановление доставляют письма после настройки SMTP.
Шаг 17. Проверьте адреса OpenID Connect #
Discovery-документ сообщает приложению адреса авторизации и выдачи токенов. issuer должен содержать ваш HTTPS-домен и realm company.
curl --fail https://sso.example.com/realms/company/.well-known/openid-configurationПолучен JSON; issuer и все адреса относятся к вашему серверу.
Шаг 18. Подготовьте клиент одного приложения #
Создайте OpenID Connect client по требованиям выбранного приложения. Укажите точные redirect URI и Web Origins. Серверный клиент может хранить секрет, браузерный — нет и использует подходящий публичный поток с PKCE.
Вход в тестовое приложение работает; постороннее перенаправление не разрешено. Если приложение ещё не выбрано, настройку клиента выполните позже.
Шаг 19. Остановите изменения перед копией #
Создадим закрытый каталог и остановим Keycloak. База продолжает работать для pg_dump; предупредите пользователей о перерыве во входе.
umask 077
mkdir -p "$HOME/backups/keycloak"
docker compose stop keycloakKeycloak остановлен, PostgreSQL работает.
Шаг 20. Выгрузите базу #
База содержит realm, пользователей и конфигурацию клиентов. Export realm не заменяет полную резервную копию базы.
docker compose exec -T db pg_dump -U keycloak -d keycloak -Fc > "$HOME/backups/keycloak/database.dump"database.dump создан без ошибки и не пуст.
Шаг 21. Сохраните конфигурацию установки #
Сохраним версии и пароль базы вместе с дампом. Перенесите обе части в закрытое хранилище вне этого сервера.
tar -czf "$HOME/backups/keycloak/config.tar.gz" compose.yaml .envАрхив создан; копия доступна независимо от установленного Keycloak.
Шаг 22. Возобновите вход и проверьте копию #
Запустите Keycloak и выполните вход постоянным администратором и тестовым пользователем. Восстановление проверяйте на изолированной машине той же версии с тестовыми адресами клиентов.
docker compose start keycloakОбе записи входят; проверка восстановления возвращает realm company.
Если результат шага отличается #
Вернитесь к проверке того шага, на котором появилась ошибка. Первая ошибка в выводе обычно полезнее последних строк: последующие команды могли не получить нужный файл или работающую службу. Не повторяйте установку целиком поверх частично настроенного приложения.
Если страница не открывается, сначала проверьте домен и входящие порты, затем состояние приложения и его журнал. Если сайт открывается, но отдельное действие не работает, проверьте связанные компоненты — обработчик фоновых задач, почту или права пользователя. Официальные источники в конце статьи относятся к выбранному способу установки.
Настройки внешнего доступа храните вместе с копией приложения: /etc/nginx/sites-available/keycloak и /etc/letsencrypt содержат сайт и сертификаты с закрытыми ключами. Архивируйте их с sudo в закрытое хранилище. После восстановления подключите сайт через sites-enabled, выполните sudo nginx -t, затем перечитайте Nginx. Для ошибки 502 сначала проверьте локальное приложение и /var/log/nginx/error.log; для сертификата — /var/log/letsencrypt/letsencrypt.log и таймер продления.