JSON Web Token の検証

JSON Web Token（JWT）は、多くの Web アプリケーションで認証の一部として使われます。JWT はユーザーの識別とアクセス権の判定に重要なので、トークンの完全性を保つことが大切です。

API Shield の JWT 検証は、API オリジンに届く前に受信 JWT を暗号学的に検証します。期限切れ、改ざん済み、まだ有効になっていないトークンを検出します。検証結果に対するアクションは、ルールで設定します。

処理の流れ

JWT 検証は 2 つで構成されます。JWT の場所と検証方法を Cloudflare に伝えるトークン設定と、検証結果に対して動作するルールです。

トークン設定を作成すると、Cloudflare はゾーン内のすべてのリクエストを、設定した場所で JWT がないか確認します。JWT が見つかるとトークンを検証し、検証済みクレームを http.request.jwt.claims フィールドで使えるようにします。利用できるフィールドと標準クレームは、JWT 検証フィールドのリファレンスを参照してください。検証自体にルールや Endpoint Management のオペレーションは不要です。結果への対処方法を決めるのがルールです。

トークン検証設定を追加する

Cloudflare ダッシュボードで Security Settings ページを開きます。
Settings を開く ↗
API abuse で絞り込みます。
Token configurations で Configure tokens を選びます。
設定の名前を入力します。
受信リクエスト上で、この設定の JWT を探す場所（ヘッダーや Cookie とその名前など）を選びます。
JWT 発行者の検証鍵（JWKS）をコピーして貼り付けます。非対称公開鍵、または HMAC アルゴリズムで使う対称鍵を指定できます。

非対称アルゴリズムを使う JWT 発行者は、通常、検証用の公開鍵（JWKS）をインターネット上の既知の URL で公開します。HMAC アルゴリズムを使う発行者は、検証側と対称資格情報を共有します。発行者の検証鍵や対称資格情報の入手先がわからない場合は、ID 管理者に問い合わせてください。

対応アルゴリズムと対称鍵の要件は、API で JWT 検証を設定するを参照してください。

ID プロバイダーが JWKS を更新したときに自動で追従するには、Worker を使えます。Worker の設定方法は、Worker で鍵を自動更新するを参照してください。

JWT 検証結果に応じて対処する

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

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

選ぶルールの種類に関係なく、Cloudflare の JWT 検証方法は同じです。

たとえば、ルール式で単純な文字列クレームを参照するには、トークン設定 ID とクレーム名を指定して lookup_json_string() を使います。

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

完全な例は、JWT クレームの管理者ユーザーに対し、attack score に基づいてチャレンジを出すを参照してください。利用できるフィールドの全体は、JWT 検証フィールドのリファレンスを参照してください。

JWT 検証ルールを追加する

JWT 検証ルールは、Endpoint Management のオペレーションを使い、log または block アクションの適用先を制御します。

Cloudflare ダッシュボードで Security rules ページを開きます。
Security rules を開く ↗
API JWT validation rules で Create rule を選びます。
ルールの名前を入力します。
保存済みエンドポイントへのリクエストをこのルールで保護するホスト名を選びます。
JWT 検証ルールの適用から除外したいエンドポイントの選択を外します。
受信リクエストに対応するトークン設定を選びます。
これらのエンドポイントで、トークンの存在を厳密に必須にするかを選びます。
- すべてのクライアントがリクエストに JWT を付けるとは限らない場合があります。その場合は Ignore を選びます。存在する JWT は引き続き検証されます。
- 選んだホスト名とエンドポイントへのリクエストには、すべて JWT が含まれると想定する場合は Mark as non-compliant を選びます。
非準拠リクエストに対するアクションを選びます。たとえば、検証に失敗した JWT（期限切れ、改ざん、不正な署名）や、前の手順で Mark as non-compliant を選んだ場合の JWT 欠落リクエストです。
Save を選びます。

特殊なケース

1 つのリクエストで異なる ID プロバイダーの 2 つの JWT を検証する

1 つのリクエストに異なる 2 つの JWT があり、両方を検証したい場合は、トークン設定を 2 つ作成する必要があります。検証ルールで 2 つの設定を選ぶときは、Validation behavior for multiple configurations で Validate all configurations を選びます。

ある ID プロバイダーから別のプロバイダーへの移行を支える

2 つの異なる ID プロバイダー間で移行する場合は、トークン設定を 2 つと、それぞれに対応する検証ルールを 2 つ作成する必要があります。この構成なら、移行の進捗に応じて検証ルールごとのアクションを変えられます。

`Bearer` プレフィックス付きの JSON Web Token

API Shield は、Bearer プレフィックスの有無に関係なく JSON Web Token を検証します。

ユーザー単位のレート制限（JWT クレーム）

JSON Web Token（JWT）内の任意のクレームに基づいて、リクエストをレート制限できます。例:

aud や sub などの登録済みクレーム
userEmail などのカスタムクレーム。ネストしたカスタムクレーム（user.email）も含みます

JWT クレームの値によるレート制限は、有効な JSON Web Token でのみ動作します。パス上で無効な JSON Web Token をブロックしていない場合、JWT クレームはすべてカウントされ、Point of Presence（PoP）で高トラフィックが検出されるとブロックされることがあります。

ユーザーを一意に識別する JWT クレームをカウントする必要があります。多くのユーザーで同じ値になるクレームを選ぶと、それらのレート制限はまとめてカウントされます。

ユーザーティア単位のレート制限

ウェブサイトやアプリケーションで複数のティアを提供しており、ティアに応じてレート制限を適用したい場合の例:

"aud": "free-tier" の場合、1 分あたり 5 リクエストに制限します。
"aud": "premium-tier" の場合、1 分あたり 50 リクエストに制限します。

次のレート制限ルールの例に従ってください。

Example rule expressiontxt

(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"

`OPTIONS` のプリフライト CORS リクエストを無視する

クロスオリジンリソース共有（CORS）のセキュリティにより、Web ブラウザーは GET（またはほかの動詞）を送る前に、OPTIONS 動詞で API エンドポイントへ「プリフライト」リクエストを送ります。定義上、OPTIONS プリフライトリクエストに資格情報（認証ヘッダーや Cookie）は含まれず、匿名です。

API の正当なクライアントとして Web ブラウザーを想定しており、それらのブラウザーからの OPTIONS リクエストをブロックしたくない場合は、JWT 検証ルールに or http.request.method eq "OPTIONS" を追加することを Cloudflare は推奨します。

提供状況

JWT 検証は、すべての API Shield のお客様が利用できます。API Shield を購入していない Enterprise のお客様は、Cloudflare ダッシュボードで API Shield を非契約サービスとしてプレビュー ↗ するか、アカウントチームに問い合わせてください。

制限事項

JWT 検証が対象にするのは、クライアントリクエストのヘッダーまたは Cookie で送られる JWT だけです。POST 本文で JWT を送る場合は、アカウントチームに問い合わせてください。