Если поискать, как 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 покажет, что внутри.