Как установить Keycloak на виртуальный сервер

Keycloak — открытая платформа для аутентификации и авторизации, которая поддерживает протоколы OAuth2, OpenID Connect и SAML. Сервис полностью избавляет от необходимости создавать систему логинов и паролей с нуля: обеспечивает защищённый вход, позволяет вести работу со всеми приложениями в одном аккаунте и легко интегрируется с любыми сервисами.

Keycloak можно развернуть локально или в облаке, а также упаковать его в контейнер. Вариант с установкой на собственный VDS в связке с Docker — один из самых удобных: такой подход позволяет быстро поднять рабочую систему, упрощает её обновление, а при необходимости — позволяет перенести на другой сервер без сложных настроек.

В статье пошагово разберём процесс установки Keycloak в контейнере: от подготовки виртуального сервера до настройки доступа через HTTPS и доменное имя.

Требования к серверу

Keycloak — это ресурсоёмкое приложение: оно потребляет значительный объём памяти (RAM), а также работает с внешними базами данных и HTTP-запросами, нагружая процессор (CPU).

Системные требования для установки:

• Минимальная конфигурация для тестирования — 1 vCPU, 1 ГБ RAM, 10–20 ГБ SSD. Подходит только для пробного запуска.
• Оптимальная конфигурация для продакшена — не менее 2 vCPU, 2 ГБ RAM, 40 ГБ SSD.
• Конфигурация для стабильной работы под нагрузкой — от 2 vCPU и 4 ГБ RAM, что обеспечит запас ресурсов для Java-машины, уменьшит задержки при аутентификации и повысит отказоустойчивость.

Если количество пользователей и подключенных сервисов растёт, объём оперативной памяти и число CPU нужно увеличить, чтобы избежать проблем с производительностью.

VPS/VDS от 219 ₽/мес

Готовые и индивидуальные конфигурации виртуальных серверов. Дата-центры в России и Европе

Подробнее

Инструкция по установке

1. Обновите пакеты

Подключитесь к серверу по SSH и введите команду:

sudo apt update && sudo apt upgrade -y

2. Установите Docker

Для этого нужно обновить репозитории, установить необходимое ПО и запустить контейнеры. Как это сделать, рассказали в другой нашей статье.

3. Создайте инфраструктуру

Для корректной работы сервиса потребуется минимальная инфраструктура:

• Keycloak — контейнер с самим сервером авторизации.
• PostgreSQL — внешняя база данных. У Keycloack есть встроенная база H2, но она подходит только для тестирования и стартовой настройки.
• Nginx опционально, для реверс-прокси и HTTPS.

Рассмотрим, как развернуть все зависимости внутри файла docker-compose.

3.1. Создайте начальную папку проекта

Для этого введите команду:

mkdir ~/opt  ~/opt/keycloak && cd ~/opt/keycloak

В папке нужно создать:

• .env — файл с паролями и переменными окружения;
• docker-compose.yml — описание сервисов;
• nginx.conf — файл для конфигурации реверс-прокси.

3.2. Создайте файл с переменными окружения

Вынесите секреты и пароли в отдельный файл .env: 

nano .env 

Введите код с основными переменными, которые будут использоваться в сборке:

# Версии
POSTGRES_VERSION=15
KC_VERSION=26.3

# База
POSTGRES_DB=keycloak
POSTGRES_USER=keycloak
POSTGRES_PASSWORD=supersecret

# Keycloak админ
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=admin123

# Домен
DOMAIN=keycloakkb.fvds.ru

# Let's Encrypt
LETSENCRYPT_EMAIL=admin@keycloakkb.fvds.ru

3.3. Добавьте docker-compose.yml

Создайте файл docker-compose.yml для описания запуска базы данных, Keycloak и реверс-прокси со следующим содержимым:

nano  docker-compose.yml

Введите описание запуска сервисов:

version: "3.9"

services:
  postgres:
    image: postgres:${POSTGRES_VERSION}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "${POSTGRES_USER}"]
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./postgres_data:/var/lib/postgresql/data
    networks:
      - keycloak-network

  keycloak:
    image: quay.io/keycloak/keycloak:${KC_VERSION}
    command:
      - start
      - --db=postgres
      - --hostname=${DOMAIN}
      - --proxy-headers=xforwarded
      - --health-enabled=true
      - --metrics-enabled=true
      - --http-enabled=true
    restart: unless-stopped
    environment:
      KC_DB: postgres
      KC_DB_USERNAME: ${POSTGRES_USER}
      KC_DB_PASSWORD: ${POSTGRES_PASSWORD}
      KC_DB_URL: "jdbc:postgresql://postgres:5432/${POSTGRES_DB}"
      KEYCLOAK_ADMIN: ${KEYCLOAK_ADMIN}
      KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - ./keycloak_metrics:/opt/keycloak/metrics
    networks:
      - keycloak-network

  nginx:
    image: nginx:latest
    container_name: keycloak_nginx
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./letsencrypt:/etc/letsencrypt
      - ./certbot-www:/var/www/certbot
    depends_on:
      - keycloak
    networks:
      - keycloak-network

  certbot:
    image: certbot/certbot:latest
    container_name: certbot
    volumes:
      - ./letsencrypt:/etc/letsencrypt
      - ./certbot-www:/var/www/certbot
    entrypoint: >
      sh -c "certbot certonly --webroot
      --webroot-path=/var/www/certbot
      --email ${LETSENCRYPT_EMAIL}
      --agree-tos
      --no-eff-email
      -d ${DOMAIN}"

networks:
  keycloak-network:
    driver: bridge

Для запуска Keycloak в код нужно добавить флаги:

•  start

Команда запуска Keycloak. Это стандартный entrypoint — без неё контейнер не запустит сам сервер.

•  --db=postgres

Указывает, какую базу данных использовать. В нашем случае — PostgreSQL. Keycloak поддерживает и другие БД (MySQL/MariaDB, Oracle, MSSQL), но PostgreSQL — рекомендуемая для продакшена.

•  --proxy-headers=xforwarded

Предписывает Keycloak доверять заголовкам X-Forwarded-*, которые прокидывает реверс-прокси (Nginx, Traefik и т. д.). Без этого параметра Keycloak может неправильно определить схему (http/https), IP-адрес клиента и хост.

•  --health-enabled=true

Включает endpoint здоровья (/health) для проверки состояния Keycloak. Полезно для мониторинга (Prometheus, Zabbix и др.), Kubernetes и Docker healthchecks.

•  --metrics-enabled=true

Включает метрики Prometheus (/metrics). Позволяет собирать статистику о сессиях, логинах, нагрузке, чтобы использовать данные для построения графиков и дашбордов.

•  --http-enabled=true

Включает работу Keycloak по HTTP (порт 8080). Обычно используется для работы за реверс-прокси (Nginx), который уже занимается HTTPS. Если оставить только HTTPS внутри контейнера, придётся настраивать SSL прямо в Keycloak — это менее гибкий подход.

3.4. Создайте Nginx-конфигурацию (без HTTPS)

Файл nginx.conf должен проксировать запросы к Keycloak (HTTP → контейнер): 

nano  nginx.conf

Введите базовый код для проксирования:

events {}

http {
    server {
        listen 80;
        server_name keycloakkbt.fvds.ru;

        location /.well-known/acme-challenge/ {
            root /var/www/certbot;
        }

        location / {
            proxy_pass http://keycloak:8080;
        }
    }
}

3.5. Запуск контейнеров

Запустите основные сервисы для работы, кроме cerbot, командой:

docker compose up -d --no-deps --build postgres keycloak nginx

После установки контейнеров, введите команду docker ps, чтобы увидеть запущенные контейнеры и удостовериться, что нужные работают. Ожидаемый вывод команды:

Откройте логи контейнера:

docker logs keycloak-keycloak-1

Keycloak 26.3.5 on JVM (powered by Quarkus 3.20.3) started in 25.374s означает, что сервис запустился. 

3.6. Установите SSL-сертификат с помощью cerbot

Защищённое HTTPS-соединение необходимо для корректной работы. Запустите контейнер командой:

docker compose run --rm certbot

В терминале отобразится:

Замените nginx.conf на вариант с сертификатом:

events {}

http {
    server {
        listen 80;
        server_name keycloakkb.fvds.ru;
        location /.well-known/acme-challenge/ {
            root /var/www/certbot;
        }
        location / {
            return 301 https://$host$request_uri;
        }
    }

    server {
        listen 443 ssl;
        server_name keycloakkbtest.fvds.ru;

        ssl_certificate     /etc/letsencrypt/live/keycloakkbtest.fvds.ru/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/keycloakkbtest.fvds.ru/privkey.pem;

        ssl_protocols       TLSv1.2 TLSv1.3;
        ssl_ciphers         HIGH:!aNULL:!MD5;

        location / {
            proxy_pass http://keycloak: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 https;
        }
    }
}

Перезапустите контейнеры командой:

docker compose restart

Перейдите на домен, который указали. Появится окно аутентификации в Keycloak.

Зайдите на платформу, используя данные, указанные в .env, в нашем случае — admin и admin123. 

SSL-сертификаты

SSL-сертификаты GlobalSign от 1250 руб/год.

Подробнее

4. Поменяйте пароль у главного аккаунта

По правилам безопасности пароль нужно сразу сменить. Для этого перейдите в раздел «Users»: 

Найдите административный аккаунт:

Зайдите во вкладку «Credentials» и нажмите на reset password:

Заключение

Установка Keycloak на виртуальный сервер с использованием Docker и внешней базы данных позволяет развернуть надёжную и масштабируемую систему аутентификации и авторизации. Сервис упрощает управление пользователями, поддерживает современные протоколы безопасности и легко интегрируется с внешними приложениями. А инструкция по установке поможет создать готовую инфраструктуру для использования как в небольших проектах, так и в промышленных системах.