Как развернуть и настроить Keycloak: пошаговая инструкция

Если у вас есть веб-приложение и вы не хотите писать собственную авторизацию с нуля — скорее всего, вам пригодится Keycloak. Это готовая система управления пользователями, которая умеет всё: логины, роли, токены, соцсети, и даже SSO «из коробки». 

В статье рассмотрим, как развернуть Keycloak на сервере Timeweb Cloud и настроить авторизацию для своих приложений. 

vds

Что такое 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

Разворачивать Keycloak можно где угодно — от домашнего сервера до Kubernetes. Но если нужен быстрый старт без лишних сложностей, подойдет обычный VPS. Посмотрим, как установить Keycloak в Timeweb Cloud — удобно, быстро и недорого.

Что понадобится:

• Аккаунт в Timeweb Cloud (если нет, зарегистрируйте новый аккаунт)
• Облачный сервер (VPS) на Ubuntu 22.04
• Установленный Docker и Docker Compose (покажем ниже)

Шаг 1. Создайте сервер в Timeweb Cloud

1. Зайдите в панель управления → «Облачные серверы».
2. Нажмите «Создать».
3. Выберите образ Ubuntu 22.04.
4. Установите параметры (CPU, RAM, диск) — для теста хватит минимальной конфигурации.
5. Запустите сервер и подключитесь к нему по SSH.

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

Это можно сделать в две команды:

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

Дождитесь завершения выполнения команд. 

Чтобы Dockerhub, откуда скачиваются образы приложений, не блокировал ваш трафик, используйте прокси от Timeweb Cloud. Подробнее об этом пишем на странице по ссылке, а поставить его на сервер можно одной командой:

touch /etc/docker/daemon.json && echo "{ \"registry-mirrors\" : [ \"https://dockerhub.timeweb.cloud\" ] }" > $_ && 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

Используйте команду:

docker compose up -d

Через минуту Keycloak будет доступен по адресу:

http://<ваш_IP>:8080

Шаг 5. Отключите требование HTTPS (только для теста)

По умолчанию Keycloak требует HTTPS даже в dev-режиме, из-за чего при открытии может появиться сообщение HTTPS required.

Чтобы отключить это поведение только в тестовой среде, выполните в контейнере Keycloak следующие команды:

docker exec -it keycloak-keycloak-1 /opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password admin
docker exec -it keycloak-keycloak-1 /opt/keycloak/bin/kcadm.sh update realms/master -s sslRequired=NONE

После этого можно обновить страницу — сообщение об HTTPS исчезнет. Теперь можно авторизоваться в панель с логином и пароль admin.

Базовая настройка Keycloak

После успешного запуска контейнера с Keycloak вы получите административную панель по адресу http://<ваш-сервер>:8080/admin. Именно здесь происходит вся настройка: от создания realm'ов до подключения клиентов, ролей и пользователей.

Реалмы

В Keycloak всё начинается с реалма — это как отдельный «мир» с собственной базой пользователей, настройками безопасности и приложениями.

Представьте, что вы делаете платформу с двумя проектами: внутренний портал для сотрудников и сайт для клиентов. У каждого — свои пользователи, свои роли, свои настройки входа. Чтобы не хранить всё вместе, вы создаете два реалма: staff и clients. Они полностью изолированы друг от друга: логины, правила, страницы входа, даже политики паролей можно настроить по-разному.

Реалм — это способ держать порядок в системе и не путать пользователей из разных приложений.

Создадим свой реалм. Для этого перейдите на вкладку «Manage realms» (1) в панели администратора и нажмите кнопку «Create realm» (2).

Навигация к созданию реалма в Keycloak: вкладка «Manage realms» и кнопка «Create realm»

Далее введите имя реалма и нажмите кнопку «Create».

Форма создания реалма: ввод имени и подтверждение нажатием «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). 

Переход к разделу ролей: вкладка «Realm roles» и кнопка «Create role» для создания новой роли

Введите название роли и нажмите кнопку «Save».

Создание роли

Теперь попробуем создать пользователя. Перейдите на вкладку «Users» и нажмите кнопку «Add user». Обязательно введите имя пользователя, и по желанию — электронную почту, имя и фамилию пользователя. Нажмите «Create».

Создание пользователя: укажите параметры и сохраните через кнопку «Create»

Назначьте новому пользователю пароль для входа. Для этого на открывшейся странице перейдите на вкладку «Credentials» (1), нажмите на кнопку «Set password» (2), установите пароль и повторите его. Оставьте параметр «Temporary» активным, чтобы новый пользователь сменил свой пароль после первой авторизации в систему. 

Назначение данных для входа: откройте вкладку «Credentials» и введите пароль нового пользователя

Теперь назначьте новому пользователю роль — в том же разделе вкладку «Role mapping» (1), нажмите на кнопку «Assign role» (2) → «Realm roles» (3).

Назначение роли: откройте вкладку «Role mapping» и выберите нужную роль через «Assign role» → «Realm roles»

Выберите роль и нажмите «Assign».

Выбор роли из списка и подтверждение назначения кнопкой «Assign»

Теперь роль назначена пользователю.

Клиенты

Клиенты в Keycloak — это приложения, которые подключаются к системе авторизации. Через них пользователь входит в сервис, а Keycloak проверяет его личность и права. Без клиента система не поймет, откуда пришел пользователь, куда его возвращать после входа и какие разрешения ему можно выдать.

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

Важно: один и тот же пользователь может входить в разные клиенты. Например, в клиент «frontend» он заходит как обычный пользователь, а в клиент «admin-panel» — как модератор. Это удобно, когда у приложения несколько интерфейсов с разными уровнями доступа.

Именно с клиента начинается авторизация. Приложение перенаправляет пользователя в Keycloak, тот проверяет его данные и возвращает обратно уже с токеном. А приложение использует этот токен, чтобы узнать, кто перед ним и что ему можно.

Создайте тестового клиента. Перейдите на вкладку «Clients» и нажмите на кнопку «Create client». Введите название клиента в поле «Client ID». На шаге «Login settings» в пункте «Valid redirect URIs» введите корректные пути, куда пользователь может быть переадресован после авторизации. Для тестирования можно оставить звездочку — «*». Остальные значения можно оставить по умолчанию. 

Экран после создания клиента в Keycloak

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

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/timeweb-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-адрес или домен своего сервера, вместо указанного там адреса и исправьте реалм на тот, который вы создали самостоятельно.

nano .env

Пример настройки переменных окружения для подключения к Keycloak

Запустите приложение командой:

node index.js

Перейдите на страницу: http://<IP-сервера>:3000/.

Появится страница авторизации. Нажмите на зеленую кнопку.

Тестовая страница авторизации с кнопкой входа через Keycloak

Авторизация может быть выполнена автоматически, так как на этом сервере вы уже проходили авторизацию в аккаунт администратора. Если этого не произошло, введите тестовые логин и пароль. Если всё успешно, вы увидите страницу: 

Успешная авторизация: страница с приветствием и отображением Access Token, полученного от Keycloak

Чтобы интегрировать решение в свой проект или понять, как всё работает изнутри, посмотрите исходный код проекта на GitHub.

Интеграция с внешними сервисами

Keycloak можно использовать не только для собственных проектов, но и для входа в сторонние сервисы — например, GitLab, Jenkins, Grafana. Это особенно удобно, если вы хотите реализовать единый вход (SSO) для команды. Документацию по интеграции любого сервиса к Keycloak можно найти в свободном доступе. 

Для примера рассмотрим настройку авторизации через Keycloak для GitLab. Для этого потребуется docker-compose и базовая настройка в панели управления.

Обратите внимание, что в этом случае внешние сервисы требуют обязательное наличие SSL-сертификата, чтобы Keycloak мог обеспечивать безопасный вход. Для этого потребуется собственный домен — его можно купить в панели Timeweb Cloud. Здесь будет удобно создать два дополнительных поддомена — для GitLab и Keycloak соответственно. 

Если GitLab уже установлен, можно добавить настройки вручную. Но проще — сразу развернуть всё вместе. Ниже пример docker-compose.yml, который поднимает Keycloak и GitLab, уже настроенные для работы друг с другом. Не забудьте поставить ваш домен вместо example.ru.

version: "3.9"

services:
  traefik:
    image: traefik:v3.1
    container_name: traefik
    command:
      - "--api.dashboard=true"
      - "--providers.docker=true"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.letsencrypt.acme.email=admin@example.ru"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "./letsencrypt:/letsencrypt"
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
    restart: unless-stopped
    networks:
      - app-network

  gitlab:
    image: gitlab/gitlab-ce:latest
    container_name: gitlab
    hostname: gitlab.example.ru
    volumes:
      - gitlab-config:/etc/gitlab
      - gitlab-logs:/var/log/gitlab
      - gitlab-data:/var/opt/gitlab
    restart: unless-stopped
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.example.ru'
        nginx['listen_https'] = false
        nginx['listen_port'] = 80
        gitlab_rails['omniauth_enabled'] = true
        gitlab_rails['omniauth_allow_single_sign_on'] = ['openid_connect']
        gitlab_rails['omniauth_auto_link_user'] = ['openid_connect']
        gitlab_rails['omniauth_block_auto_created_users'] = false
        gitlab_rails['omniauth_providers'] = [
          {
            name: "openid_connect",
            label: "Keycloak",
            args: {
              name: "openid_connect",
              scope: ["openid", "profile", "email"],
              response_type: "code",
              issuer: "https://keycloak.example.ru/realms/master",
              discovery: true,
              client_auth_method: "query",
              uid_field: "preferred_username",
              client_options: {
                identifier: "gitlab",
                secret: "secret",
                redirect_uri: "https://gitlab.example.ru/users/auth/openid_connect/callback"
              }
            }
          }
        ]
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.gitlab.rule=Host(`gitlab.example.ru`)"
      - "traefik.http.routers.gitlab.entrypoints=websecure"
      - "traefik.http.routers.gitlab.tls.certresolver=letsencrypt"
      - "traefik.http.services.gitlab.loadbalancer.server.port=80"
    networks:
      - app-network

  keycloak:
    image: quay.io/keycloak/keycloak:26.3.2
    container_name: keycloak
    command: start-dev
    environment:
      KC_HOSTNAME: https://keycloak.example.ru
      KC_HOSTNAME_STRICT: false
      KC_HOSTNAME_HTTPS: true
      KC_PROXY: edge
      KC_HTTP_ENABLED: true
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.keycloak.rule=Host(`keycloak.example.ru`)"
      - "traefik.http.routers.keycloak.entrypoints=websecure"
      - "traefik.http.routers.keycloak.tls.certresolver=letsencrypt"
      - "traefik.http.services.keycloak.loadbalancer.server.port=8080"
    networks:
      - app-network

volumes:
  gitlab-config:
  gitlab-logs:
  gitlab-data:

networks:
  app-network:
    driver: bridge

В проекте используется Traefik в качестве реверс-прокси. Он автоматически выпустит бесплатные SSL-сертификаты Let`s Encrypt для поддоменов.

Запустите проект:

docker compose up -d

В административной панели 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:

Экран входа в GitLab с доступной опцией авторизации через Keycloak

После успешной авторизации через Keycloak откроется панель редактирования нового пользователя, который был создан после авторизации.

Окно настроек нового пользователя GitLab после авторизации через Keycloak

Частые проблемы и их решения

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

Заключение

Если вы создаете веб-приложение и хотите быстро запустить авторизацию, Keycloak становится отличным решением. Он избавляет от рутины: логины, роли, сессии, соцсети, права доступа — всё есть сразу.

Мы разобрали, как развернуть Keycloak на сервере, настроить базовую панель, подключить React и Express-приложения, а также интегрировать сторонний сервис вроде GitLab. Это универсальный подход: однажды настроив Keycloak, вы сможете добавлять к нему новые сервисы за считанные минуты — и управлять доступом из единой панели.

Такой подход экономит время, упрощает сопровождение, снижает риски и делает систему безопаснее. А главное — вы больше не тратите силы на изобретение собственной авторизации.