JWT Auth plugin

JWT Auth plugin（技術名 jwt-auth、Authentication グループ）は、JSON Web Token（JWT）で Route と Service を保護します。plugin は request からトークンを取り出し、request がバックエンドに進む前に検証します。

JWT のフローには 2 つの要素が必要です。

要素	役割	設定場所
Consumer の JWT Credential	ID とトークンの署名鍵（Key、Algorithm、Secret / Public Key）。	JWT Credential の管理
Route / Service の JWT Auth plugin	API Gateway が request からトークンを取り出して検証する場所。	このページ

ユースケース

• JWT を発行されたアプリケーションやパートナーだけに API の呼び出しを許可する。
• Rate Limiting plugin と組み合わせて、Consumer ごとの request 数を制限する。

警告

先に JWT Credential を持つ Consumer を作成してください。作成していないと、plugin を有効にした時点で有効なトークンがないため、Route / Service へのすべての request が拒否されます。

JWT Auth plugin を作成する

JWT Auth plugin を作成するには、次の手順を実行します。

1. 左側のメニューで API Gateway → Plugin を選択し、右上で API Gateway を選択して New plugin をクリックし、Add plugin ポップアップで JWT Auth を選択します。Route / Service の Plugins タブから追加することもできます。Plugin の追加を参照してください。

2. Basic Information セクションで Display Name を入力します。Description には Verify and authenticate JSON Web Tokens. が入力済みで、変更できます。Basic Informationを参照してください。

3. Configuration セクションを選択します。フォームには必須の属性が 1 つ表示されます。

属性	必須	説明
header	Y	request で JWT を運ぶ HTTP ヘッダーの名前です。デフォルトは Authorization です。

必要に応じて、Attribute (N) をクリックして他の属性を追加します。

属性	必須	説明
query	N	JWT を運ぶクエリパラメーターの名前で、header より優先度が低くなります。デフォルトは jwt です。
cookie	N	JWT を運ぶ cookie の名前で、query より優先度が低くなります。デフォルトは jwt です。
hide_credentials	N	オンにすると、API Gateway は JWT を運ぶ header / query / cookie をバックエンドに渡しません。デフォルトは false です。
key_claim_name	N	正しい Credential / Consumer を見つけるために使う JWT ペイロードのクレームです。クレームの値は JWT Credential の Key と一致する必要があります。デフォルトは iss です。
claims_to_verify	N	有効期間を確認するクレームです: exp、nbf。デフォルトは exp です。
maximum_expiration	N	許可するトークンの最大有効期間（秒）です。0 は無制限を意味します。デフォルトは 0 です。
anonymous	N	認証に失敗した場合でもアクセスを許可するために使う匿名の Consumer です。デフォルトは空です。
run_on_preflight	N	プリフライトの OPTIONS request（CORS）でも plugin を実行します。デフォルトは false です。
use_jwks	N	JWT Credential の Secret / Public Key の代わりに、Identity Provider の JSON Web Key Set（JWKS）を使って署名を検証します。デフォルトは false です。

たとえば key_claim_name を追加すると、フォームと JSON にこの属性が値 iss で表示されます。

4. Scope セクションを選択し、Global または Scoped を選んで、保護する Route / Service を割り当てます。Scopeを参照してください。

5. Create をクリックします。Plugin created successfully というメッセージが表示され、選択した範囲に対応する Applied to 列とともに JWT Auth plugin が一覧に表示されます。

設定例

デフォルトの設定で、Authorization ヘッダーからのみトークンを取り出します。

{
  "header": "Authorization"
}

トークン内の iss クレームで Consumer を見つけます。

{
  "header": "Authorization",
  "key_claim_name": "iss"
}

Authorization ヘッダーからトークンを取り出し、トークンを運ぶヘッダーをバックエンドに渡しません。

{
  "header": "Authorization",
  "hide_credentials": true
}

exp に加えて nbf クレームも確認します（まだ有効になっていないトークンを拒否します）。

{
  "header": "Authorization",
  "claims_to_verify": "exp,nbf"
}

クライアントがクエリパラメーターや cookie でトークンを送れるようにし（ヘッダーを設定できない埋め込み Web ページなど）、有効期間が 1 時間を超えるトークンを拒否します。

{
  "header": "Authorization",
  "query": "jwt",
  "cookie": "jwt",
  "maximum_expiration": "3600"
}

JWT Credential で宣言した Secret / Public Key の代わりに、Identity Provider の JWKS を使って署名を検証します。

{
  "header": "Authorization",
  "use_jwks": true,
  "run_on_preflight": false
}

ヒント

Route で CORS を使う場合は、run_on_preflight を false のままにしてください。ブラウザーはプリフライトの OPTIONS request を Authorization ヘッダーなしで送信します。true に設定すると、実際の request のトークンが有効でも、プリフライトが 401 になり、ブラウザーからの API 呼び出しが失敗します。

動作を確認する

plugin を作成したら、JWT Credential を持つ Consumer を使ってテスト用のトークンを作成します。

• 保護された Route / Service 経由でトークンなしで API を呼び出します: 401 Unauthorized が返れば、plugin は正しくブロックしています。
• 正しいアルゴリズムと Secret で署名し、key_claim_name で指定したクレームが JWT Credential の Key と一致するトークンを使い、ヘッダー Authorization: Bearer <jwt>（設定した場合は query / cookie）を付けてもう一度呼び出します: 200 が返り、request がバックエンドに届きます。

よくある問題

エラー	原因	対処方法
トークンがあっても 401 になる	トークン内の key_claim_name で指定したクレームが JWT Credential の Key と一致しません	クレームが Key と一致するようにトークンを修正するか、key_claim_name を変更します。
トークンがあっても 401 になる	JWT Credential に保存された Secret とは異なる Secret でトークンが署名されています	正しい Secret でトークンを署名し直します。
トークンがあっても 401 になる	トークンの署名アルゴリズムが JWT Credential の Algorithm と異なります	正しいアルゴリズムでトークンを署名し直します。
ブラウザーからの呼び出しが CORS エラーまたは OPTIONS request の 401 で失敗する	run_on_preflight が true です	run_on_preflight を false に戻します。

次のステップ

• JWT Credential の管理
• Rate Limiting plugin