JWT 検証ポリシー

ポリシー名

JWT 検証

概要

JWT トークンを検証する

カテゴリ

セキュリティ

使用可能な最小 Flex Gateway バージョン

v1.0.0

返される状況コード

400 - トークンが要求で提供されなかった。

401

署名が検証されなかった、または無効である。

必要ないくつかのクレームがない、またはクレームの検証に失敗した。

トークンの解析に失敗した。

概要

JSON Web Token (JWT) は、2 者間で転送されるクレームを表す URL セキュアな方法です。JWT のクレームは、JSON Web Signature (JWS) のペイロードまたはプレーンテキストの JSON Web Encryption (JWE) 構造として使用される JSON オブジェクトとしてエンコードされます。これにより、クレームはデジタル署名したり、メッセージ認証コード (MAC) で整合性を保護したりできます。トークンは署名されるので、その情報と情報源を信頼できます。

JWT 検証ポリシーは、トークンの署名を検証し、JWS 形式の JWT を使用してすべての受信要求のクレームの値をアサートします。このポリシーでは、JWE を使用する JWT は検証されません。

ポリシーのパラメーターの設定

Flex Gateway のローカルモード

ローカルモードでは、宣言型の設定ファイルを使用して JWT 検証ポリシーを API に適用します。以下のポリシー定義とパラメーターの表を参照してください。

- policyRef:
    name: jwt-validation-flex
  config:
パラメーター 必須または省略可能 デフォルト値 説明

signingMethod

省略可能

rsa

キーの署名方式を含む文字列。サポートされている値: rsa​、​hmac​、​es​、​none

signingKeyLength

省略可能

256

キーの長さを示す数値

textKey

省略可能

your-(256|384|512)-bit-secret/your-public-pem-certificate

jwtOrigin

省略可能

httpBearerAuthenticationHeader

jwtKeyOrigin

省略可能

text

jwksUrl

省略可能

jwksServiceTimeToLive

省略可能

60

jwksServiceConnectionTimeout

省略可能

10000

validateAudClaim

省略可能

false

mandatoryAudClaim

省略可能

false

mandatoryNbfClaim

省略可能

false

mandatoryExpClaim

省略可能

false

supportedAudiences

省略可能

空の文字列

validateCustomClaim

省略可能

false

mandatoryCustomClaims

省略可能

空の配列

nonMandatoryCustomClaims

省略可能

空の配列

jwtExpression

省略可能

#[attributes.headers['jwt']]

skipClientIdValidation

必須

true

このパラメーターはローカルモードで ​true​ に設定する必要があります。

clientIdExpression

省略可能

#[vars.claimSet.client_id]

Flex Gateway の接続モード

パラメーターの設定

UI を使用してポリシーを API に適用する場合は、以下のパラメーターを設定できます。

要素 説明

JWT Origin (元の JWT)

要求のどこから JWT が抽出されるのかを指定します。 * HTTP ベアラー認証ヘッダー * カスタム式

この項目を ​HTTP Bearer Authentication Header​ に設定すると、JWT はベアラーと想定されます。
この項目を ​Custom Expression​ に設定する場合、トークンを返す DataWeave 式を指定します。

Token Expression (トークン式)

[JWT Origin (元の JWT)] を ​Custom Expression​ に設定した場合は、JWT を返す DataWeave 式をここに入力します。

#[attributes.headers['jwt']]
この式は、​jwt​ というヘッダー内の JWT を検索します。

JWT Signing Method (JWT 署名方法)

受信 JWT に期待される署名方法を指定します。JWT の署名方法が異なっている場合、ポリシーはトークンを拒否します。

RSA、HMAC、ES、None

JWT Signing Key Length (JWT 署名キーの長さ)

署名方法で使用されるキーの長さ (HMAC アルゴリズムの場合) またはアルゴリズム (RSA の場合) を指定します。
[JWT Signing Method (JWT 署名方法)] で ​[None (なし)]​ を選択した場合は、この項目を無視します。

256、384、512。ES メソッドの場合、Flex Gateway は 256 キーの長さのみをサポートします。

JWT Key Origin (元の JWT キー)

署名検証用のキーの取得元を指定します。
[Text (テキスト)]​ オプションを選択するか、​JWKS​ から取得することで、ポリシーのキーを提供できます。
[JWT Signing Method (JWT 署名方法)] で ​[None (なし)]​ を選択した場合は、この項目を無視します。

JWT Key (JWT キー)

この項目は、[JWT Key Origin (元の JWT キー)] で ​[Text (テキスト)]​ を選択した場合に表示されます。
この項目を使用して、トークンの署名を確認するために使用するキーを提供します。
[JWT Signing Method (JWT 署名方法)] で ​[None (なし)]​ を選択した場合は、この項目を無視します。

HMAC の場合は 32、48、または 64 文字の文字列の共有シークレット、ES の場合は 32 文字の文字列の共有シークレット、RSA の場合はヘッダーとフッターのない PEM 公開キーを入力します。

JWKS URL

この項目は、[JWT Key Origin (元の JWT キー)] で ​[JWKS]​ を選択した場合に表示されます。
[JWT Signing Method (JWT 署名方法)] で ​[None (なし)]​ を選択した場合は、この項目を無視します。

JWKS サーバーの URL。

JWKS Caching Time To Live (JWKS キャッシュの存続時間)

JKWS が有効な時間 (分)。JKWS の有効期限が切れると、ポリシーによってもう一度取得されます。デフォルト値は 60 分です。
[JWT Signing Method (JWT 署名方法)] で ​[None (なし)]​ を選択した場合は、この項目を無視します。

この項目の入力値は、ポリシーで JWKS が有効とみなされる時間 (分) です。

JWKS サービス接続タイムアウト (ミリ秒)。

アクセストークン検証エンドポイントを認証するときに、応答を待機する最大時間 (ミリ秒単位) を設定します。
デフォルト値は 10 秒です。

Skip Client ID Validation (クライアント ID 検証をスキップ)

この項目をオンにすると、JWT から抽出したクライアント ID が API の有効なクライアントアプリケーションと一致することの確認はされません。

Client ID Expression (クライアント ID 式)

[Skip Client ID Validation (クライアント ID 検証をスキップ)] を設定しない場合は、クライアント ID をトークンから抽出する必要があります。

デフォルトでは、この値は Oauth 2.0 トークンエクスチェンジドラフト​で指定されているように、式 ​#[vars.claimSet.client_id]​ を使用して抽出されます。

Validate Audience Claim (Audience クレームの検証)

Audience クレームの有効性を確認する必要があることを示します。​[Audience Claim Mandatory (Audience クレーム必須)]​ を選択して、このクレームを「必須」に設定できます。

Validate Expiration Claim (Expiration クレームの検証)

Expiration クレームの有効性を確認する必要があることを示します。​[Expiration Claim Mandatory (Expiration クレーム必須)]​ を選択して、このクレームを「必須」に設定できます。

Validate Not Before Claim (Not Before クレームの検証)

Not Before クレームの有効性を確認する必要があることを示します。​[Not Before Claim Mandatory (Not Before クレーム必須)]​ を選択すると、このクレームを「必須」に設定できます。

Validate Custom Claim (カスタムクレームの検証)

ポリシーでカスタム検証を使用できるようにします。すべての DataWeave 式が満たされた場合にのみ JWT が有効とみなされます。

ポリシーは、受信 JWT にあるすべてのクレームを含む ​claimSet​ 変数を提供します。次に例を示します。

foo : #[vars.claimSet.foo == 'fooValue']

すべての DataWeave 式がブール値を返す必要があります。返さない場合は必ず式が失敗します。

Anypoint Service Mesh (非 Mule アプリケーション) のパラメーターの設定

Anypoint Service Mesh (非 Mule アプリケーション) の場合、JWT 検証ポリシーを同じ方法で設定しますが、次の違いがあります。

  • ポリシーはクレーム検証の DataWeave 式を受け入れません。

  • 次の表で説明しているように、トークン取得およびクライアント ID 検証パラメーターは異なります。

要素 説明

JWT Origin (元の JWT)

要求のどこから JWT を抽出するかを指定します。

  • jwt Header​: そのヘッダーから JWT を抽出する

  • HTTP Bearer Authentication Header​: ベアラーであると想定される JWT

  • Custom Header​: JWT は入力であると想定されるヘッダーの名前を取得する

Token Header (トークンヘッダー)

[JWT Origin (元の JWT)]​ を ​Custom Header​ に設定した場合は、JWT を含むヘッダーの名前を指定します。

myJwtHeader

Client ID Claim (クライアント ID クレーム)

[Skip Client ID Validation (クライアント ID 検証をスキップ)]​ を設定しない場合、クライアント ID はトークンから抽出されます。

デフォルトでは、この値は ​client_id​ クレームから抽出されます。

ポリシーのしくみ

このポリシーは、このセクションで説明しているように、異なる方法でクレームと署名を検証します。

署名の検証

このポリシーは、ポリシー設定で指定した値に基づいて JWT の署名を検証します。ポリシー設定で指定したアルゴリズムがトークンと一致しない場合や、トークンの署名が無効である場合、すべての JWT がポリシーで拒否されます。アルゴリズムが指定されていない場は、ポリシーは署名済みと未署名のすべてのトークンに一致します。

署名検証がサポートされているアルゴリズムは、次のとおりです。

  • 対称アルゴリズム​ - SHA-256、SHA-384、SHA-512 を使用する HMAC。

  • 非対称アルゴリズム​ - SHA-256、SHA-384、SHA-512 を使用する ES および RSA。

  • なし​ - 署名検証なし。

JWS 構造内のアルゴリズムについての詳細は、 JWA RFC 標準​を参照してください。

クレームの検証

クレーム検証では、ポリシーで受信したトークンを拒否する条件を選択できます。次の登録済みクレーム検証がデフォルトで提供されています。

  • aud:​: Audience (オーディエンス) 検証。定義された値が少なくとも 1 つトークンに含まれていない場合、トークンを拒否しなければならないことを示す。

  • exp:​: Expiration (有効期限) 検証。トークンの日付が検証日より後の場合、トークンを拒否しなければならないことを示す。

  • nbf​: Not before (以降) 検証。検証日時がトークンの日時よりも前の場合、トークンを拒否しなければならないことを示す。

これらの​提供されたクレーム​に加え、検証で使用する他のクレームを指定することもできます。すべてのクレーム、​登録済み​または​カスタム​で、次の詳細を指定する必要があります。

  • 検証するクレームの名前。
    たとえば、トークンの発行者の場合は ​iss​。

  • テストに使用する値。
    リテラル値の検証のみが必要な場合は単純なリテラル値を指定し、より複雑な比較の場合は DataWeave 式を指定できます。

各クレーム検証は必須か必須でないかを定義できます。クレームを必須と定義し、そのクレームが受信 JWT に含まれていない場合、ポリシーはこのトークンを拒否します。クレームを必須でないと定義し、そのクレームが受信 JWT に含まれていない場合、ポリシーはその特定の検証ではトークンを拒否しません。
どちらも、クレームが含まれている場合、ポリシーはトークン値を検証します。検証が失敗すると、JWT は拒否されます。

クレームの伝播

ポリシーが JWT を解析および検証したら、クレームはダウンストリームポリシーに伝播され、認証オブジェクトの ​claims​ プロパティを介して移動します。

クレームの値にアクセスするには、次の Dataweave 2.0 式の ​<claimName>​ をアクセス対象のクレームの名前に置き換えて使用します。

#[authentication.properties.claims.<claimName>]

JWT は下流にも伝播され、次の Dataweave 2.0 式でアクセスできます。

#[authentication.properties.jwt]

再試行メカニズム

[JWT Key Origin (元の JWT キー)] として [JSON Web Key Set (JWKS)] を選択した場合、ポリシーは再試行メカニズムを使用して、失敗した JWKS フェッチを処理します。キャッシュされた JWKS が期限切れになるか存在せず、新しい要求が開始されるたびに、要求は JWKS サービスに送信されます。要求が失敗した場合、新しい JWKS が取得されて再度キャッシュされるまで、エクスポネンシャルバックオフ遅延のある一連の非同期要求が JWKS サービスに送信されます。

再キャッシュが完了するまで、期限切れの JWKS を使用して要求が処理され、要求が見つからない場合は ​503​ エラーが返されます。期限切れの JWKS を使用すると、前の要求が失敗した場合でも、今後の要求にキャッシュされた値を適用できます。

ポリシーと互換性がある PEM 公開キーを取得する

サポートされていない形式の既存の RSA キーを使用する場合、まずキーを PEM 公開キーに変換します。JWT ポリシーは、PEM 形式の公開 RSA キーを使用します。

タスクの前提条件

既存のキーを変換する前に次の作業を行います。

  1. public.pem​ キーを取得します。

  2. キーをポリシー設定に貼り付ける前に、​-----BEGIN PUBLIC KEY-----​ ヘッダーと ​-----END PUBLIC KEY-----​ フッターを削除します。

次の表に、現在の形式に基づいて既存のキーを変換する手順を示します。

開始点 手順

以前の証明書なし

  1. 非公開 RSA キーを生成します。 ​openssl genrsa -out key.pem 2048

  2. 生成された非公開キー ​key.pem​ から、公開キーを抽出します。 ​openssl rsa -in key.pem -outform PEM -pubout -out public.pem

  3. 公開キーはファイル public.pem 内に含まれます。

PEM 証明書

  1. PEM 証明書から公開キーを抽出します。​openssl x509 -inform pem -in cert.pem -pubkey -noout > public.pem

  2. 公開キーはファイル public.pem 内に含まれます。

DER 証明書

  1. DER 証明書から公開キーを抽出します。​openssl x509 -inform der -in cert.crt -pubkey -noout > public.pem

  2. 公開キーはファイル public.pem 内に含まれます。

JWKS の x5c 項目

  1. チェーンから最初の証明書をコピーしてデコードします。echo <certificateString> | base64 -D > cert.crt​ (​<certificateString> をコピーした値に置き換える)

  2. DER 証明書から公開キーを抽出します。​openssl x509 -inform der -in cert.crt -pubkey -noout > public.pem

  3. 公開キーはファイル public.pem 内に含まれます。