Microservice Security Example — микросервисная система с авторизацией через Keycloak

Этот проект демонстрирует интеграцию микросервисов с безопасностью на основе OAuth2 и JWT.
Система реализует банковский перевод между счетами, включая:

• аутентификацию пользователя через Keycloak (Authorization Code Flow);
• проброс пользовательского JWT через API Gateway (Token Relay);
• проверку прав пользователя и сервисов на основе ролей realm_access;
• вызовы между микросервисами через Client Credentials Flow;
• разделение ответственности между UI, Gateway, transfer-service и accounts-service.

---

Архитектура проекта

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

sequenceDiagram
    autonumber

    participant User as Пользователь
    participant UI as UI<br>(Spring MVC)
    participant KC as Keycloak
    participant GW as Gateway API<br>(Spring Cloud Gateway)
    participant TR as transfer-service
    participant AC as accounts-service

    User ->> UI: Открывает страницу перевода<br>вводит данные
    UI ->> KC: Перенаправление на авторизацию<br>(Authorization Code Flow)
    KC ->> UI: user-token (JWT)
    UI ->> GW: Запрос /api/transfers<br>с user-token
    GW ->> GW: Проверка JWT<br>Token Relay
    GW ->> TR: Проброс user-token
    TR ->> TR: Проверка ролей<br>USER + transfer.write
    TR ->> AC: Запрос проверки владельца<br>c service-token<br>(Client Credentials Flow)
    AC ->> AC: Проверка ролей<br>SERVICE + accounts.write
    AC ->> TR: Ответ о владельце
    TR ->> AC: Запрос перевода<br>c service-token
    AC ->> TR: Успешный результат
    TR ->> UI: Ответ об успешном переводе
    UI ->> User: Показ результата

Loading

---

Взаимодействие компонентов

UI (bank-ui)

• Аутентифицирует пользователя через Keycloak.
• Получает user-token (JWT).
• Делает запросы к Gateway с пользовательским токеном.
• Показывает страницу перевода и результат операции.

Gateway API (bank-gateway)

• Проверяет JWT как Resource Server.
• Выполняет кастомный Token Relay.
• Проксирует запросы в transfer-service.

transfer-service

• Принимает запросы с user-token.
• Проверяет роли пользователя (USER, transfer.write).
• Для вызова accounts-service получает service-token (Client Credentials Flow).
• Проверяет владельца счёта и выполняет перевод.

accounts-service

• Принимает запросы с service-token.
• Проверяет роли (SERVICE, accounts.write).
• Сообщает, кому принадлежит счёт.
• Выполняет перевод.

Keycloak

• Управляет пользователями, ролями и клиентами.
• Выдаёт JWT для UI и сервисов.

---

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

1. Keycloak

В проекте есть экспорт realm’а:

bank-realm.json

Он включает:

• realm bank-realm;
• пользователей;
• роли (USER, TRANSFER_WRITE, ACCOUNTS_WRITE);
• клиентов (bank-ui, transfer-service);
• протокольные мапперы.

Создавать realm, роли, пользователей или клиентов вручную НЕ нужно. При запуске контейнера Keycloak автоматически применяет этот экспорт, и вы сразу получаете полностью готовый к работе Keycloak без ручной настройки.

Запуск Keycloak

docker compose up

Keycloak поднимется на:

http://localhost:8080

---

2. Запуск сервисов

bank-gateway

./gradlew :bank-gateway:bootRun

accounts-service

./gradlew :accounts-service:bootRun

transfer-service

./gradlew :transfer-service:bootRun

bank-ui

./gradlew :bank-ui:bootRun

UI будет доступен по адресу:

http://localhost:8084

---

Проверка работы системы (тест-кейс)

Тест-кейс: успешный перевод между счетами

Шаги

1. Открыть UI:

   http://localhost:8084
   

2. Перейти на страницу перевода.
3. Нажать «Перейти к переводу денег».
4. Авторизоваться в Keycloak (Пользователь test-user, пароль test123).
5. Ввести параметры:
   • Счёт отправителя: ACC-001
   • Счёт получателя: ACC-002
   • Сумма: 100
6. Нажать «Перевести».
7. UI отправляет запрос в Gateway с пользовательским JWT.
8. Gateway проверяет токен и выполняет Token Relay.
9. transfer-service проверяет роли.
10. transfer-service получает сервисный токен.
11. transfer-service вызывает accounts-service.
12. UI получает успешный ответ и показывает результат.

• На UI отображается: «Перевод выполнен...»