← Cloudflare API Shield / api-shield / security / jwt-validation

Настройка JWT validation через API

Используйте API Cloudflare для настройки Проверка JWT. Конфигурация токена определяет, как Cloudflare находит и проверяет JWT. Затем вы используете пользовательское правило WAF или правило проверки токена, чтобы принять меры по результатам.

Конфигурация токена определяет набор JSON Web Key Set (JWKS), используемый для проверки JSON Web Token (JWT). Она также определяет, где Cloudflare ищет JWT в запросах.

Для конфигурации токена требуется следующая информация:

Каждый элемент должен быть выражением Ruleset Engine, которое возвращает строку.

В настоящее время поддерживаются следующие поля: http.request.headers и http.request.cookies.

Вы можете задать до четырех источников токена. Если в запросе задано несколько таких полей, будет использовано только одно. Начальные Bearer: строки в токенах запроса автоматически игнорируются.

См. Документация Ruleset Engine подробнее о работе с полями Ruleset Engine.

API Shield поддерживает учётные данные типа RS256, RS384, RS512, PS256, PS384, PS512, ES256, а также ES384. Ключи RSA должны быть не менее 2048 бит. У каждого JSON web key должен быть параметр «KID», который также должен присутствовать в заголовке JWT, чтобы API Shield мог их сопоставить.

Укажите alg значение для каждого JSON Web Key. Используемый алгоритм, заданный явно или применённый по умолчанию, должен совпадать с alg значением в заголовке JWT.

Для совместимости с поставщиками удостоверений, которые не указывают alg, по умолчанию API Shield использует ключ RSA без alg к RS256. Размер ключа RSA не определяет, какой алгоритм подписи использует поставщик удостоверений. Укажите alg явно, если провайдер идентификации использует другой поддерживаемый алгоритм.

Допускается использование до 4 разных ключей для упрощения ротации ключей.

Cloudflare удаляет из каждого ключа все лишние поля, а также отбрасывает ключи, которые не поддерживаются.

Настоятельно рекомендуется проверять результат вызова API, чтобы убедиться, что полученные ключи соответствуют ожиданиям.

В примере ниже показан объект JSON со всей информацией, необходимой для создания конфигурации токена с помощью Cloudflare API. Если вы хотите создать JWK для тестирования, см. mkjwk JSON Web Key Generator ↗.

{
	"title": "Production JWT configuration",
	"description": "This configuration checks the JWT in the authorization header or cookie.",
	"token_sources": [
		"http.request.headers[\"authorization\"][0]",
		"http.request.cookies[\"Authorization\"][0]"
	],
	"token_type": "jwt",
	"credentials": {
		"keys": [
			{
				"kty": "EC",
				"use": "sig",
				"crv": "P-256",
				"kid": "93UrzmNu1mqXs5cZcvCPkTlMHB2Jya30vSTkiBb0vhU",
				"x": "QG3VFVwUX4IatQvBy7sqBvvmticCZ-eX5-nbtGKBOfI",
				"y": "A3PXCshn7XcG7Ivvd2K_DerW4LHAlIVKdqhrUnczTD0",
				"alg": "ES256"
			}
		]
	}
}

Используйте cURL или любой другой клиент API, чтобы отправить новую конфигурацию в API Cloudflare и включить проверку JWT. Обязательно замените {zone_id} соответствующим ID зоны и добавьте свой учётные данные для аутентификации заголовок.

curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/config" \
--header 'Content-Type: application/json' \
--data '{
    "title": "Production JWT configuration",
    "description": "This configuration checks the JWT in the authorization header or cookie.",
    "token_sources": [
        "http.request.headers[\"authorization\"][0]",
        "http.request.cookies[\"Authorization\"][0]"
    ],
    "token_type": "jwt",
    "credentials": {
        "keys": [
            {
                "kty": "EC",
                "use": "sig",
                "crv": "P-256",
                "kid": "93UrzmNu1mqXs5cZcvCPkTlMHB2Jya30vSTkiBb0vhU",
                "x": "QG3VFVwUX4IatQvBy7sqBvvmticCZ-eX5-nbtGKBOfI",
                "y": "A3PXCshn7XcG7Ivvd2K_DerW4LHAlIVKdqhrUnczTD0",
                "alg": "ES256"
            }
        ]
    }
}'

Ответ будет представлен в формате Cloudflare v4 конверт ответа (response envelope), а результат содержит созданную конфигурацию. Запишите возвращённый ID. Его можно использовать для ссылки на конфигурацию токена в полях claim JWT или в правилах проверки токена.

{
	"result": {
		"id": "d5902294-00c3-4aed-b517-57e752e9cd58",
		"token_type": "JWT",
		"title": "Production JWT configuration",
		"description": "This configuration checks the JWT in the authorization header or cookie.",
		"token_sources": [
			"http.request.headers[\"authorization\"][0]",
			"http.request.cookies[\"Authorization\"][0]"
		],
		"credentials": {
			"keys": [
				{
					"x": "QG3VFVwUX4IatQvBy7sqBvvmticCZ-eX5-nbtGKBOfI",
					"y": "A3PXCshn7XcG7Ivvd2K_DerW4LHAlIVKdqhrUnczTD0",
					"alg": "ES256",
					"crv": "P-256",
					"kid": "93UrzmNu1mqXs5cZcvCPkTlMHB2Jya30vSTkiBb0vhU",
					"kty": "EC"
				}
			]
		},
		"created_at": "2023-11-08T16:45:17.236841Z",
		"last_updated": "2023-11-08T16:45:17.236841Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

Если API Shield подставляет алгоритм по умолчанию при его отсутствии, ответ включает фактически применённый алгоритм в result. messages массив также содержит одно сообщение для каждого ключа со значением по умолчанию:

{
	"code": 110003,
	"message": "keys[0].alg was omitted and defaulted to \"RS256\" (kid \"key-1\")"
}

Проверьте оба result и messages чтобы подтвердить действующие учётные данные.

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

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

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

Чтобы сослаться на пользовательское утверждение (claim) в выражении правила, можно использовать lookup_json_* функции, такие как lookup_json_string() вашим ID конфигурации токена и именем claim. Полный пример см. в Проверка администратора по JWT claim на основе показателя атаки. Полный список доступных полей и стандартных утверждений см. в Поля валидации JWT справочник.

Правила проверки токенов применяют политику безопасности на основе существующих конфигураций токенов и операций в Endpoint Management.

Правила проверки токенов можно настроить через Cloudflare API или панель управления.

Селекторы определяют, к каким операциям из Endpoint Management Cloudflare применяет действие правила проверки токена.

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

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

Чтобы найти operation ID, ознакомьтесь с Endpoint Management или используйте Cloudflare API.

Выражение правила проверки токена задаёт политику безопасности, которой должен соответствовать запрос.

Например, выражение is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") or is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") сработает, если во входящем запросе нет хотя бы одного действительного токена аутентификации.

Эти выражения похожи на выражения, используемые в Ruleset Engine, с несколькими ключевыми отличиями:

• Действия правила проверки токена срабатывают, если выражение возвращает false, в отличие от выражений Ruleset.
• В правилах проверки токенов можно использовать специальные функции, которые ссылаются на конфигурации токенов.

Операторы, такие как or, and, eq, и другие можно использовать в выражениях так же, как в выражениях Ruleset Engine.

Для работы с JWT-токенами в запросе можно использовать следующие функции:

• is_jwt_valid(token_configuration_id) возвращает true, если у запроса есть действительный токен согласно конфигурации токена с ID token_configuration_id.
• is_jwt_present(token_configuration_id) возвращает true, если у запроса есть токен, соответствующий конфигурации токена с ID token_configuration_id.

Эти функции доступны только в правилах проверки токенов и недоступны в пользовательских правилах WAF.

Ознакомьтесь со следующими примерами использования, чтобы понять, какую политику безопасности выбрать. В большинстве случаев Cloudflare рекомендует требовать действительный токен для всего API, исключая с помощью селекторов пути, которые используются для получения или обновления токенов.

is_jwt_present("51231d16-01f1-48e3-93f8-91c99e81288e") выражение запускает действие, если в запросе отсутствует JWT.

Это можно сочетать с log действие в правиле проверки токена, чтобы регистрировать запросы, в которых отсутствует заголовок авторизации.

is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") выражение запускает действие, если у запроса отсутствует действительный JWT.

Это можно сочетать с block действие в правиле проверки токена, чтобы блокировать запросы без учетных данных или с недействительными учетными данными.

is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") or is_jwt_valid("fddfc39e-3686-4683-ab23-bf917da6bb43") выражения запускают действие, если у запроса нет хотя бы одного действительного токена.

Это может понадобиться, если нужно разделить JWK между несколькими конфигурациями токенов.

is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") or not is_jwt_present("51231d16-01f1-48e3-93f8-91c99e81288e") выражения запускают действие, если у запроса есть недействительный токен, игнорируя запросы, в которых токены отсутствуют вовсе.

К одной операции может применяться только одно правило проверки токена. Если операция подпадает под несколько правил, действует правило с наивысшим приоритетом.

Вы можете настроить, для каких операций применяется проверка JWT, с помощью selector поле.

Например, следующий селектор применит правило ко всем операциям в v1.example.com и v2.example.com, кроме двух операций на этих хостах:

{
	"include": [
		{
			"host": ["v1.example.com", "v2.example.com"]
		}
	],
	"exclude": [
		{
			"operation_ids": [
				"f9c5615e-fe15-48ce-bec6-cfc1946f1bec", // POST v1.example.com/login
				"56828eae-035a-4396-ba07-51c66d680a04" // POST v2.example.com/login
			]
		}
	]
}

Операции можно включать на уровне хоста, а игнорировать отдельно для каждой операции.

Вы можете использовать POST /zones/{zone_id}/token_validation/rules/preview конечная точка, чтобы увидеть операции, охватываемые этим правилом:

curl --request PUT \
'https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/rules/preview' \
--header 'Content-Type: application/json' \
--data '{
    "include": [
        {
            "host": [
                "v1.example.com",
                "v2.example.com"
            ]
        }
    ],
    "exclude": [
        {
            "operation_ids": [
                "f9c5615e-fe15-48ce-bec6-cfc1946f1bec", // POST v1.example.com/login
                "56828eae-035a-4396-ba07-51c66d680a04"  // POST v2.example.com/login
            ]
        }
    ]
}'

Ответ будет включать все операции в зоне с дополнительным state поле.

state поле может быть ignored, excluded, или included. Включённые операции будут соответствовать указанным вами селекторам хостнеймов. Исключённые операции будут соответствовать ID операций, указанным в селекторе. К игнорируемым относятся операции, которые не соответствуют ничему, указанному в селекторе.

{
	"result": {
		"operations": [
			{
				"operation_id": "ed15fcb6-5a73-41cd-91af-8c61e5bb1cdb",
				"method": "GET",
				"host": "example.com",
				"endpoint": "/api/accounts/{var1}",
				"last_updated": "2023-05-24T14:54:34.806506Z",
				"state": "ignored"
			},
			{
				"operation_id": "e7a582cd-3cfb-4061-ab5b-722e6e42f545",
				"method": "GET",
				"host": "v1.example.com",
				"endpoint": "/api/accounts/{var1}",
				"last_updated": "2023-05-24T14:54:34.806506Z",
				"state": "included"
			},
			{
				"operation_id": "ddd5df5a-795c-40ce-b38c-38e9d7ef9ae8",
				"method": "GET",
				"host": "v2.example.com",
				"endpoint": "/api/accounts/{var1}",
				"last_updated": "2023-05-24T14:54:34.806506Z",
				"state": "included"
			},
			{
				"operation_id": "4d20befb-0120-45d5-9b29-5835fd41b44e",
				"method": "GET",
				"host": "v3.example.com",
				"endpoint": "/api/accounts/{var1}",
				"last_updated": "2023-05-24T14:54:34.806506Z",
				"state": "ignored"
			},
			{
				"operation_id": "f9c5615e-fe15-48ce-bec6-cfc1946f1bec",
				"method": "POST",
				"host": "v1.example.com",
				"endpoint": "/login",
				"last_updated": "2023-05-24T14:54:34.806506Z",
				"state": "excluded"
			},
			{
				"operation_id": "56828eae-035a-4396-ba07-51c66d680a04",
				"method": "POST",
				"host": "v2.example.com",
				"endpoint": "/login",
				"last_updated": "2023-05-24T14:54:34.806506Z",
				"state": "excluded"
			},
			{
				"operation_id": "cf86874c-8d0c-4337-ae14-4e2459b541ac",
				"method": "GET",
				"host": "v3.example.com",
				"endpoint": "login",
				"last_updated": "2023-05-24T14:54:34.806506Z",
				"state": "ignored"
			}
		],
		"total": 7,
		"included": 2,
		"excluded": 2,
		"ignored": 3,
		"selected_hosts": ["v1.example.com", "v2.example.com"],
		"available_hosts": [
			"example.com",
			"v1.example.com",
			"v1.example.com",
			"v3.example.com"
		]
	},
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"page": 1,
		"per_page": 20,
		"count": 20,
		"total_count": 1631
	}
}

Операции с included состояние будет охвачено правилом проверки токена. В ответе также указаны имена хостов операций, включённых в result.selected_hosts и показывает все хосты, используемые всеми операциями зоны в result.available_hosts.

Вы также можете отправить пустой объект в теле запроса:

curl --request PUT \
'https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/rules/preview' \
--header 'Content-Type: application/json' \
--data '{ }'

Ответ покажет все операции зоны и все возможные хосты, которые можно использовать для построения собственного селектора.

В примере ниже показан объект JSON со всей информацией, необходимой для создания правила проверки токена с помощью Cloudflare API.

Замените ID конфигураций токенов и ID операций на те ID, которые существуют в вашей зоне.

[
	{
		"title": "JWT Validation on v1 and v2.example.com",
		"description": "Log requests without a valid authorization header.",
		"action": "log",
		"enabled": true,
		"expression": "is_jwt_valid(\"00170473-ec24-410e-968a-9905cf0a7d03\")",
		"selector": {
			"include": [
				{
					"host": ["v1.example.com", "v2.example.com"]
				}
			],
			"exclude": [
				{
					"operation_ids": [
						"f9c5615e-fe15-48ce-bec6-cfc1946f1bec",
						"56828eae-035a-4396-ba07-51c66d680a04"
					]
				}
			]
		}
	}
]

Используйте cURL или любой другой клиент API, чтобы отправить новую конфигурацию в API Cloudflare и включить проверку JWT. Обязательно замените {zone_id} соответствующим ID зоны и добавьте свой учётные данные для аутентификации заголовок.

Замените ID конфигураций токенов и ID операций на те ID, которые существуют в вашей зоне.

Один запрос может создать сразу несколько правил. Для этого передайте несколько объектов правил в массиве JSON тела запроса.

curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/rules/bulk" \
--header 'Content-Type: application/json' \
--data '[
    {
        "title": "JWT Validation on v1 and v2.example.com",
        "description": "Log requests without a valid authorization header.",
        "action": "log",
        "enabled": true,
        "expression": "is_jwt_valid(\"00170473-ec24-410e-968a-9905cf0a7d03\")",
        "selector": {
            "include": [
                {
                    "host": [
                        "v1.example.com",
                        "v2.example.com"
                    ]
                }
            ],
            "exclude": [
                {
                    "operation_ids": [
                        "f9c5615e-fe15-48ce-bec6-cfc1946f1bec",
                        "56828eae-035a-4396-ba07-51c66d680a04"
                    ]
                }
            ]
        }
    }
]'

Ответ будет представлен в формате Cloudflare v4 конверт ответа, а результат содержит созданные правила. Запишите возвращённый ID для каждого правила: его можно использовать для редактирования или удаления существующего правила.

{
	"result": [
		{
			"id": "5ec7c417-6964-4b24-b82c-a23a7ec8f90c",
			"title": "JWT Validation on v1 and v2.example.com",
			"description": "Log requests without a valid authorization header.",
			"action": "log",
			"enabled": true,
			"expression": "is_jwt_valid(\"00170473-ec24-410e-968a-9905cf0a7d03\")",
			"selector": {
				"include": [
					{
						"host": ["v1.example.com", "v2.example.com"]
					}
				],
				"exclude": [
					{
						"operation_ids": [
							"f9c5615e-fe15-48ce-bec6-cfc1946f1bec",
							"56828eae-035a-4396-ba07-51c66d680a04"
						]
					}
				]
			},
			"created_at": "2023-10-18T12:08:09.575388Z",
			"last_updated": "2023-10-18T12:08:09.575388Z",
			"modified_by": "[email protected]"
		}
	],
	"success": true,
	"errors": [],
	"messages": []
}

Рекомендуется периодически обновлять ключи. Чтобы упростить их обновление, Cloudflare допускает до четырёх ключей на одну конфигурацию. Это позволяет добавить второй, новый ключ к уже существующему. Вы можете начать выпускать JWT только с новым ключом, а старый удалить спустя некоторое время. Кроме того, эта функция позволяет разворачивать тестовые или разрабатываемые ключи наряду с продуктивными.

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

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

Используйте PUT команда для обновления ключей.

curl --request PUT \
'https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/config/{config_id}/credentials' \
--header 'Content-Type: application/json' \
--data '{
    "keys": [
        {
            "kty": "EC",
            "use": "sig",
            "kid": "test",
            "x": "-0LNzBheJPn-Zy6JmanTIUX7xc3jgqU714IQY0oU6mw",
            "y": "KONxBybUcRsJQmtu17jMAHsILSw009AuU3ulfUGv3FI",
            "alg": "ES256"
        },
        {
            "kty": "EC",
            "crv": "P-256",
            "kid": "test-2",
            "x": "iIbPRbOeLzjGPvv7iwmzCOTU03R0xDqbenp2D6GUcWo",
            "y": "tDkEh95PnfWwIXciCtdBBVA7wfghx_egmZ1Zcvu2lWw",
            "alg": "ES256"
        }
    ]
}'

Обязательно замените {zone_id} соответствующим ID зоны и добавьте свой учётные данные для аутентификации заголовок.

Правила проверки токенов можно обновить с помощью PATCH запрос. Один PATCH запрос может обновить несколько правил.

A PATCH запрос задаётся в виде JSON-массива в теле запроса. Каждый элемент этого массива содержит обновления для одного правила, определяемого id.

В следующем примере одно правило обновляется, а другое отключается:

curl --request PATCH \
"https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/rules/bulk"  \
--header "Content-Type: application/json" \
--data '[
    {
        "id": "714d3dd0-cc59-4911-862f-8a27e22353cc",
        "action": "log",
        "title": "updated title"
    },
    {
        "id": "7124f9bc-d6b5-430d-b488-b6bc2892f2fb",
        "enabled": false
    }
]'

Порядок правил можно изменить, задав поле position в PATCH тела запроса.

В этом примере правило 714d3dd0-cc59-4911-862f-8a27e22353cc после правила 7124f9bc-d6b5-430d-b488-b6bc2892f2fb:

curl --request PATCH \
"https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/rules/bulk" \
--header 'Content-Type: application/json' \
--data '[
    {
        "id": "714d3dd0-cc59-4911-862f-8a27e22353cc",
        "position": {
            "after": "7124f9bc-d6b5-430d-b488-b6bc2892f2fb"
        }
    }
]'

В этом примере правило 714d3dd0-cc59-4911-862f-8a27e22353cc до правила 7124f9bc-d6b5-430d-b488-b6bc2892f2fb:

curl --request PATCH \
"https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/rules/bulk" \
--header 'Content-Type: application/json' \
--data '[
    {
        "id": "714d3dd0-cc59-4911-862f-8a27e22353cc",
        "position": {
            "before": "7124f9bc-d6b5-430d-b488-b6bc2892f2fb"
        }
    }
]'

Ниже описан общий процесс обработки входящих запросов при проверке JWT:

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

4. Мы проверяем подлинность JWT, сверяя подпись с помощью выбранного ключа.
5. Если JWT содержит claim EXP (expiration time), выполняется проверка того, что срок действия JWT не истёк.

6. Если JWT содержит claim NBF (not before time), выполняется проверка того, что JWT уже действителен.

7. Cloudflare предоставляет проверенные утверждения в виде http.request.jwt.claims полей. Пользовательские правила WAF могут использовать эти утверждения. Правила проверки токена могут учитывать наличие и действительность токена.

8. События Security Analytics в панели управления Cloudflare для API Shield - Token Validation сервис укажет причины нарушения в Token validation violations раздел события.