Skip to main contentSkip to navigation
Назад в блог
Руководства

Руководство по интеграции JWT: добавьте аутентификацию по токенам в своё приложение

Пошаговое руководство по жизненному циклу JWT в приложениях с email и паролем: регистрация, вход, хранение токена, проверка на сервере, 2FA и выход, а также отладка токенов в jwt.io.

Обновлено
6 мин чтения

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

В этом руководстве рассматривается весь жизненный цикл JSON Web Token в приложении с входом по почте и паролю — от первой регистрации до выхода — на примере REST API AuthFlow™. Сам формат токена определён в RFC 7519; читать его, чтобы разобраться в материале, не нужно.

Что такое JWT и чем он не является

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

JWT состоит из трёх частей: заголовка (тип токена и алгоритм подписи), полезной нагрузки с утверждениями (claims) о пользователе и подписи. Подпись доказывает, что токен не был изменён. Она ничего не скрывает. Полезная нагрузка лишь закодирована в base64, поэтому любой, кто получил токен, может её прочитать. Считайте JWT защищённым от подделки, но не секретным.

Никогда не кладите пароль в токен

Частый вопрос новичков: можно ли хранить учётные данные пользователя в JWT? Как правило, это не нужно: сам токен — это кратковременная учётная запись, выданная при входе. Если нужно идентифицировать пользователя, поместите идентификатор в утверждение sub, а при необходимости — роль или уровень доступа. Не включайте пароли, секреты и всё, что вы не хотели бы видеть в браузере.

HTTPS — это отдельный вопрос, и использовать его нужно для всего. Он защищает трафик между клиентом и сервером, тогда как подпись JWT защищает целостность токена. Одно другого не заменяет.

Шаг 1. Храните API-ключ на своём сервере

Каждый вызов AuthFlow выполняется от имени вашей организации с использованием API-ключа из панели владельца. Этот ключ должен находиться в инфраструктуре, которую вы контролируете, например в серверной переменной окружения вроде AUTHFLOW_API_KEY. Никогда не отправляйте его в браузерном JavaScript. Самая простая безопасная схема — небольшой бэкенд (или публикуемый нами прокси на ExpressJS), с которым общается ваш фронтенд и который от его имени обращается к /auth.

Шаг 2. Регистрация и вход

Перед регистрацией или входом ваш бэкенд запрашивает у /auth/fooBar краткоживущий антиспам-токен для почты пользователя. Он истекает через 45 секунд, поэтому получайте его непосредственно перед следующим вызовом и никогда не используйте повторно. Затем вызовите /auth/signUp со значением foobar, вашим api_key, email, password, соответствующим правилу сложности (от 8 до 32 символов, с заглавной и строчной буквами, цифрой и специальным символом), fullname и disclaimed, равным true. Успешная регистрация сразу возвращает токен сессии, а повторяющиеся email и роль приводят к ответу 409.

Вход работает так же, через /auth/login. При успехе вы получаете токен сессии — JWT, подписанный алгоритмом RS512. RS512 использует пару ключей, поэтому токены подписываются закрытым ключом, который вы никогда не видите, и могут проверяться без передачи какого-либо секрета.

Шаг 3. Аккуратно храните токен

Когда токен получен бэкендом, решите, где он будет храниться. Рекомендуемый вариант — HTTP-only cookie: скрипты страницы не могут их прочитать, что ограничивает ущерб от уязвимости межсайтового скриптинга. Что бы вы ни выбрали, храните токен сессии, а не временный, и следите за тем, чтобы он никогда не попадал в логи.

Шаг 4. Проверяйте токен на каждом защищённом маршруте

Прежде чем бэкенд обработает защищённый запрос, проверьте токен. Вызовите /auth/validate с sessionToken и email пользователя: действительный токен проходит проверку, а недействительный или просроченный возвращает 401. Используйте /auth/me, когда нужен профиль текущего пользователя. Делать это на сервере для каждого защищённого запроса важно, потому что подписанный токен, который вы никогда не проверяете, ничего не защищает.

Истечение срока действия — часть замысла. Когда токен истекает, пользователь входит заново, а приложение не пытается незаметно его продлить. Убедитесь, что приложение корректно обрабатывает этот ответ 401, возвращая пользователя на страницу входа.

Шаг 5. Обработка двухфакторной аутентификации

Если пользователь включил 2FA, /auth/login не возвращает токен сессии. Вместо него возвращаются requires2FA и tempToken. Затем приложение запрашивает второй фактор и обменивает tempToken через одну из конечных точек проверки /auth/2fa (код TOTP, резервный код или OTP по почте). Только этот обмен выдаёт настоящий токен сессии, поэтому сохраняйте именно его, а не tempToken.

Отладка токенов с помощью jwt.io

Если что-то не так, самый быстрый способ увидеть, что на самом деле содержит токен, — jwt.io. Вставьте токен в его отладчик, и он декодирует заголовок и полезную нагрузку, чтобы вы могли проверить алгоритм, утверждение sub и время истечения. Обычно этого достаточно, чтобы заметить просроченный токен, не того пользователя или tempToken, сохранённый по ошибке.

Из всего сказанного следует одна предосторожность: токен — это учётные данные. Относитесь к действующему рабочему токену как к конфиденциальным данным, при отладке отдавайте предпочтение тестовым аккаунтам и не вставляйте реальные токены в инструменты, которым не доверяете. Декодирование токена — это не то же самое, что его проверка. Проверка по-прежнему выполняется на вашем сервере через /auth/validate.

Шаг 6. Выход из системы

Чтобы завершить сессию, вызовите /auth/logout с sessionToken и email, а затем удалите токен оттуда, где вы его хранили. Смена пароля выполняется аналогично через /auth/changePassword. Ведение журнала событий аутентификации по ходу работы даст вам полезную историю, если что-то пойдёт не так.

Чек-лист интеграции JWT

  • API-ключ хранится только в серверной конфигурации, никогда в коде браузера.
  • Перед каждой регистрацией и входом выполняется новый вызов /auth/fooBar.
  • В полезную нагрузку токенов не помещаются пароли и секреты; пользователей идентифицируют по sub и роли.
  • Токен сессии хранится в HTTP-only cookie или другом хранилище, контролируемом сервером.
  • Каждый защищённый маршрут проверяет токен через /auth/validate, прежде чем выполнять какую-либо работу.
  • Просроченные или недействительные токены (401) возвращают пользователя на страницу входа.
  • В сценарии 2FA сохраняется итоговый токен сессии, а не tempToken.
  • Весь трафик идёт по HTTPS, а токены никогда не попадают в логи.

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

интеграция JWTJWT аутентификация по email и паролюаутентификация на основе токеновотладчик jwt.ioJWT RS512