JWT применяется в API для передачи данных о пользователе и подтверждения его прав. При работе с токеном важно проверять подпись, сроки действия и набор claim, иначе любой запрос может пройти без фактической проверки подлинности. В CSharp для этого используются классы из пространства имен System.IdentityModel.Tokens.Jwt и параметры TokenValidationParameters.
Для корректной проверки требуется точный ключ подписи, совпадающий с тем, что использует сервер. Ошибка в алгоритме, длине ключа или формате приводит к тому, что токен будет распознан, но не пройдет проверку. Поэтому ключ и алгоритм следует задавать явно, без автоматического подбора.
Помимо подписи, важно сверять значения iss, aud, exp и дополнительные claim. Проверка этих полей исключает использование токена от другого сервиса, предотвращает запросы с истекшим сроком и помогает отсекать подмененные данные. В ASP.NET Core это выполняется через встроенное middleware, которое проверяет токен до вызова контроллера.
Разбор структуры JWT токена перед проверкой
JWT состоит из трех частей, разделенных точками: заголовка, полезной нагрузки и подписи. Перед проверкой стоит декодировать первые две части через Base64Url, чтобы увидеть используемый алгоритм и набор claim. Это позволяет заранее определить, соответствует ли токен ожидаемой конфигурации.
В заголовке полезно проверить поле alg. Если сервис принимает только HMAC-SHA256 или другой конкретный алгоритм, токен с отличающимся значением следует отклонять еще до проверки подписи. Это снижает риск подмены алгоритма.
В полезной нагрузке стоит обратить внимание на iss, aud, sub и пользовательские claim. Несовпадение этих значений с параметрами сервера указывает на токен, выпущенный другим источником или измененный вручную. Такой предварительный разбор помогает настроить строгие правила валидации и заранее отсеивать некорректные данные.
Получение ключа подписи и выбор алгоритма
Проверка подписи требует точного совпадения ключа и алгоритма с теми, что использует сервер при выпуске токена. В CSharp ключ формируется на основе симметричной строки или открытого RSA-ключа, после чего передаётся в параметры валидации.
- Для HMAC-алгоритмов используется SymmetricSecurityKey. Строку ключа лучше хранить в переменных окружения или в секретах приложения, исключая прямое размещение в коде.
- Для RSA применяются RsaSecurityKey и заранее подготовленные пары ключей. Публичный ключ передаётся в приложение, а закрытый остаётся на сервере, который выпускает токены.
Алгоритм следует задавать явно, используя TokenValidationParameters.ValidAlgorithms или проверку поля alg. Это исключает принятие токена с алгоритмом, который приложение не использует. Задание списка допустимых значений помогает ограничить область проверки и избежать обработки неподходящих вариантов.
Проверка подписи токена через JwtSecurityTokenHandler
Для проверки подписи используется класс JwtSecurityTokenHandler. Метод ValidateToken принимает токен и параметры проверки, после чего возвращает объект ClaimsPrincipal или генерирует исключение при несоответствии подписи.
В параметрах необходимо указать ключ, список допустимых алгоритмов, настройки по проверке издателя и аудитории. Если поле ValidateIssuerSigningKey не включено, подпись не будет проверена даже при корректно заданном ключе, поэтому параметр должен быть установлен явно.
Перед вызовом ValidateToken стоит убедиться, что токен корректно закодирован и содержит три части. Обращение к методу с поврежденной строкой приводит к исключению SecurityTokenException, что помогает быстро выявить подменённый или неполный токен.
Анализ сроков действия: exp, nbf и другие параметры
Поле exp задаёт момент, после которого токен недействителен. При обработке в CSharp значение автоматически сравнивается с системным временем. Если сервер и клиент работают в разных часовых поясах или с заметным расхождением часов, стоит задать разумный ClockSkew, чтобы избежать ложных отказов.
Параметр nbf определяет время, начиная с которого токен допускается к проверке. Использование nbf помогает блокировать запросы с преждевременным доступом, особенно при выпуске токенов партиями или в распределённых системах.
Дополнительный параметр iat применяется для фиксации момента выпуска. Его можно использовать при диагностике, чтобы определить, был ли токен создан до обновления ключа подписи. При активной ротации ключей проверка iat позволяет отключать старые токены без изменения их срока действия.
Проверка издателя, аудитории и пользовательских claim
Параметры ValidIssuer и ValidAudience задают конкретные значения, которым должны соответствовать поля iss и aud. Несовпадение любого из них приводит к отклонению токена при вызове ValidateToken. Для сервисов с несколькими клиентами можно указать массив допустимых значений.
Для пользовательских claim часто требуется сверка с данными приложения: роль, идентификатор пользователя, уровень доступа. Проверка выполняется вручную после успешной валидации подписи и сроков действия, используя свойства объекта ClaimsPrincipal.
| Поле | Назначение | Что проверять |
|---|---|---|
| iss | Источник токена | Совпадение с ожидающимся значением |
| aud | Целевая система | Принадлежность приложению, которое принимает запрос |
| role / custom claim | Дополнительные параметры доступа | Соответствие требованиям конкретного маршрута или операции |
Предварительное сравнение этих полей сокращает вероятность обработки токена, предназначенного для другого сервиса, и позволяет применять внутренние политики доступа без дополнительных запросов к базе данных.
Обработка ошибок валидации и типичные сценарии отказа
При проверке токена через JwtSecurityTokenHandler возможны несколько видов ошибок, каждая из которых требует отдельного реагирования. Их обработка позволяет корректно информировать систему о причине отклонения токена.
- SecurityTokenExpiredException – срок действия токена истёк. Следует отклонять запрос и при необходимости предлагать пользователю обновление токена.
- SecurityTokenNotYetValidException – токен используется раньше времени, указанного в nbf. Нужно проверить синхронизацию времени сервера и клиента.
- SecurityTokenInvalidIssuerException – издатель токена не совпадает с ValidIssuer. Токен от другого сервиса или поддельный.
- SecurityTokenInvalidAudienceException – аудитория не соответствует ожидаемому значению, что указывает на попытку использовать токен в неверном приложении.
- SecurityTokenInvalidSignatureException – подпись не прошла проверку. Чаще всего ошибка в ключе или алгоритме.
Для безопасной обработки рекомендуется использовать блок try-catch вокруг вызова ValidateToken и логировать конкретный тип исключения. Это позволяет различать поддельные токены, устаревшие и некорректные, а также применять соответствующие меры защиты без остановки всей обработки запросов.
Проверка токена в middleware ASP.NET Core
В ASP.NET Core проверка JWT токена выполняется через Authentication Middleware, настроенный с использованием схемы JwtBearer. Middleware автоматически извлекает токен из заголовка Authorization и передаёт его на валидацию.
Настройки выполняются в Program.cs или Startup.cs через services.AddAuthentication().AddJwtBearer(), где указываются:
- TokenValidationParameters с ключом подписи, списком допустимых алгоритмов, проверкой issuer и audience.
- Events, позволяющие обрабатывать ошибки валидации и логировать попытки использования недействительных токенов.
- Опцию SaveToken, если требуется доступ к токену внутри контроллеров для дополнительных проверок claim.
Middleware гарантирует, что контроллеры и маршруты получают объект ClaimsPrincipal только после успешной проверки подписи и сроков действия. Любые отклонения автоматически возвращают статус 401 Unauthorized, что исключает ручную проверку на каждом уровне приложения.
Вопрос-ответ:
Как проверить подпись JWT токена в CSharp?
Для проверки подписи используется класс JwtSecurityTokenHandler. Создайте объект TokenValidationParameters, задав ключ подписи и алгоритм, затем вызовите ValidateToken. Метод вернёт объект ClaimsPrincipal, если подпись верна, или выбросит исключение при несоответствии.
Какие поля токена нужно проверять для срока действия?
Следует учитывать exp и nbf. exp указывает момент истечения токена, nbf — момент, с которого токен становится действительным. В CSharp их проверка выполняется автоматически, но при значительном расхождении времени между сервером и клиентом рекомендуется использовать ClockSkew для корректной оценки.
Как убедиться, что токен предназначен для нашего приложения?
Проверяйте поля iss и aud через TokenValidationParameters. iss должен совпадать с издателем токена, а aud — с аудиторией приложения. Несовпадение этих значений указывает на токен, созданный другим сервисом или поддельный.
Какие типичные ошибки возникают при проверке JWT и как их обработать?
Чаще всего встречаются SecurityTokenExpiredException для просроченного токена, SecurityTokenInvalidSignatureException при неверной подписи, SecurityTokenInvalidIssuerException и SecurityTokenInvalidAudienceException. Рекомендуется использовать блок try-catch вокруг ValidateToken, логировать тип ошибки и возвращать клиенту статус 401 Unauthorized при несоответствии.
Загрузка...
