Когда продукт использует токенную аутентификацию, интерфейс взаимодействия между клиентом, API и сервисом токенов становится нетривиальным. Пользователь вводит пароль, получает пару токенов, работает с системой, а когда срок действия access token истекает, клиент автоматически запрашивает новый. Если этот механизм ломается или пользователь вводит неверные данные, поведение системы должно быть предсказуемым. Диаграмма последовательности позволяет зафиксировать эти состояния и переходы в одном виде, понятном разработчикам, тестировщикам и аналитикам. Ниже — полный разбор того, как собрать такой сценарий в PlantUML, начиная от базовой структуры и заканчивая обработкой исключений.
Акторы и компоненты сценария
В типичном сценарии авторизации участвуют три основные роли. Первая — клиент (браузер, мобильное приложение или CLI-утилита). Он инициирует запрос, хранит полученные токены локально и управляет жизненным циклом сессии. Вторая — API Gateway или основной эндпоинт приложения. Этот компонент принимает входящие HTTP-запросы, проверяет наличие и валидность access token, маршрутизирует запросы к внутренним сервисам. Третья — Token Service (или Auth Server). Отдельный микросервис или модуль, который отвечает за выпуск, проверку и отзыв токенов. Именно он хранит refresh tokens и выдаёт новые access tokens по запросу.
Важно различить access token и refresh token. Access token — это короткий-lived JWT (обычно 5–15 минут), который клиент прикрепляет к каждому защищённому запросу в заголовке Authorization. Refresh token — это длинный-lived opaque string (часы или дни), который используется только для получения нового access token. Разделение этих ролей снижает риск компрометации: если access token утекает, окно злоупотребления ограничено его коротким временем жизни, а refresh token хранится в более защищенном месте (httpOnly cookie или secure storage).
Базовая структура диаграммы
PlantUML для диаграмм последовательности использует ключевое слово @startuml и @enduml. Акторы объявляются через participant или actor. В нашем случае все три участника — программные компоненты, поэтому используем participant. Сообщения передаются стрелками: -> для синхронного запроса, <-- для ответа. Асинхронные сообщения обозначаются пунктирной стрелкой -->.
Первый шаг — определение участников. Порядок объявления определяет их расположение слева направо на диаграмме. Логичный порядок: Клиент → API Gateway → Token Service. Это отражает направление потока данных: запрос идёт от клиента внутрь системы.
@startuml
!theme plain
title Авторизация: вход и обновление токена
participant "Клиент" as Client
participant "API Gateway" as GW
participant "Token Service" as TS
@enduml
Этот каркас задаёт канву. Теперь наполняем его логикой сценария. Каждый блок действий соответствует одному логическому шагу: вход, использование, обновление, ошибка.
Сценарий успешного входа
Пользователь открывает форму логина и вводит учётные данные. Клиент отправляет POST-запрос на эндпоинт /api/auth/login с телом, содержащим username и password. API Gateway не проверяет credentials напрямую — он делегирует эту задачу Token Service. Это важно: Gateway остаётся stateless относительно аутентификации, а вся логика проверки паролей, хэширования и выпуска токенов инкапсулирована в Token Service.
Token Service выполняет следующие операции: находит пользователя по username, сравнивает hash пароля с переданным значением, при совпадении генерирует пару JWT. Access token содержит claims: user_id, exp (expiration time), iat (issued at), scope. Refresh token — случайная строка, которую сервис сохраняет в БД с привязкой к user_id и сроком действия. Оба токена возвращаются клиенту в JSON-ответе со статусом 200 OK.
Client -> GW : POST /api/auth/login\n{username, password}
GW -> TS : validateCredentials(username, password)
TS ->> TS : checkPasswordHash()
TS --> GW : {accessToken, refreshToken}
GW --> Client : 200 OK\n{accessToken, refreshToken}
Обратите внимание на пунктирную стрелку от Token Service к самому себе (>>). Она обозначает внутреннюю операцию — проверку хэша пароля. Это не сетевой вызов, а локальная логика. Включение таких внутренних шагов делает диаграмму информативнее: читатель видит, что происходит «под капотом» компонента, без необходимости читать исходный код.
Использование access token
После успешного входа клиент начинает делать обычные запросы к API. Например, GET /api/orders. Клиент добавляет заголовок Authorization: Bearer <accessToken>. API Gateway перехватывает запрос, извлекает JWT и выполняет первичную проверку: подпись валидна? Expired? Если да — запрос пробрасывается дальше. Если нет — Gateway может либо вернуть 401 сразу, либо попытаться обновить токен (если поддерживает прозрачное обновление). В большинстве современных архитектур Gateway не обновляет токены сам; он просто отклоняет просроченный токен, а клиент обрабатывает 401 и запускает процедуру refresh.
Client -> GW : GET /api/orders\nAuthorization: Bearer <at>
GW -> TS : verifyJWT(accessToken)
TS --> GW : valid=true
GW --> Client : 200 OK\n[orders]
Этот блок показывает happy path: токен валиден, запрос проходит. Важно подчеркнуть, что проверка JWT в Token Service включает верификацию подписи (HMAC-SHA256 или RSA) и проверку времени истечения. Если подпись невалидна или токен expired, TS вернёт valid=false, и GW получит сигнал для отказа.
Автоматическое обновление токена
Через несколько минут access token истекает. Клиент делает очередной запрос, Gateway проверяет JWT, обнаруживает exp < now() и возвращает 401 Unauthorized с заголовком WWW-Authenticate: Bearer error="invalid_token", error_description="expired". Клиент не показывает пользователю ошибку. Вместо этого он автоматически выполняет POST /api/auth/refresh с refresh token в теле запроса.
Token Service проверяет refresh token: существует ли в БД, не отозван ли, не истёк ли. Если всё в порядке — выпускает новый access token и, опционально, ротирует refresh token (выдаёт новый, старый аннулируется). Ротация повышает безопасность: даже если старый refresh token будет украден после ротации, он бесполезен.
Client -> GW : GET /api/orders\nAuthorization: Bearer <old_at>
GW -> TS : verifyJWT(old_at)
TS --> GW : valid=false (expired)
GW --> Client : 401 Unauthorized
Client -> GW : POST /api/auth/refresh\n{refreshToken}
GW -> TS : rotateRefreshToken(refreshToken)
TS ->> TS : invalidateOldRT()\nissueNewAT()
TS --> GW : {newAccessToken, newRefreshToken}
GW --> Client : 200 OK\n{newAccessToken, newRefreshToken}
Client -> GW : GET /api/orders\nAuthorization: Bearer <new_at>
GW --> Client : 200 OK\n[orders]
Ключевой момент: после обновления клиент повторяет исходный запрос с новым токеном. Это обеспечивает бесшовный опыт для пользователя — он не замечает, что сессия была прервана. На диаграмме это видно как повторение блока «Использование access token» с новым значением токена.
Обработка ошибок
Не все сценарии завершаются успехом. Рассмотрим три типовые ошибки: неверный пароль, истёкший refresh token, отозванный refresh token.
Неверный пароль. При POST /login Token Service не находит совпадение хэшей. Возвращает GW ошибку. GW формирует ответ 401 Unauthorized с сообщением «Неверный логин или пароль». Важно: сообщение не уточняет, какая именно часть неверна (логин vs пароль), чтобы не облегчить brute-force атаку. Клиент отображает это сообщение пользователю.
Истёкший refresh token. Клиент пытается обновить токен, но refresh token имеет срок действия (например, 7 дней), и он прошёл. Token Service не находит активную запись RT в БД. Возвращает ошибку. GW отдаёт 401. Клиент понимает, что refresh невозможен — сессия окончательно закрыта. Пользователю предлагается войти заново. На диаграмме это отдельный поток, где после 401 на refresh следует редирект на страницу логина.
Отозванный refresh token. Администратор заблокировал пользователя или пользователь сам вышел из всех сессий. Refresh token помечен как revoked в БД. Token Service видит флаг и отказывает. Поведение аналогично предыдущему случаю: 401, выход на логин.
alt Неверный пароль
Client -> GW : POST /api/auth/login\n{wrong_password}
GW -> TS : validateCredentials()
TS --> GW : invalid_credentials
GW --> Client : 401 Unauthorized\n"Неверный логин или пароль"
end
alt Refresh token expired/revoked
Client -> GW : POST /api/auth/refresh\n{stale_RT}
GW -> TS : rotateRefreshToken(stale_RT)
TS --> GW : rt_invalid
GW --> Client : 401 Unauthorized\n"Сессия истекла"
note right of Client
Клиент очищает
локальное хранение
и показывает форму
логина
end note
end
Bлок alt в PlantUML создаёт условную ветвь. Внутри него можно разместить альтернативные сценарии. В данном случае показаны две ветви ошибки. Комментарий note right добавляет визуальную подсказку о том, что делает клиент после получения 401 на refresh — это полезно для понимания UX-поведения.
Сводная таблица состояний и реакций
Чтобы быстро ориентироваться в логике системы, полезно свести все возможные исходы взаимодействий с токенами в единую таблицу. Эта таблица отражает поведение, которое должно быть реализовано в коде и показано на диаграмме. Она также служит чек-листом для тестирования: каждый ряд — потенциальный test case.
| Ситуация | Компонент | HTTP Status | Действие клиента | Примечание |
|---|---|---|---|---|
| Успешный вход | Token Service | 200 OK | Сохранить AT и RT | RT должен храниться безопасно |
| Неверный пароль | Token Service | 401 Unauthorized | Показать ошибку | Не уточнять причину (логин/пароль) |
| Access token истёк | API Gateway | 401 Unauthorized | Вызвать refresh | Check WWW-Authenticate header |
| Refresh token валиден | Token Service | 200 OK | Заменить AT, обновить RT | Ротация RT рекомендуется |
| Refresh token истёк | Token Service | 401 Unauthorized | Logout, show Login | Сессия закрыта навсегда |
| Refresh token отозван | Token Service | 401 Unauthorized | Logout, show Login | Проверить flag 'revoked' in DB |
Эта таблица помогает избежать неоднозначностей при реализации. Например, если разработчик не знает, что делать клиенту при 401 на refresh, он смотрит в таблицу: «Logout, show Login». Аналогично, если тестировщик пишет тесты, он итератирует по строкам таблицы, обеспечивая покрытие всех граничных случаев.
Полный рабочий пример PlantUML
Ниже собран весь сценарий в единый файл. Он включает определение участников, три основных блока (login, usage, refresh) и обработку ошибок через alt-блоки. Код готов к вставке в редактор PlantUML.
@startuml
!theme plain
title Сценарий авторизации: вход, обновление токена, ошибки
skinparam sequenceMessageAlign left
skinparam responseMessageBelowArrow true
participant "Клиент\n(Browser/App)" as C
participant "API Gateway" as G
participant "Token Service" as T
== Вход ==
C -> G : POST /api/auth/login\n{username, password}
G -> T : validateCredentials()
T ->> T : checkPasswordHash()
alt Успех
T --> G : {at, rt}
G --> C : 200 OK\n{accessToken, refreshToken}
else Неверный пароль
T --> G : invalid_credentials
G --> C : 401 Unauthorized\n"Неверный логин или пароль"
end
== Использование ==
C -> G : GET /api/orders\nAuthorization: Bearer <at>
G -> T : verifyJWT(at)
T --> G : valid=true
G --> C : 200 OK [orders]
== Обновление токена ==
C -> G : GET /api/orders\nAuthorization: Bearer <old_at>
G -> T : verifyJWT(old_at)
T --> G : expired
G --> C : 401 Unauthorized
C -> G : POST /api/auth/refresh\n{refreshToken}
G -> T : rotateRefreshToken(rt)
T ->> T : invalidateOldRT()\nissueNewAT()
alt RT валиден
T --> G : {new_at, new_rt}
G --> C : 200 OK\n{newAccessToken, newRefreshToken}
C -> G : GET /api/orders\nAuthorization: Bearer <new_at>
G --> C : 200 OK [orders]
else RT истёк/отозван
T --> G : rt_invalid
G --> C : 401 Unauthorized\n"Сессия истекла"
note right of C
Очистка storage,
redirect to /login
end note
end
@enduml
Этот код демонстрирует все ключевые элементы: последовательность сообщений, условные ветвления, внутренние операции, комментарии. Он компактен, но полон. Его можно расширить добавлением rate-limiting, CSRF-проверки или logout-сценария.
Проверка корректности диаграммы
После написания диаграммы её нужно проверить. Во-первых, убедитесь, что каждый participant имеет хотя бы одну исходящую или входящую стрелку — изолированные участники указывают на ошибку модели. Во-вторых, проверьте баланс alt/if блоков: каждый alt должен иметь end, каждая ветвь должна завершаться ответом. В-третьих, прочитайте диаграмму сверху вниз как историю: «Клиент делает X, Gateway отвечает Y...». Если в какой-то момент логика обрывается или появляется необъяснённое действие — это баг в модели.
Также полезно сверить диаграмму с OpenAPI-спецификацией. Каждый endpoint на диаграмме должен существовать в spec. Статусы ответов (200, 401) должны совпадать. Если в OpenAPI указан 403 Forbidden, а на диаграмме только 401 — добавьте ветвь для 403 (например, токен валиден, но недостаточно прав).
Частые ошибки при создании
- Смешение уровней абстракции. Показ на диаграмме внутренней работы JWT-библиотеки (распарсивание base64, проверка signature) — слишком низкоуровневый слой. Оставьте только «verifyJWT» как атомарную операцию.
- Отсутствие обработки ошибок. Диаграмма с только happy path не полезна. Всегда включайте хотя бы один alt-блок с ошибкой.
- Непоследовательное именование. То
accessToken, тоtoken, тоjwt. Выберите одно название и используйте везде. - Игнорирование ротации refresh token. Если ваш дизайн предполагает ротацию, она должна быть видна на диаграмме: старый RT аннулируется, новый выдаётся. Иначе диаграмма вводит в заблуждение.
- Слишком длинные сообщения. Текст в стрелках должен быть кратким: метод, путь, ключевые параметры. Детали — в notes или отдельной таблице.
Интеграция с другими артефактами
Диаграмма последовательности не существует в вакууме. Она ссылается на OpenAPI-спецификацию (для точных форматов запросов/ответов), на BPMN-диаграмму (если авторизация — часть большего бизнес-процесса), на классы UML (для структуры Token Service). Убедитесь, что терминология во всех документах совпадает. Если в OpenAPI endpoint называется /auth/token, а на диаграмме /api/auth/refresh — это расхождение, которое нужно устранить.
Хранить такую диаграмму лучше в формате PlantUML-кода в репозитории рядом с OpenAPI-spec. Тогда при изменении API можно одновременно обновить и спецификацию, и диаграмму, и зафиксировать изменения в git-истории. Генерировать изображение PNG/SVG можно автоматически через CI-pipeline.
Итог
Диаграмма последовательности для сценария авторизации — это не иллюстрация, а рабочий инструмент проектирования. Она фиксирует контракт между клиентом, gateway и token service, делает видимыми edge cases (истечение, отзыв, неверные данные) и служит основой для написания unit- и integration-тестов. Правильно построенная диаграмма экономит часы обсуждений и предотвращает целую категорию багов, связанных с неправильной обработкой сессий. Начните с каркаса из трёх участников, добавьте happy path, затем ветви ошибок — и получите документ, который понимают все: от бэкенд-разработчика до QA-инженера.
Для создания и редактирования такого файла используйте редактор PlantUML. Более широкий контекст применения UML-диаграмм в работе аналитика — в статье «UML для системных аналитиков».
