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

Konfigurace validace JWT přes API

Pomocí API Cloudflare nakonfigurujte Ověřování JWT. Konfigurace tokenu určuje, jak Cloudflare vyhledává a ověřuje JWT. Poté pomocí vlastního pravidla WAF nebo pravidla pro ověřování tokenů reagovat na výsledky.

Konfigurace tokenu definuje sadu JSON Web Key Set (JWKS) použitou k ověřování JSON Web Tokenů (JWT). Zároveň určuje, kde Cloudflare v požadavcích hledá JWT.

Konfigurace tokenů vyžadují následující informace:

Každá položka musí být výraz Ruleset Engine, který se vyhodnotí jako řetězec.

Aktuálně podporovaná pole jsou http.request.headers a http.request.cookies.

Můžete nastavit až čtyři zdroje tokenu. Pokud má požadavek nastaveno více než jedno z těchto polí, použije se pouze jedno. Úvodní Bearer: řetězce v tokenech požadavků jsou automaticky ignorovány.

Viz Dokumentace Ruleset Engine kde najdete podrobnosti o práci s poli Ruleset Engine.

API Shield podporuje přihlašovací údaje typu RS256, RS384, RS512, PS256, PS384, PS512, ES256, a ES384. Klíče RSA musí mít alespoň 2048 bitů. Každý JSON web key musí obsahovat pole „KID“, které musí být uvedeno i v hlavičce JWT, aby ho API Shield mohlo párovat.

Uveďte alg hodnotu pro každý JSON web key. Efektivní algoritmus, ať už zadaný, nebo výchozí, musí odpovídat alg hodnotě v hlavičce JWT.

Kvůli kompatibilitě s poskytovateli identity, kteří vynechávají alg, API Shield jako výchozí nastaví klíč RSA bez alg na RS256. Velikost klíče RSA neurčuje, jaký algoritmus podpisu poskytovatel identity používá. Zadejte alg explicitně, pokud poskytovatel identity používá jiný podporovaný algoritmus.

Povolujeme až 4 různé klíče, abychom usnadnili rotaci klíčů.

Cloudflare z každého klíče odstraní všechna nepotřebná pole a zahodí klíče, které nepodporuje.

Důrazně doporučujeme ověřit výstup volání API a zkontrolovat, že výsledné klíče odpovídají očekávání.

Následující příklad ukazuje objekt JSON se všemi informacemi potřebnými k vytvoření konfigurace tokenu pomocí Cloudflare API. Pokud si chcete pro účely testování vytvořit JWK, přečtěte si 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"
			}
		]
	}
}

Pomocí cURL nebo jiného klientského nástroje API odešlete novou konfiguraci do API Cloudflare a povolte tak ověřování JWT. Nezapomeňte nahradit {zone_id} s příslušným ID zóny a přidejte svůj autentizační údaje hlavička.

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"
            }
        ]
    }
}'

Odpověď bude ve formátu Cloudflare v4 response envelope a výsledek obsahuje vytvořenou konfiguraci. Poznamenejte si vrácené ID. Můžete ho použít k odkazování na konfiguraci tokenu v polích JWT claim nebo v pravidlech ověřování tokenu.

{
	"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": []
}

Pokud API Shield doplní vynechaný algoritmus výchozí hodnotou, odpověď obsahuje skutečně použitý algoritmus v result. messages pole navíc obsahuje jednu zprávu pro každý klíč s výchozí hodnotou:

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

Zkontrolujte obě result a messages , abyste potvrdili platné přihlašovací údaje.

Po vytvoření konfigurace tokenu Cloudflare u každého požadavku v zóně zkontroluje nakonfigurované zdroje tokenů a každý nalezený token ověří. K ověření nepotřebujete žádné pravidlo ověření tokenu ani operaci v Endpoint Management. To, jak Cloudflare s výsledky naloží, určují pravidla.

Pro nové bezpečnostní zásady Cloudflare obecně doporučuje používat vlastní pravidla WAF.

• WAF custom rules : tyto použijte pro zásady platné pro celou zónu založené na ověřených nárokech JWT. Vlastní pravidla mohou kombinovat nároky s dalšími signály, například skóre útoku. Koncové body nemusí být ve funkci Endpoint Management.
• Pravidla ověřování tokenu : tyto použijte, pokud se má vynucování vztahovat jen na konkrétní operace ve funkci Endpoint Management. Tato pravidla podporují is_jwt_valid() a is_jwt_present() funkce, které nejsou ve vlastních pravidlech k dispozici.

Chcete-li odkázat na vlastní claim ve výrazu pravidla, můžete použít lookup_json_* funkce jako lookup_json_string() s ID konfigurace tokenu a názvem claimu. Úplný příklad najdete v Vydat výzvu pro administrátora v nároku (claim) JWT na základě skóre útoku. Přehled všech dostupných polí a standardních nároků najdete v Pole pro ověřování JWT reference.

Pravidla ověřování tokenu vynucují bezpečnostní politiku pomocí existujících konfigurací tokenu a operací v Endpoint Management.

Pravidla ověřování tokenu lze konfigurovat pomocí Cloudflare API nebo dashboard.

Selektory určují, na které operace ze sekce Endpoint Management Cloudflare uplatní akci pravidla ověřování tokenu.

Pokud potřebujete vynucování jen u konkrétních hostname nebo subdomén své apex domény, použijte hostname v selektoru, abyste do pravidla ověřování JWT zahrnuli odpovídající operace.

Pokud potřebujete vyloučit endpointy z vynucování, použijte v selektoru ID operace daného endpointu. Můžete tak například vyloučit endpoint, který vydává nebo obnovuje JWT.

Chcete-li najít operation ID, přečtěte si Endpoint Management nebo použijte Cloudflare API.

Výraz pravidla ověřování tokenu definuje bezpečnostní politiku, kterou musí požadavek splňovat.

Například výraz is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") or is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") se aktivuje, pokud příchozí požadavek nemá alespoň jeden platný autentizační token.

Tyto výrazy jsou podobné výrazy používané v Ruleset Engine, s několika klíčovými rozdíly:

• Akce pravidla ověřování tokenu se spustí, pokud výraz vyhodnotí false, na rozdíl od výrazů Ruleset.
• Pravidla ověřování tokenu mohou používat speciální funkce, které odkazují na konfigurace tokenu.

Operátory jako or, and, eq, a další lze ve výrazech používat stejně jako ve výrazech používaných v Ruleset Engine.

K práci s tokeny JWT v požadavku lze použít následující funkce:

• is_jwt_valid(token_configuration_id) : Vrátí hodnotu true, pokud požadavek obsahuje platný token podle konfigurace tokenu s ID token_configuration_id.
• is_jwt_present(token_configuration_id) : Vrátí hodnotu true, pokud požadavek obsahuje token nakonfigurovaný v konfiguraci tokenu s ID token_configuration_id.

Tyto funkce jsou dostupné pouze v pravidlech ověřování tokenu. Ve vlastních pravidlech WAF nejsou k dispozici.

Následující příklady použití vám pomohou pochopit, jakou zásadu zabezpečení zvolit. Pro většinu případů použití Cloudflare doporučuje vyžadovat platný token napříč celým API a pomocí selektorů vyloučit cesty sloužící k vytváření nebo obnově tokenů.

is_jwt_present("51231d16-01f1-48e3-93f8-91c99e81288e") výraz vyvolá akci, pokud požadavku chybí JWT.

Lze to kombinovat s log akci v pravidle ověřování tokenu, která zaznamenává požadavky bez ověřovací hlavičky.

is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") výraz vyvolá akci, pokud požadavek nemá platný JWT.

Lze to kombinovat s block akci v pravidle ověřování tokenu, která blokuje požadavky bez přihlašovacích údajů nebo s neplatnými přihlašovacími údaji.

is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") or is_jwt_valid("fddfc39e-3686-4683-ab23-bf917da6bb43") výrazy vyvolají akci, pokud požadavek nemá alespoň jeden platný token.

K tomu může dojít, pokud potřebujete rozdělit JWK klíče do více konfigurací tokenu.

is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") or not is_jwt_present("51231d16-01f1-48e3-93f8-91c99e81288e") výrazy vyvolají akci, pokud má požadavek neplatný token, přičemž požadavky zcela bez tokenu ignorují.

Na operaci lze uplatnit jen jedno pravidlo ověřování tokenu. Pokud se na operaci vztahuje více pravidel, uplatní se to s nejvyšší prioritou.

Můžete nastavit, na které operace se vynucuje ověřování JWT, pomocí selector .

Následující selektor například použije pravidlo na všechny operace v v1.example.com a v2.example.com, kromě dvou operací na těchto hostitelích:

{
	"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
			]
		}
	]
}

Operace lze zahrnout na úrovni hostitele a jednotlivě je z tohoto zahrnutí vyloučit.

Můžete použít POST /zones/{zone_id}/token_validation/rules/preview endpoint a zobrazte operace, na které se toto pravidlo vztahuje:

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
            ]
        }
    ]
}'

Odpověď bude obsahovat všechny operace v zóně s dalším state .

state pole může být ignored, excluded, nebo included. Zahrnuté operace odpovídají zadaným selektorům názvu hostitele. Vyloučené operace odpovídají ID operací zadaným v selektoru. Ignorované operace jsou ty, které neodpovídají ničemu zadanému v selektoru.

{
	"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
	}
}

Operace s included stavu bude pokryto pravidlem ověřování tokenu. Odpověď také zobrazuje názvy hostitelů zahrnutých operací ve stavu result.selected_hosts a zobrazuje všechny hostname použité všemi operacemi zóny v result.available_hosts.

V těle požadavku můžete odeslat i prázdný objekt:

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

Odpověď zobrazí všechny operace zóny a všechny možné hostitele, které můžete použít k sestavení vlastního selektoru.

Následující příklad ukazuje objekt JSON se všemi informacemi potřebnými k vytvoření pravidla ověření tokenu pomocí Cloudflare API.

ID konfigurací tokenů a ID operací nahraďte ID, která existují ve vaší zóně.

[
	{
		"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"
					]
				}
			]
		}
	}
]

Pomocí cURL nebo jiného klientského nástroje API odešlete novou konfiguraci do API Cloudflare a povolte tak ověřování JWT. Nezapomeňte nahradit {zone_id} s příslušným ID zóny a přidejte svůj autentizační údaje hlavička.

ID konfigurací tokenů a ID operací nahraďte ID, která existují ve vaší zóně.

Jeden požadavek může vytvořit více pravidel. Stačí předat více objektů pravidel v poli JSON v těle požadavku.

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"
                    ]
                }
            ]
        }
    }
]'

Odpověď bude ve formátu Cloudflare v4 response envelope a výsledek obsahuje vytvořená pravidla. Poznamenejte si vrácené ID pro každé pravidlo, které lze použít k úpravě nebo odstranění existujícího pravidla.

{
	"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": []
}

Osvědčeným postupem je klíče po určité době rotovat. Pro snazší aktualizaci klíčů umožňuje Cloudflare v jedné konfiguraci až čtyři klíče. Díky tomu můžete k již existujícímu klíči přidat druhý, nový klíč. Nové JWT pak můžete začít vydávat pouze pomocí nového klíče a starý klíč po určité době odebrat. Tato funkce navíc umožňuje nasazovat testovací nebo vývojové klíče vedle produkčních.

Vstup pro aktualizaci klíčů je stejný jako při vytváření konfigurace, kde jste počáteční klíče zadali pomocí klíče credentials, a musí jít o JWK.

Aktualizace přihlašovacích údajů využívá stejné chování kompatibility algoritmů jako vytváření konfigurace. Odpověď obsahuje normalizované přihlašovací údaje a zprávu ke každému algoritmu, u kterého byla použita výchozí hodnota.

Použijte PUT příkaz k aktualizaci klíčů.

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"
        }
    ]
}'

Nezapomeňte nahradit {zone_id} s příslušným ID zóny a přidejte svůj autentizační údaje hlavička.

Pravidla ověřování tokenu lze aktualizovat pomocí PATCH požadavek. Jeden PATCH požadavek může aktualizovat více pravidel.

A PATCH požadavek je zadán jako pole JSON v těle požadavku. Každá položka tohoto pole obsahuje aktualizace jednoho pravidla, definované id.

Následující příklad aktualizuje jedno pravidlo a druhé deaktivuje:

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
    }
]'

Pořadí pravidel lze změnit nastavením pole position v PATCH tělo.

Tento příklad umísťuje pravidlo 714d3dd0-cc59-4911-862f-8a27e22353cc po pravidle 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"
        }
    }
]'

Tento příklad umísťuje pravidlo 714d3dd0-cc59-4911-862f-8a27e22353cc před pravidlem 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"
        }
    }
]'

Zde je přehled toho, jak ověřování JWT zpracovává příchozí požadavky:

1. JWT extrahujeme z příchozího požadavku podle nastavené konfigurace.
2. Dekódujeme JWT a v jeho hlavičce vyhledáme nárok KID.
3. Pomocí nároků KID a ALG najdeme správný klíč v seznamu poskytnutých klíčů.

4. Pravost JWT ověřujeme kontrolou podpisu pomocí vybraného klíče.
5. Pokud JWT obsahuje claim EXP (expiration time), ověříme, že platnost JWT ještě nevypršela.

6. Pokud JWT obsahuje claim NBF (not before time), ověříme, že je JWT již platný.

7. Cloudflare zpřístupňuje ověřené claims jako http.request.jwt.claims pole. Vlastní pravidla WAF mohou na tyto claims reagovat. Pravidla pro ověřování tokenů mohou reagovat na přítomnost a platnost tokenu.

8. Události Security Analytics v Cloudflare dashboardu pro API Shield - Token Validation služba vysvětlí důvody porušení v Token validation violations sekce události.