← Cloudflare API Shield / api-shield / security

Проверка JSON Web Tokens

JSON web tokens (JWT) часто используются как часть механизма аутентификации во многих веб-приложениях. Поскольку JWT играют ключевую роль в идентификации пользователей и определении их прав доступа, важно обеспечивать целостность токена.

Проверка JWT в API Shield криптографически подтверждает подлинность входящих токенов до того, как они попадут на источник вашего API. Она обнаруживает токены с истёкшим сроком действия, изменённые или ещё не вступившие в силу. После этого вы создаёте правило, которое реагирует на результаты проверки.

Валидация JWT состоит из двух частей: конфигурации токена, которая сообщает Cloudflare, как находить и проверять JWT, и правила, которое обрабатывает результаты валидации.

После создания конфигурации токена Cloudflare проверяет каждый запрос в зоне на наличие JWT в настроенных местах. Когда Cloudflare находит JWT, она проверяет токен и делает подтверждённые claims доступными в http.request.jwt.claims полей. Список доступных полей и стандартных утверждений см. в Поля валидации JWT ссылку. Правило или операция в Endpoint Management для проверки. Правила определяют, как Cloudflare обрабатывает результаты.

Каждый издатель JWT обычно публикует открытые ключи (JWKS) для проверки по известному URL-адресу в интернете. Если вы не знаете, где их найти, обратитесь к администратору вашей системы идентификации.

Чтобы автоматически поддерживать актуальность JWKS при их обновлении на стороне вашего провайдера идентификации, можно использовать Worker. Подробнее см. Настройка Workers для автоматического обновления ключей чтобы узнать больше о настройке Worker.

Для новых политик безопасности Cloudflare обычно рекомендует использовать пользовательские правила WAF.

• Пользовательские правила WAF используйте их для политик уровня зоны на основе проверенных утверждений JWT. Пользовательские правила могут сочетать утверждения с другими сигналами, такими как оценка атаки. Конечные точки не обязательно должны находиться в Endpoint Management.
• Правила валидации JWT используйте их, если применение правила должно ограничиваться конкретными операциями в Endpoint Management. Эти правила поддерживают is_jwt_valid() и is_jwt_present() функции, которые недоступны в пользовательских правилах.

Cloudflare проверяет JWT одинаково независимо от выбранного типа правила.

Например, чтобы сослаться на простой строковый claim в выражении правила, используйте lookup_json_string() вашим ID конфигурации токена и именем claim:

lookup_json_string(http.request.jwt.claims["<TOKEN_CONFIGURATION_ID>"][0], "claim_name")

Полный пример см. в Проверка администратора по JWT claim на основе показателя атаки. Полный список доступных полей см. в Поля валидации JWT справочник.

Правила валидации JWT используют операции из Endpoint Management, чтобы определить, где Cloudflare применяет их log или block действие.

Если вы ожидаете, что в запросе должны присутствовать два разных JWT, и хотите проверять оба, создайте две отдельные конфигурации токена. При выборе обеих конфигураций в правиле валидации выберите Проверка всех конфигураций в разделе Поведение проверки при нескольких конфигурациях.

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

API Shield будет проверять JSON Web Token независимо от того, есть ли у них Bearer префикс.

Вы можете ограничивать частоту запросов на основе любого claim внутри JSON Web Token (JWT), например:

• Зарегистрированные claims, такие как aud или sub
• Пользовательские claims, например userEmail, включая вложенные пользовательские утверждения, такие как user.email

Ограничение скорости на основе значений JWT claim работает только с действительными JSON Web Tokens. Если вы не блокируете недействительные JSON Web Tokens на своём пути, Все JWT claims будут учитываться и могут быть заблокированы при обнаружении высокого трафика в точке присутствия (PoP).

Также необходимо учитывать claim JWT, однозначно идентифицирующий пользователя. Если выбранный claim одинаков для нескольких пользователей, их ограничения скорости запросов будут учитываться совместно.

Если на вашем сайте или в приложении предусмотрено несколько тарифных уровней и вы хотите применять ограничение частоты запросов в зависимости от уровня, например:

• Если "aud": "free-tier", ограничьте скорость до пяти запросов в минуту.
• Если "aud": "premium-tier", ограничьте скорость до 50 запросов в минуту.

Ниже приведен пример правила ограничения частоты запросов:

(http.request.method eq "GET" and
http.host eq "<YOUR_DOMAIN>" and
http.request.uri.path matches "</EXAMPLE_PATH>" and
lookup_json_string(http.request.jwt.claims["<JWT_TOKEN_CONFIGURATION_ID>"][0], "aud") eq "free-tier"

Из соображений безопасности совместного использования ресурсов между источниками (CORS) браузеры отправляют предварительные запросы «preflight» с помощью метода OPTIONS метод к конечным точкам API перед отправкой GET (или другой метод) запрос. По определению, OPTIONS preflight-запросы не содержат учётных данных (заголовков аутентификации или cookie-файлов) и являются анонимными.

Если вы допускаете, что веб-браузеры могут быть легитимными клиентами вашего API, и хотите избежать блокировки OPTIONS запросов из этих браузеров Cloudflare рекомендует добавить or http.request.method eq "OPTIONS" в ваши правила проверки JWT.

Валидация JWT доступна всем клиентам API Shield. Клиенты плана Enterprise, которые не приобрели API Shield, могут ознакомиться с API Shield как услуга без контракта ↗ в панели управления Cloudflare или обратившись в свою команду по работе с клиентами.

Валидация JWT работает только с JWT, отправленными в заголовках запроса клиента или cookie. Если ваши клиенты отправляют JWT в POST тела запроса, обратитесь к своей команде по работе с аккаунтом.