API で JWT 検証を設定する

Cloudflare API で JWT 検証を設定します。トークン構成は、Cloudflare が JWT を見つけ、検証する方法を定義します。検証結果に対するアクションは、WAF カスタムルールまたはトークン検証ルールで指定します。

トークン構成

トークン構成は、JSON Web Token（JWT）の検証に使う JSON Web Key Set（JWKS）を定義します。リクエスト内の JWT の場所も定義します。

トークン構成には、次の情報が必要です。

フィールド名	説明	例	備考
`title`	構成の目的をすばやく識別できる、人が読める名前です。	Production JWT configuration	50 文字までです。
`description`	`title` よりも詳しい、人が読める説明です。構成の用途を文書化できます。	この構成は、authorization ヘッダー内の JWT を確認します。	500 文字までです。
`token_sources`	リクエスト上で JWT を探せる場所の一覧です。	`http.request.headers[\"authorization\"][0]` `http.request.cookies[\"Authorization\"][0]`	次の情報を参照してください。
`token_type`	検証するトークンの種類を指定します。	`jwt`	現在サポートしているのは `jwt` のみです。
`credentials`	JWT の検証に使う暗号鍵を記述します。各鍵は JSON Web Key（JWK）である必要があります。	次の例を参照してください。	次の情報を参照してください。

トークンソース

各項目は、文字列に解決される Ruleset Engine の式である必要があります。

現在サポートしているフィールドは、http.request.headers と http.request.cookies です。

トークンソースは最大 4 つまで設定できます。リクエストにこれらのフィールドが複数ある場合、使われるのは 1 つだけです。リクエストトークン先頭の Bearer: 文字列は、自動的に無視されます。

Ruleset Engine フィールドの扱いについては、Ruleset Engine のドキュメントを参照してください。

資格情報

API Shield は、非対称の RSA 鍵と楕円曲線鍵、および対称のハッシュベースメッセージ認証コード（HMAC）鍵に対応しています。

鍵の種類	対応アルゴリズム	要件
RSA	`RS256`、`RS384`、`RS512`、`PS256`、`PS384`、`PS512`	RSA 鍵は 2,048 ビット以上である必要があります。
EC	`ES256`、`ES384`	`ES256` では曲線 `P-256`、`ES384` では曲線 `P-384` を使います。
HMAC	`HS256`、`HS384`、`HS512`	それぞれ 32、48、64 バイト以上の対称シークレットを使います。

各 JWK には alg と kid が必要です。API Shield が正しい鍵を選べるように、JWT ヘッダーにも一致する alg と kid の値が必要です。

すべての JWK に alg を指定してください。指定した値でもデフォルト値でも、実際に使われるアルゴリズムは JWT ヘッダーの alg と一致する必要があります。HMAC 鍵では、常に alg を指定してください。

alg を省略する ID プロバイダーとの互換性のため、alg のない RSA 鍵は RS256 にデフォルト設定されます。RSA 鍵のサイズだけでは、ID プロバイダーが使う署名アルゴリズムは分かりません。別の対応アルゴリズムを使う場合は、alg を明示してください。

HMAC 鍵では、kty を oct にします。k には、パディングなし Base64url でエンコードした生の対称資格情報を設定します。デコード後の資格情報は、アルゴリズムごとの最小長を満たす必要があります。

Cloudflare は、各鍵から不要なフィールドを削除し、サポートしていない鍵は破棄します。

API 呼び出しの出力を確認し、結果の鍵が意図どおりかを検証することを強く推奨します。

トークン構成の JSON オブジェクト

次の例は、Cloudflare API でトークン構成を作成するために必要な情報をすべて含む JSON オブジェクトです。テスト用の JWK を作成する場合は、mkjwk JSON Web Key Generator ↗ を参照してください。

例json

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

対称鍵の例

次の例は、HS256 対称鍵で JWT 検証を設定します。<BASE64URL_ENCODED_SECRET> は、デコード後に 32 バイト以上になる、パディングなし Base64url エンコードの資格情報に置き換えます。

HS256 トークン構成json

{
	"title": "Production HMAC JWT configuration",
	"description": "This configuration checks the JWT in the authorization header.",
	"token_sources": ["http.request.headers[\"authorization\"][0]"],
	"token_type": "jwt",
	"credentials": {
		"keys": [
			{
				"kty": "oct",
				"alg": "HS256",
				"kid": "production-hmac-key",
				"k": "<BASE64URL_ENCODED_SECRET>"
			}
		]
	}
}

レスポンスには kty、alg、kid が含まれますが、k は含まれません。

対称鍵のレスポンスjson

{
	"credentials": {
		"keys": [
			{
				"kty": "oct",
				"alg": "HS256",
				"kid": "production-hmac-key"
			}
		]
	}
}

Cloudflare API でトークン構成を作成する

cURL または他の API クライアントで、新しい構成を Cloudflare の API に送信し、JWT 検証を有効にします。{zone_id} は対象のゾーン ID に置き換え、認証資格情報のヘッダーを追加してください。

cURL の例bash

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 レスポンスエンベロープです。result に作成された構成が含まれます。返された ID を控えてください。JWT クレームフィールドやトークン検証ルールから、このトークン構成を参照できます。

レスポンスの例json

{
	"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 配列にも、デフォルト設定された各鍵に対するメッセージが 1 件ずつ入ります。

デフォルト設定されたアルゴリズムのメッセージ例json

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

実際の資格情報を確認するには、result と messages の両方を見てください。

検証結果に応じてアクションを実行する

トークン構成を作成すると、Cloudflare はゾーン内のすべてのリクエストについて、設定したトークンソースで JWT を探し、見つかったトークンを検証します。検証自体にトークン検証ルールや Endpoint Management のオペレーションは不要です。ルールは、結果に対する Cloudflare のアクションを決めます。

新しいセキュリティポリシーでは、通常は WAF カスタムルールの使用を推奨します。

WAF カスタムルール — 検証済み JWT クレームに基づくゾーン全体のポリシーに使います。カスタムルールは、攻撃スコアなど他のシグナルとクレームを組み合わせできます。エンドポイントを Endpoint Management に登録する必要はありません。
トークン検証ルール — Endpoint Management の特定オペレーションにだけ適用したい場合に使います。これらのルールは is_jwt_valid() と is_jwt_present() に対応しています。カスタムルールでは使えません。

ルール式でカスタムクレームを参照するには、トークン構成 ID とクレーム名を指定して lookup_json_string() などの lookup_json_* 関数を使えます。完全な例は、攻撃スコアに基づき JWT クレームの管理者ユーザーにチャレンジを発行するを参照してください。利用可能なフィールドと標準クレームは、JWT 検証フィールドのリファレンスを参照してください。

トークン検証ルール

トークン検証ルールは、既存のトークン構成と Endpoint Management のオペレーションを使って、セキュリティポリシーを適用します。

トークン検証ルールは、Cloudflare API またはダッシュボードで設定できます。

フィールド名	説明	例	備考
`title`	すばやく識別できる、人が読める名前です。	JWT validation on `v1` and `v2.example.com`	50 文字までです。
`description`	`title` よりも詳しい、人が読める説明です。文書化に役立ちます。	Log requests without a valid `authorization` header.	500 文字までです。
`action`	`expression` を満たさないリクエストに対する Firewall Action です。	`log`	指定できる値: `log` または `block`
`enabled`	ルールを有効または無効にします。	`true`	指定できる値: `true` または `false`
`expression`	ルールのセキュリティポリシーです。	`is_jwt_valid ("00170473-ec24-410e-968a-9905cf0a7d03")`	Cloudflare API でルールを作成するときは、引用符をエスケープしてください。セキュリティポリシーを定義するを参照してください。
`selector`	このルールの対象オペレーションを設定します。		ルールをオペレーションに適用するを参照してください。

セレクター

セレクターは、トークン検証ルールのアクションを Endpoint Management のどのオペレーションに適用するかを制御します。

apex ドメインの特定ホスト名またはサブドメインにだけ適用したい場合は、セレクターにホスト名を指定し、一致するオペレーションを JWT 検証ルールに含めます。

適用対象からエンドポイントを除外する場合は、セレクターにそのエンドポイントのオペレーション ID を指定します。たとえば、JWT を発行または更新するエンドポイントを除外できます。

オペレーション ID は、Endpoint Management を参照するか、Cloudflare API を使って確認します。

セキュリティポリシーを定義する

トークン検証ルールの式は、リクエストが満たすべきセキュリティポリシーを定義します。

たとえば、式 is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") or is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") は、受信リクエストに有効な認証トークンが 1 つもない場合に発動します。

これらの式は Ruleset Engine で使う式に似ていますが、次の違いがあります。

トークン検証ルールのアクションは、式が false と評価されたときに発動します。Ruleset の式とは逆です。
トークン検証ルールでは、トークン構成を参照する専用関数を使えます。

or、and、eq などの演算子は、Ruleset Engine の式と同じように使えます。

リクエスト上の JWT トークンを扱うには、次の関数を使えます。

is_jwt_valid(token_configuration_id) — ID が token_configuration_id のトークン構成に照らして、リクエストに有効なトークンがある場合に true を返します。
is_jwt_present(token_configuration_id) — ID が token_configuration_id のトークン構成どおりに、リクエストにトークンがある場合に true を返します。

これらの関数はトークン検証ルールでのみ使えます。WAF カスタムルールでは使えません。

よくあるユースケース

どのセキュリティポリシーを使うかは、次の例を参考にしてください。ほとんどの場合、API 全体で有効なトークンを必須にし、トークンの発行や更新に使うパスはセレクターで除外することを推奨します。

トークンを必須にする

is_jwt_present("51231d16-01f1-48e3-93f8-91c99e81288e") の式は、リクエストに JWT がない場合にアクションを発動します。

トークン検証ルールの log アクションと組み合わせると、認証ヘッダーがないリクエストをログに残せます。

有効なトークンを必須にする

is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") の式は、リクエストに有効な JWT がない場合にアクションを発動します。

トークン検証ルールの block アクションと組み合わせると、資格情報がない、または無効なリクエストをブロックできます。

2 つのトークンのうち少なくとも 1 つを必須にする

is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") or is_jwt_valid("fddfc39e-3686-4683-ab23-bf917da6bb43") の式は、リクエストに有効なトークンが 1 つもない場合にアクションを発動します。

JWK を複数のトークン構成に分ける必要がある場合に使います。

有効なトークンを必須にするが、トークンのないリクエストは無視する

is_jwt_valid("51231d16-01f1-48e3-93f8-91c99e81288e") or not is_jwt_present("51231d16-01f1-48e3-93f8-91c99e81288e") の式は、無効なトークンがある場合にアクションを発動します。トークンのないリクエストは無視します。

ルールをオペレーションに適用する

1 つのオペレーションに適用できるトークン検証ルールは 1 つだけです。複数のルールが対象になる場合は、優先度が最も高いルールが有効になります。

JWT 検証を適用するオペレーションは、selector フィールドで設定できます。

たとえば、次のセレクターは v1.example.com と v2.example.com のすべてのオペレーションにルールを適用します。ただし、これらのホスト上の 2 つのオペレーションは除外します。

セレクターの例json

{
	"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 の例bash

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 のいずれかです。included のオペレーションは、指定したホスト名セレクターに一致します。excluded のオペレーションは、セレクターで指定したオペレーション ID に一致します。ignored のオペレーションは、セレクターの指定に何も一致しません。

結果json

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

state が included のオペレーションは、トークン検証ルールの対象です。レスポンスの result.selected_hosts には対象オペレーションのホスト名が、result.available_hosts にはゾーンの全オペレーションが使うホスト名が入ります。

リクエスト本文に空のオブジェクトを送ることもできます。

cURL の例bash

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 でトークン検証ルールを作成するために必要な情報をすべて含む JSON オブジェクトです。

トークン構成 ID とオペレーション ID は、ゾーンに存在する ID に置き換えてください。

トークン検証ルールの JSON 例json

[
	{
		"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 API でトークン検証ルールを作成する

トークン構成 ID とオペレーション ID は、ゾーンに存在する ID に置き換えてください。

1 回のリクエストで複数のルールを作成できます。その場合は、リクエスト本文の JSON 配列に複数のルールオブジェクトを渡します。

cURL の例bash

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 レスポンスエンベロープです。result に作成されたルールが含まれます。各ルールの返された ID を控えてください。既存ルールの編集や削除に使えます。

結果json

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

メンテナンス

トークン構成を更新する

鍵は定期的にローテーションすることを推奨します。新しい鍵を追加し、その鍵で JWT の発行を始め、古い鍵を削除できます。

鍵の更新時の入力は、構成作成時に credentials で初期鍵を渡したときと同じです。JWK である必要があります。

資格情報の更新は、構成作成時と同じアルゴリズム互換性の動作を使います。レスポンスには正規化された資格情報と、デフォルト設定された各アルゴリズムのメッセージが含まれます。

鍵セット全体を置き換えるには PUT を使います。PUT リクエスト内のすべての対称鍵に k が必要です。リクエストから省略した鍵は削除されます。

cURL の例bash

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 を使います。Cloudflare は alg と kid で既存の鍵を照合します。

一致する対称鍵で資格情報を維持する場合は、k を省略します。
資格情報をローテーションする場合は、新しい k を含めます。
まだ存在しない対称鍵を追加する場合は、k を含めます。
構成から鍵を削除する場合は、keys からその鍵を省略します。
k に null を設定しないでください。

次の例は、production-hmac-key の資格情報を維持しつつ、EC 鍵を追加します。

対称資格情報を維持するbash

curl --request PATCH \
'https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/config/{config_id}/credentials' \
--header 'Content-Type: application/json' \
--data '{
    "keys": [
        {
            "kty": "oct",
            "alg": "HS256",
            "kid": "production-hmac-key"
        },
        {
            "kty": "EC",
            "alg": "ES256",
            "crv": "P-256",
            "kid": "production-ec-key",
            "x": "<BASE64URL_ENCODED_X_COORDINATE>",
            "y": "<BASE64URL_ENCODED_Y_COORDINATE>"
        }
    ]
}'

次の例は、既存 HMAC 鍵の資格情報をローテーションします。

対称資格情報をローテーションするbash

curl --request PATCH \
'https://api.cloudflare.com/client/v4/zones/{zone_id}/token_validation/config/{config_id}/credentials' \
--header 'Content-Type: application/json' \
--data '{
    "keys": [
        {
            "kty": "oct",
            "alg": "HS256",
            "kid": "production-hmac-key",
            "k": "<NEW_BASE64URL_ENCODED_SECRET>"
        }
    ]
}'

トークン検証ルールを更新する

トークン検証ルールは PATCH リクエストで更新できます。1 回の PATCH で複数のルールを更新できます。

PATCH リクエストは、リクエスト本文の JSON 配列で指定します。配列の各項目は、id で識別する 1 つのルールの更新です。

次の例は、1 つのルールを更新し、もう 1 つを無効にします。

cURL の例bash

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

PATCH 本文の position フィールドで、ルールの順序を変更できます。

次の例は、ルール 714d3dd0-cc59-4911-862f-8a27e22353cc をルール 7124f9bc-d6b5-430d-b488-b6bc2892f2fb の後ろに置きます。

cURL の例bash

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 の例bash

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 検証の処理

受信リクエストに対する JWT 検証の処理概要です。

構成に従って、受信リクエストから JWT を抽出します。
JWT をデコードし、ヘッダーの KID クレームを探します。
KID と ALG クレームを使い、渡された鍵の一覧から正しい鍵を探します。

選択した鍵で署名を確認し、JWT の真正性を検証します。
JWT に EXP クレーム（有効期限）がある場合は、期限切れでないことを検証します。

JWT に NBF クレーム（有効開始時刻）がある場合は、すでに有効になっていることを検証します。

Cloudflare は、検証済みクレームを http.request.jwt.claims フィールドとして公開します。WAF カスタムルールはこれらのクレームに応じてアクションできます。トークン検証ルールは、トークンの有無と妥当性に応じてアクションできます。
Cloudflare ダッシュボードの Security Analytics で、API Shield - Token Validation サービスのイベントは、イベントの Token validation violations セクションに違反理由を表示します。