Материал подготовлен командой Simple-Server для администраторов VPS и выделенных серверов. Команды и пути проверяйте на тестовой машине перед production.
Что такое Keycloak и зачем он нужен
Keycloak — это сервис, который берет на себя всю работу с авторизацией и аутентификацией. Вместо того чтобы выстраивать свою систему логинов, паролей, подтверждений почты, ролей и токенов, вы просто подключаете Keycloak — и получаете всё необходимое.
Keycloak функционирует как самостоятельный сервис: у него есть панель управления, REST API, интеграция с внешними системами и клиенты для популярных языков и фреймворков. По сути, Keycloak становится центральным хабом авторизации в проекте: пользователи авторизуются через него, получают токены, а далее попадают в ваши приложения.
Ключевые сценарии, где Keycloak раскрывает себя лучше всего:
- Single Sign-On (SSO) — один вход для всех ваших сервисов.
- OAuth2 и OpenID Connect — готовая реализация стандартов.
- Роли и группы — определяют, какие действия доступны пользователю.
- Соцлогины — вход через Google, GitHub, VK и т.д.
- Управление пользователями — создание, бан, сброс пароля, подтверждение email.
- Интеграция с любыми фронтами и бэками — Java, Python, Node.js, React, Angular.
Keycloak помогает не только быстро запустить вход через логин и пароль, но и масштабировать доступ: от одного лендинга до десятков микросервисов с разными правами.
Разворачивать Keycloak можно где угодно — от домашнего сервера до Kubernetes. Но если нужен быстрый старт без лишних сложностей, подойдет обычный VPS. Посмотрим, как установить Keycloak в Simple-Server — удобно, быстро и недорого.
- Аккаунт в Simple-Server (если нет, зарегистрируйте новый аккаунт)
- Облачный сервер (VPS) на Ubuntu 22.04
- Установленный Docker и Docker Compose (покажем ниже)
Шаг 1. Создайте сервер в Simple-Server
- Зайдите в панель управления → «Облачные серверы».
- Нажмите «Создать».
- Выберите образ Ubuntu 22.04.
- Установите параметры (CPU, RAM, диск) — для теста хватит минимальной конфигурации.
- Запустите сервер и подключитесь к нему по SSH.
Шаг 2. Установите Docker и Docker Compose
Это можно сделать в две команды:
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.shДождитесь завершения выполнения команд.
Чтобы Dockerhub, откуда скачиваются образы приложений, не блокировал ваш трафик, используйте прокси от Simple-Server. Подробнее об этом пишем на странице по ссылке, а поставить его на сервер можно одной командой:
touch /etc/docker/daemon.json && echo "{ \"registry-mirrors\" : [ \"https://docker.io\" ] }" > $_ && systemctl reload dockerШаг 3. Создайте Docker Compose файл
Создайте папку для проекта и файл с конфигурацией:
mkdir keycloak && cd keycloak
nano docker-compose.ymlВставьте в него следующее содержимое:
services:
keycloak:
image: quay.io/keycloak/keycloak:26.3.2
command: start-dev
environment:
- KEYCLOAK_ADMIN=admin
- KEYCLOAK_ADMIN_PASSWORD=admin
ports:
- "8080:8080"
restart: alwaysСохраните комбинацией клавиш Ctrl+O, далее Enter для подтверждения. Закройте редактор комбинацией Ctrl+X.
Шаг 4. Запустите Keycloak
Через минуту Keycloak будет доступен по адресу:
Шаг 5. Отключите требование HTTPS (только для теста)
По умолчанию Keycloak требует HTTPS даже в dev-режиме, из-за чего при открытии может появиться сообщение HTTPS required.
Чтобы отключить это поведение только в тестовой среде, выполните в контейнере Keycloak следующие команды:
После этого можно обновить страницу — сообщение об HTTPS исчезнет. Теперь можно авторизоваться в панель с логином и пароль admin.
Базовая настройка Keycloak
После успешного запуска контейнера с Keycloak вы получите административную панель по адресу http://<ваш-сервер>:8080/admin. Именно здесь происходит вся настройка: от создания realm'ов до подключения клиентов, ролей и пользователей.
В Keycloak всё начинается с реалма — это как отдельный «мир» с собственной базой пользователей, настройками безопасности и приложениями.
Представьте, что вы делаете платформу с двумя проектами: внутренний портал для сотрудников и сайт для клиентов. У каждого — свои пользователи, свои роли, свои настройки входа. Чтобы не хранить всё вместе, вы создаете два реалма: staff и clients. Они полностью изолированы друг от друга: логины, правила, страницы входа, даже политики паролей можно настроить по-разному.
Реалм — это способ держать порядок в системе и не путать пользователей из разных приложений.
Создадим свой реалм. Для этого перейдите на вкладку «Manage realms» (1) в панели администратора и нажмите кнопку «Create realm» (2).
Далее введите имя реалма и нажмите кнопку «Create».
Вернитесь на вкладку «Manage realms» и нажмите на новый реалм — теперь он выбран по умолчанию.
Если вы тестируете Keycloak, отключите требование SSL-сертификата для нового реалма — в тестовом окружении он необязателен. Используйте:
docker exec -it keycloak-keycloak-1 /opt/keycloak/bin/kcadm.sh update realms/<ИМЯ_НОВОГО_РЕАЛМА> -s sslRequired=NONEПользователи — это люди или сервисы, которые будут заходить в ваши приложения через Keycloak. У каждого — свой логин, пароль и набор разрешений.
Пользователи без назначенных ролей не получают доступ ни к каким функциям. Чтобы понять, что им можно, а что нельзя, им назначают роли.
Роли — это ярлыки вроде «admin», «manager», «viewer». Они не делают ничего сами по себе, но дают понять приложению: «этот человек — админ, ему можно удалять, а тому — только смотреть».
Создайте свою роль. Для этого перейдите на вкладку «Realm roles» (1) и нажмите на кнопку «Create role» (2).
Введите название роли и нажмите кнопку «Save».
Теперь попробуем создать пользователя. Перейдите на вкладку «Users» и нажмите кнопку «Add user». Обязательно введите имя пользователя, и по желанию — электронную почту, имя и фамилию пользователя. Нажмите «Create».
Назначьте новому пользователю пароль для входа. Для этого на открывшейся странице перейдите на вкладку «Credentials» (1), нажмите на кнопку «Set password» (2), установите пароль и повторите его. Оставьте параметр «Temporary» активным, чтобы новый пользователь сменил свой пароль после первой авторизации в систему.
Теперь назначьте новому пользователю роль — в том же разделе вкладку «Role mapping» (1), нажмите на кнопку «Assign role» (2) → «Realm roles» (3).
Выберите роль и нажмите «Assign».
Теперь роль назначена пользователю.
Клиенты в Keycloak — это приложения, которые подключаются к системе авторизации. Через них пользователь входит в сервис, а Keycloak проверяет его личность и права. Без клиента система не поймет, откуда пришел пользователь, куда его возвращать после входа и какие разрешения ему можно выдать.
В каждом клиенте можно настроить способ входа: по логину и паролю, через соцсети, с двухфакторной авторизацией или токенами. Можно разрешить или запретить определенные роли. Можно указать, куда редиректить пользователя после успешного входа, а куда — после выхода.
Важно: один и тот же пользователь может входить в разные клиенты. Например, в клиент «frontend» он заходит как обычный пользователь, а в клиент «admin-panel» — как модератор. Это удобно, когда у приложения несколько интерфейсов с разными уровнями доступа.
Именно с клиента начинается авторизация. Приложение перенаправляет пользователя в Keycloak, тот проверяет его данные и возвращает обратно уже с токеном. А приложение использует этот токен, чтобы узнать, кто перед ним и что ему можно.
Создайте тестового клиента. Перейдите на вкладку «Clients» и нажмите на кнопку «Create client». Введите название клиента в поле «Client ID». На шаге «Login settings» в пункте «Valid redirect URIs» введите корректные пути, куда пользователь может быть переадресован после авторизации. Для тестирования можно оставить звездочку — «*». Остальные значения можно оставить по умолчанию.
Настройка авторизации для приложений
Keycloak можно подключить почти к любому приложению: фронтенду на React, бэкенду на Flask, нативному десктопу, мобильному приложению. Сам Keycloak реализует стандартные протоколы — OAuth 2.0 и OpenID Connect, а это значит, что приложение не зависит от платформы: если оно поддерживает авторизацию по стандарту, оно сможет работать с Keycloak.
Процесс подключения всегда примерно одинаковый. Приложение перенаправляет пользователя в Keycloak. Тот запрашивает логин и пароль, возвращает обратно код. Приложение обменивает код на токен и начинает с ним работать. С этого момента пользователь считается авторизованным — можно проверять его права, роли и доступы.
На стороне Keycloak приложение оформляется как клиент, для которого в интерфейсе задаются сценарии авторизации и ограничения доступа.Все эти настройки зависят от типа приложения и его возможностей. Например, если пользователь пишет обычный сайт, достаточно будет стандартного flow. А если хочешь авторизовать IoT-устройство — скорее всего, придется использовать client credentials flow без участия пользователя.
Для теста начните с базовой веб-авторизации по логину и паролю — это самый быстрый способ проверить интеграцию. Мы приготовили пример авторизации Keycloak для приложений, с использованием связки express + React.js. Посмотрим, как он работает.
Сперва склонируйте репозиторий и установите зависимости:
git clone https://github.com/Simple-Server-cloud-tutorials/test-keycloak-react.git
cd test-keycloak-react/server && npm installЕсли установка зависимостей npm завершается ошибкой, проверьте, что на сервер установлен Node.js и npm. Установите через команду:
sudo apt update && sudo apt install nodejs npm -yПодробнее об этом пишем в другой инструкции.
Перейдите в файл переменных окружения .env, введите IP-адрес или домен своего сервера, вместо указанного там адреса и исправьте реалм на тот, который вы создали самостоятельно.
Запустите приложение командой:
Перейдите на страницу: http://<IP-сервера>:3000/.
Появится страница авторизации. Нажмите на зеленую кнопку.
Авторизация может быть выполнена автоматически, так как на этом сервере вы уже проходили авторизацию в аккаунт администратора. Если этого не произошло, введите тестовые логин и пароль. Если всё успешно, вы увидите страницу:
Чтобы интегрировать решение в свой проект или понять, как всё работает изнутри, посмотрите исходный код проекта на GitHub.
Интеграция с внешними сервисами
Keycloak можно использовать не только для собственных проектов, но и для входа в сторонние сервисы — например, GitLab, Jenkins, Grafana. Это особенно удобно, если вы хотите реализовать единый вход (SSO) для команды. Документацию по интеграции любого сервиса к Keycloak можно найти в свободном доступе.
Для примера рассмотрим настройку авторизации через Keycloak для GitLab. Для этого потребуется docker-compose и базовая настройка в панели управления.
Обратите внимание, что в этом случае внешние сервисы требуют обязательное наличие SSL-сертификата, чтобы Keycloak мог обеспечивать безопасный вход. Для этого потребуется собственный домен — его можно купить в панели Simple-Server. Здесь будет удобно создать два дополнительных поддомена — для GitLab и Keycloak соответственно.
Если GitLab уже установлен, можно добавить настройки вручную. Но проще — сразу развернуть всё вместе. Ниже пример docker-compose.yml, который поднимает Keycloak и GitLab, уже настроенные для работы друг с другом. Не забудьте поставить ваш домен вместо example.ru.
В проекте используется Traefik в качестве реверс-прокси. Он автоматически выпустит бесплатные SSL-сертификаты Let`s Encrypt для поддоменов.
В административной панели Keycloak создайте клиента gitlab, у которого укажите:
- Root URL — домен GitLab с протоколом
https. Например,https://gitlab.example.ru. - Valid redirect URIs — домен GitLab с протоколом
httpsи все возможные пути по этому домену. Например,https://gitlab.example.ru/*.
Реалм по умолчанию — master. При желании можно завести отдельный realm. Пользователи для GitLab и других сервисов создаются вручную через админку Keycloak.
После загрузки GitLab перейдите на страницу авторизации по домену, принадлежащему GitLab. Сервис предложит авторизоваться через Keycloak:
После успешной авторизации через Keycloak откроется панель редактирования нового пользователя, который был создан после авторизации.
Частые проблемы и их решения
Иногда при развертывании и настройке Keycloak возникают ошибки — как в самой панели, так и при интеграции с другими сервисами. Ниже собрали типовые симптомы, причины и решения, чтобы вы могли быстро устранить проблему и продолжить настройку.
"HTTPS required" в браузере или логах
Keycloak требует HTTPS даже в dev-режиме
Отключите требование SSL:
docker exec -it keycloak-keycloak-1 bash
./kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password admin
Keycloak UI бесконечно грузится
Ошибка из-за неправильного KC_HOSTNAME или CORS
Убедитесь, что переменная KC_HOSTNAME не установлена или соответствует адресу, по которому открываете Keycloak
Keycloak не сохраняет сессии/настройки
Запущен без volume, state не сохраняется
Пропишите volume в docker-compose.yml:
Ошибка Web Crypto API is not available
React-приложение запущено в окружении без HTTPS или в старом браузере
Запускайте через HTTPS или в современном браузере. На dev-сервере используйте localhost
A 'Keycloak' instance can only be initialized once
Множественная инициализация Keycloak в React
Проверьте, что инициализация происходит один раз, например, в отдельном keycloak.js, а не в каждом компоненте
Ssl connect returned=1 errno=0 ... в GitLab
GitLab требует HTTPS, а Keycloak работает по HTTP
Временно отключите SSL-требование в Keycloak (только для dev) или настройте HTTPS с self-signed или Let’s Encrypt сертификатом
После логина пользователь не создаётся в GitLab
В GitLab отключено автоматическое создание пользователей
Убедитесь, что параметры заданы:
Кнопка входа через Keycloak не появляется
Ошибка в omniauth_providers или issuer
Проверьте client_id, issuer, redirect_uri в конфигурации GitLab — должны строго соответствовать клиенту в Keycloak
Старый docker-compose-файл или не та версия образа
Убедитесь, что используете актуальный образ (например, quay.io/keycloak/keycloak:26.3.2) и команду запуска start-dev
Если вы создаете веб-приложение и хотите быстро запустить авторизацию, Keycloak становится отличным решением. Он избавляет от рутины: логины, роли, сессии, соцсети, права доступа — всё есть сразу.
Мы разобрали, как развернуть Keycloak на сервере, настроить базовую панель, подключить React и Express-приложения, а также интегрировать сторонний сервис вроде GitLab. Это универсальный подход: однажды настроив Keycloak, вы сможете добавлять к нему новые сервисы за считанные минуты — и управлять доступом из единой панели.
Такой подход экономит время, упрощает сопровождение, снижает риски и делает систему безопаснее. А главное — вы больше не тратите силы на изобретение собственной авторизации.
Нужен сервер для практики? Арендуйте VPS/VDS в России — root-доступ, NVMe, DDoS-защита и поддержка 24/7.