Как установить и настроить Keycloak на VPS

MAATRIX

Когда в проекте появляется третье-четвёртое приложение, каждое со своей регистрацией и своей базой пользователей, поддерживать это становится больно: пароли расползаются, единого входа нет, а любой аудит доступа превращается в квест по десятку админок. Keycloak закрывает эту проблему целиком — это готовый identity-провайдер от Red Hat с поддержкой SAML, OAuth2 и OIDC из коробки, который можно поднять на своём VPS за час и подключить к нему все внутренние и внешние сервисы через единый вход.

Что такое Keycloak и когда он нужен

Keycloak — это сервер управления идентификацией и доступом (IAM), open source, написан на Java (Quarkus), развивается под крылом Red Hat с 2014 года. Он берёт на себя всё, что связано с аутентификацией и авторизацией: хранение пользователей, ролей и групп, единый вход (SSO), федерацию с внешними провайдерами (Google, GitHub, корпоративный LDAP/AD), двухфакторную аутентификацию, управление сессиями и токенами.

Разница с самописной авторизацией «на каждый проект своя» простая: вместо N реализаций входа и N мест с потенциальными дырами у вас один защищённый шлюз, который отдаёт приложениям OIDC-токены или SAML-ассерции. Приложение просто доверяет Keycloak и не хранит пароли пользователей вообще.

Когда Keycloak оправдан:

• у вас 3+ внутренних сервиса (админка, CRM, мониторинг, вики), и нужен один логин на всё;
• нужна интеграция с корпоративным LDAP/Active Directory;
• клиентам или партнёрам нужен вход через их SSO (SAML/OIDC) — типичное B2B-требование;
• требуется MFA, ролевая модель, аудит входов — без написания всего этого с нуля.

Если у вас один сайт с логином/паролем — Keycloak избыточен, хватит встроенной авторизации фреймворка. Но как только сервисов становится несколько, экономия времени и снижение риска окупают сложность внедрения быстро.

Для продакшена Keycloak — не игрушка: под нагрузкой JVM ест память заметно (для старта закладывайте от 2 ГБ RAM, комфортно — от 4 ГБ), а база данных (PostgreSQL) обязана быть отдельным сервисом с бэкапами, а не SQLite «на попробовать».

Требования к серверу и подготовка VPS

Минимальная конфигурация для теста — 2 vCPU, 2 ГБ RAM, 20 ГБ SSD. Для боевой эксплуатации закладывайте 4 ГБ RAM и 2-4 vCPU — Java-процесс Keycloak в среднем держит heap 512 МБ-1 ГБ, плюс PostgreSQL, плюс nginx/traefik перед ним.

Понадобится:

• VPS с Ubuntu 24.04 (или Debian 12) — оба варианта чистая установка занимает 10-15 минут, см. руководство по установке Docker с нуля — принцип для Ubuntu/Debian тот же, меняются только пакетные команды;
• доменное имя, указывающее на IP сервера (A-запись) — Keycloak в проде без валидного домена и HTTPS не разворачивают, токены OIDC требуют доверенного issuer;
• открытые порты 80 и 443 (HTTP/HTTPS), порт 8080 наружу лучше не светить вовсе.

Обновите систему и поставьте Docker с Compose-плагином:

apt update && apt upgrade -y
curl -fsSL https://get.docker.com | sh
systemctl enable --now docker
docker compose version

Если Docker уже стоит — просто проверьте версию Compose (docker compose version), нужна v2.

Установка Keycloak через Docker Compose

Официальный образ — quay.io/keycloak/keycloak, актуальные major-версии в 2026 году — 26.x. Разворачиваем связку Keycloak + PostgreSQL двумя контейнерами.

Создайте рабочую директорию и файл окружения:

mkdir -p /opt/keycloak && cd /opt/keycloak

.env:

KC_DB_PASSWORD=замените-на-длинный-случайный-пароль
KC_ADMIN_PASSWORD=замените-на-другой-случайный-пароль
KC_HOSTNAME=auth.example.com

docker-compose.yml:

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: ${KC_DB_PASSWORD}
    volumes:
      - kc_pgdata:/var/lib/postgresql/data
    networks:
      - kc_net

  keycloak:
    image: quay.io/keycloak/keycloak:26.0
    restart: unless-stopped
    command: start --optimized
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: ${KC_DB_PASSWORD}
      KC_HOSTNAME: ${KC_HOSTNAME}
      KC_HOSTNAME_STRICT: "true"
      KC_PROXY_HEADERS: xforwarded
      KC_HTTP_ENABLED: "true"
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: ${KC_ADMIN_PASSWORD}
    depends_on:
      - postgres
    ports:
      - "127.0.0.1:8080:8080"
    networks:
      - kc_net

networks:
  kc_net:

volumes:
  kc_pgdata:

Обратите внимание на KC_PROXY_HEADERS: xforwarded — эта опция говорит Keycloak доверять заголовкам X-Forwarded-* от reverse-proxy, без неё редиректы после логина будут ломаться на http:// вместо https://. Порт 8080 намеренно забинден только на 127.0.0.1 — наружу сервис отдаёт nginx или traefik, напрямую Keycloak в интернет смотреть не должен.

Запуск:

docker compose up -d
docker compose logs -f keycloak

Первый старт занимает 20-40 секунд — Keycloak прогревает JVM и накатывает миграции схемы БД. В логах ищите строку Keycloak … started.

HTTPS через reverse-proxy: nginx или Caddy

Голый HTTP для identity-провайдера в проде недопустим — по протоколу токены и куки должны идти по TLS, иначе OIDC-клиенты будут ругаться, а браузеры — блокировать secure-cookie. Проще всего поднять терминацию SSL перед Keycloak через nginx с Certbot или через Caddy с автоматическим Let's Encrypt.

Если у вас уже стоит Caddy с авто-SSL — конфиг сводится к трём строкам:

auth.example.com {
    reverse_proxy 127.0.0.1:8080
}

Certbot и Caddy решают одну задачу по-разному — если сомневаетесь, что выбрать, сравнение вариантов есть в статье «Caddy или nginx — что выбрать для сервера».

Вариант с nginx (если он уже используется под другие сайты на этом VPS):

server {
    listen 80;
    server_name auth.example.com;
    location /.well-known/acme-challenge/ { root /var/www/certbot; }
    location / { return 301 https://$host$request_uri; }
}

server {
    listen 443 ssl http2;
    server_name auth.example.com;

    ssl_certificate     /etc/letsencrypt/live/auth.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/auth.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1: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 $scheme;
        proxy_buffer_size 128k;
        proxy_buffers 4 256k;
        proxy_busy_buffers_size 256k;
    }
}

Сертификат получите стандартно через certbot --nginx -d auth.example.com. Увеличенные proxy_buffer_size не опциональны — Keycloak отдаёт крупные заголовки с JWT в SAML/OIDC-ответах, на дефолтных буферах nginx nginx может обрезать ответ с ошибкой 502.

После этого домен https://auth.example.com должен открывать страницу входа в админ-консоль Keycloak.

Первый вход и настройка realm

Зайдите на https://auth.example.com → «Administration Console», логин admin и пароль из KC_ADMIN_PASSWORD. Сразу после первого входа Keycloak предложит сменить пароль администратора — сделайте это, дефолтный админ-аккаунт живёт в системном realm master и его компрометация — это компрометация всего.

Дальше — базовая гигиена:

1. Не используйте master realm для рабочих приложений. Создайте отдельный realm (кнопка в левом верхнем углу → «Create realm»), например company.
2. В настройках нового realm включите политику паролей (Realm settings → Policies) — минимум 8-12 символов, требование цифр и спецсимволов.
3. Настройте SMTP (Realm settings → Email) — без него не будут работать письма подтверждения и сброс пароля.
4. Включите Brute Force Detection (Realm settings → Security defenses) — блокировка после N неудачных попыток входа.

Realm — это изолированное пространство пользователей, ролей и клиентов. Обычно один realm = одна организация или один продукт; смешивать несколько проектов в одном realm не стоит, если у них разные требования к политикам безопасности.

Настройка клиента (OIDC) и подключение приложения

Каждое приложение, которое хочет использовать Keycloak для входа, регистрируется как «клиент» (Client). В консоли realm: Clients → Create client.

• Client ID: myapp (используется в конфиге вашего приложения).
• Client type: OpenID Connect.
• Client authentication: On (confidential client — если приложение бэкендовое и может хранить secret) или Off (public client — для SPA/мобильных, где secret хранить негде, используется PKCE).
• Valid redirect URIs: https://myapp.example.com/* — куда Keycloak отправит браузер после успешного логина.
• Web origins: https://myapp.example.com — для CORS.

После сохранения на вкладке Credentials появится Client secret (для confidential-клиентов) — он нужен приложению, чтобы обменивать authorization code на токены.

Стандартный OIDC-флоу выглядит так: приложение редиректит пользователя на /realms/company/protocol/openid-connect/auth, после логина Keycloak возвращает браузер обратно с code, приложение обменивает его на access_token/id_token/refresh_token через эндпоинт /realms/company/protocol/openid-connect/token.

Практически все современные бэкенд-фреймворки (Node/Express через openid-client, Python/Django через mozilla-django-oidc, Spring Security, Laravel Socialite и т.д.) умеют работать с любым OIDC-провайдером «из коробки» — конфигурация сводится к указанию discovery-URL:

https://auth.example.com/realms/company/.well-known/openid-configuration

Этот эндпоинт отдаёт JSON со всеми нужными адресами (authorization, token, userinfo, jwks) — большинство SDK настраиваются одной этой ссылкой, без ручного указания каждого пути.

Для SAML-интеграций (легаси-корпоративный софт, некоторые SaaS) в том же разделе Clients есть тип «SAML» — процесс аналогичный, но обмен идёт XML-ассерциями, а не JWT.

Резервное копирование и обслуживание

Вся ценность инсталляции — в базе PostgreSQL: пользователи, роли, настройки realm'ов, история сессий. Контейнер Keycloak сам по себе stateless, его можно пересоздать в любой момент, а вот потеря БД — это потеря всех аккаунтов.

Простой дамп по cron:

#!/bin/bash
docker exec -t $(docker compose -f /opt/keycloak/docker-compose.yml ps -q postgres) \
  pg_dump -U keycloak keycloak | gzip > /opt/backups/keycloak-$(date +%F).sql.gz
find /opt/backups -name "keycloak-*.sql.gz" -mtime +14 -delete

Добавьте в crontab -e:

0 3 * * * /opt/keycloak/backup.sh

Восстановление из дампа:

gunzip -c keycloak-2026-08-20.sql.gz | docker exec -i <postgres-container> psql -U keycloak keycloak

Обновление версии — меняете тег образа в docker-compose.yml и делаете docker compose pull && docker compose up -d. Перед обновлением на мажорную версию сверьтесь с release notes проекта — между мажорами иногда меняется формат конфигурации, и без свежего бэкапа БД экспериментировать не стоит.

Если сервер, где крутится Keycloak, не защищён базовым файрволом — начните с этого до того, как открывать сервис в интернет; порядок настройки описан в статье «Как установить и настроить UFW на VPS».

Частые вопросы