Keycloak: аутентификация и управление доступом — от realm до защиты API

Знакомая сцена. Новый проект, и вы снова пишете вход. Форму логина, регистрацию, хеширование паролей, подтверждение почты, сброс пароля, «запомнить меня», обновление сессии. Потом защиту от перебора паролей. Потом двухфакторку, потому что так требует заказчик. На всё это уходит первая неделя — каждый раз заново, в каждом проекте.

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

Keycloak снимает эту задачу целиком. Это готовый сервер аутентификации: вход, регистрация, сброс пароля, двухфакторка, вход через Google и GitHub, единый вход в несколько приложений — всё уже написано и проверено. Вы не пишете логин вообще. Ваше приложение перенаправляет пользователя на Keycloak, тот проверяет его и возвращает токен. Дальше приложение работает с токеном, а паролей не видит никогда.

Разберём по шагам: ключевые понятия, как устроен вход через OAuth2, что лежит внутри токена, как поднять Keycloak и как защитить им свой REST API.

Keycloak строится на стандартах OAuth2 и OpenID Connect — их разбирают в курсе «JWT и OAuth» и программах по бэкенду на Хекслете.

Что такое Keycloak и что он снимает с разработчика

Keycloak — сервер управления учётными записями и доступом. Его называют IAM-системой: Identity and Access Management. Работа Keycloak — знать, кто такой пользователь (аутентификация) и что ему разрешено (авторизация). Всё остальное приложение получает в готовом виде.

Главная идея: приложение больше не отвечает за вход. Когда пользователю нужно войти, приложение отправляет его на Keycloak. Тот показывает свою форму входа, проверяет логин и пароль (или код из приложения-аутентификатора, или вход через соцсеть) и возвращает токен — подписанное удостоверение, что пользователь тот, за кого себя выдаёт. Приложение этому удостоверению доверяет, потому что может проверить подпись.

Keycloak — продукт с открытым кодом, его развивает сообщество вокруг Red Hat. Ставится своим сервером, данные остаются у вас — это важно там, где нельзя отдавать учётные записи во внешний сервис. Альтернативы есть: облачные Auth0, Okta, российский вход через подобные сервисы. Keycloak выбирают, когда нужен контроль над данными и нет желания платить за каждого активного пользователя.

Четыре понятия, без которых не разобраться

В Keycloak своя терминология. Освоить нужно всего четыре слова — на них держится вся настройка.

Связь простая. Внутри realm живут пользователи, приложения-клиенты и роли. Пользователю назначают роли. Когда он входит через какой-то client, Keycloak кладёт его роли прямо в токен — и приложению не нужно отдельно спрашивать «а что этому человеку можно», ответ уже в токене.

Не плодите realm без нужды. Частая ошибка новичка — заводить отдельный realm под каждое приложение. Тогда единый вход не работает: пользователь из одного realm не войдёт в приложение из другого. Несколько приложений одной компании — это несколько client внутри одного realm, а не несколько realm.

OAuth2 и OpenID Connect: как происходит вход

Keycloak не придумывает свой протокол — он работает по стандартам OAuth2 и OpenID Connect. Звучит сложно, но участников всего четыре, и каждый делает понятную вещь.

Самый частый сценарий входа называется Authorization Code Flow. По шагам он выглядит так:

1. Пользователь нажимает «Войти» в приложении
2. Приложение перенаправляет его на Keycloak
3. Keycloak показывает форму входа, пользователь вводит логин и пароль
4. Keycloak возвращает приложению временный код
5. Приложение меняет код на токены (этот шаг невидим для пользователя)
6. Приложение зовёт API, прикладывая токен
7. API проверяет токен и отдаёт данные

Важная деталь шестого и седьмого шагов: приложение никогда не показывает API логин и пароль. Оно показывает только токен. А пароль пользователь вводил один раз и только на странице Keycloak. Это и есть суть подхода — секрет живёт в одном месте, а не размазан по всем приложениям.

OpenID Connect — надстройка над OAuth2. OAuth2 отвечает на вопрос «что этому приложению разрешено делать от имени пользователя», а OpenID Connect добавляет ответ на вопрос «кто этот пользователь» — имя, почта, идентификатор. Keycloak поддерживает оба, поэтому одним входом вы получаете и доступ, и личность пользователя.

Что лежит внутри токена

Токен Keycloak — это JWT (JSON Web Token). Снаружи он выглядит как длинная строка из трёх частей, разделённых точками. Это не шифр — это данные в кодировке Base64, которые любой может прочитать. Защищает токен не секретность, а подпись.

eyJhbGciOiJSUzI1NiJ9 . eyJzdWIiOiI4Mi4uLiJ9 . SflKxwRJSMeKKF2QT4...
└──── заголовок ─────┘  └──── полезные данные ───┘  └─── подпись ───┘

Три части устроены так. Заголовок говорит, каким алгоритмом подписан токен. Полезные данные (payload) — это набор утверждений (claims) о пользователе. Подпись — то, чем Keycloak заверил содержимое своим закрытым ключом.

Если раскодировать полезную часть, внутри окажется примерно это:

{
  "sub": "8f2e...c41",            // идентификатор пользователя
  "preferred_username": "nikita", // логин
  "email": "nikita@hexlet.io",
  "realm_access": {
    "roles": ["user", "manager"]  // роли — прямо в токене
  },
  "iss": "https://auth.app/realms/hexlet",  // кто выдал
  "exp": 1735680000,              // когда протухнет
  "iat": 1735679700               // когда выдан
}

Отсюда главное практическое следствие. API не обязано на каждый запрос ходить в Keycloak и спрашивать «кто это». В токене уже всё есть: и кто пользователь, и какие у него роли, и до какого момента токен действителен. API только проверяет подпись и срок — и доверяет содержимому.

Два токена вместо одного

Keycloak выдаёт не один токен, а пару. Access token — короткоживущий, обычно несколько минут, его прикладывают к каждому запросу к API. Refresh token живёт дольше и нужен ровно для одного: получить новый access token, когда старый протух, не заставляя пользователя входить заново.

Короткая жизнь access token — это защита. Если он утечёт, злоумышленник попользуется им несколько минут, а не вечно. Refresh token хранят бережнее и при выходе пользователя отзывают на стороне Keycloak.

Поднять Keycloak и настроить вход

Запустить Keycloak для знакомства — одна команда. Контейнер поднимется с веб-консолью администратора:

docker run -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.0 start-dev

Дальше открываете http://localhost:8080, входите в консоль администратора и проходите четыре шага настройки — ровно те четыре понятия, что разобрали выше.

При создании client важна одна настройка — тип доступа. Публичный client (public) подходит фронтенду в браузере и мобильному приложению: они не умеют хранить секрет. Конфиденциальный (confidential) — для бэкенда, у которого есть надёжное место под секретный ключ. Для REST API, который только проверяет токены, выбирают режим без интерактивного входа — он просто валидирует приходящие токены.

Защита REST API

Вот ради чего всё затевалось. У вас есть API, и часть его эндпоинтов должна быть доступна только вошедшим пользователям, а часть — только с нужной ролью. С Keycloak это делается так: клиент прикладывает access token к запросу, а API проверяет его перед тем, как отдать данные.

GET /api/orders
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI4Mi4uLiJ9...

Что именно проверяет API, получив токен:

Разница между 401 и 403 здесь принципиальна. 401 значит «я не знаю, кто ты» — токена нет, он протух или поддельный. 403 значит «я знаю, кто ты, но тебе сюда нельзя» — токен валиден, но роли не той. Путать их — частая ошибка, которая сбивает с толку тех, кто потом разбирает логи.

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

Как это выглядит в Spring Boot

Если API на Spring Boot, почти всё делает стартер resource server. В настройках указываете адрес вашего realm, и Spring сам скачает ключи и начнёт проверять токены:

# application.yml
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.app/realms/hexlet

После этого доступ к эндпоинтам по ролям описывается прямо в коде. Аннотация проверит роль из токена до того, как метод выполнится:

@RestController
public class OrderController {

    @GetMapping("/api/orders")
    @PreAuthorize("hasRole('user')")     // нужна роль user
    public List<Order> list() { ... }

    @DeleteMapping("/api/orders/{id}")
    @PreAuthorize("hasRole('admin')")    // только admin
    public void delete(@PathVariable Long id) { ... }
}

Запрос без токена получит 401, запрос с токеном без роли admin на удаление — 403. Вы не написали ни строчки про проверку паролей, сессии или подписи — это сделали Keycloak и стартер.

Роли и единый вход

Роли в Keycloak бывают двух видов. Realm-роли общие для всего realm: admin, user. Client-роли привязаны к конкретному приложению: в одном client человек editor, в другом — обычный читатель. Так одна учётная запись получает разные права в разных приложениях.

Поверх ролей строится управление доступом по ролям — когда права проверяют не для каждого пользователя отдельно, а по его роли. Добавили человека в роль manager — он сразу получил всё, что этой роли разрешено, во всех приложениях.

Единый вход (Single Sign-On) — то, ради чего многие и приходят к Keycloak. Пользователь входит один раз и дальше попадает во все приложения realm без повторного ввода пароля. Работает это так: при первом входе Keycloak ставит свою сессию. Когда пользователь идёт во второе приложение, оно отправляет его на Keycloak, а тот видит активную сессию и сразу возвращает токен — без формы входа. Один вход утром — и весь день во всех сервисах компании.

Антипаттерны

Отдельный realm под каждое приложение. Тогда единый вход невозможен, а пользователей приходится заводить в каждом realm заново. Несколько приложений одной компании — это client внутри одного realm.

Долгоживущий access token «чтобы не обновлять». Сделали срок access token в сутки — и утёкший токен работает сутки. Короткий срок access token и обновление через refresh token существуют именно ради безопасности, а не для усложнения жизни.

API ходит в Keycloak на каждый запрос. Дёргать сервер для проверки каждого токена — лишняя нагрузка и задержка. Подпись проверяется локально по опубликованному ключу. Поход в Keycloak нужен редко — например, чтобы проверить, не отозван ли токен.

Секрет конфиденциального client в коде фронтенда. Браузерное приложение не умеет хранить секреты — всё, что в нём, видно пользователю. Для фронтенда заводят публичный client без секрета, а конфиденциальный оставляют бэкенду.

Проверять права по логину, а не по роли. Захардкоженное «если username равен admin» ломается на втором администраторе и при переименовании. Права проверяют по роли из токена — Keycloak для этого роли в токен и кладёт.

Что Keycloak умеет ещё

За пределами базового входа у Keycloak много готового, что иначе пришлось бы писать руками.

FAQ

Keycloak бесплатный?

Да, это продукт с открытым кодом — бесплатный и для учёбы, и для коммерческих проектов. Платить нужно за сервер, на котором он работает, и за время на настройку и сопровождение. У Red Hat есть платная версия с поддержкой, но базовый Keycloak полнофункционален.

Чем Keycloak отличается от Auth0 и Okta?

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

Нужно ли знать OAuth2, чтобы начать?

Базовое понимание сильно помогает — без него легко запутаться в client, токенах и сценариях входа. Но Keycloak можно поднять и настроить, разбираясь по ходу. Достаточно понимать роли участников и общий сценарий: приложение отправляет пользователя на Keycloak, получает токен, прикладывает его к запросам.

Что хранить на стороне приложения, а что в Keycloak?

В Keycloak — всё про вход: учётные записи, пароли, роли, сессии. В приложении — бизнес-данные пользователя: заказы, настройки, контент. Связь между ними держат по идентификатору пользователя (claim sub в токене), а не по логину, который может меняться.

Как выйти из системы, если токен уже выдан?

Access token короткоживущий и сам протухнет за минуты. При явном выходе приложение зовёт эндпоинт выхода Keycloak — тот завершает сессию и отзывает refresh token, чтобы новый access token по нему получить было нельзя. Активные access token доживают свой короткий срок, поэтому его и держат маленьким.

Можно ли использовать Keycloak с любым языком, не только с Java?

Да. Keycloak работает по стандартам OAuth2 и OpenID Connect, а их понимают библиотеки на любом языке: Python, JavaScript, Go, C#. Сам Keycloak написан на Java, но вашему приложению это неважно — оно общается с ним по открытым протоколам.