JWT 検証ポリシー

ポリシー名

JWT 検証

概要

JWT トークンを検証する

カテゴリ

セキュリティ

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

4.1.0

返される状況コード

400

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

401

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

署名を検証できなかった、または無効である。

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

403

クライアント ID 検証が失敗した。

502

JWKS を使用できない場合。

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

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

ポリシーのしくみ

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

署名の検証

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

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

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

  • 非対称アルゴリズム​ - SHA-256、SHA-384、SHA-512 を使用する 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]

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

UI からポリシーを API に適用するときに、以下のパラメータが表示されます。

要素 説明

JWT Origin (元の JWT)

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

[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、None (なし)

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

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

256、384、512

JWT Key Origin (元の JWT キー)

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

JWT Key (JWT キー)

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

選択した JWT 署名方法が HMAC の場合は 32、48、または 64 文字の共有シークレット。RSA を選択した場合はヘッダーとフッターのない PEM 公開キー。

JWKS URL

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

JWKS サーバの URL。

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

署名検証用の公開キーを含む JWKS サーバの URL。
[JWT Signing Method (JWT 署名方法)] で [None (なし)]​ を選択した場合は、この項目を無視します。

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

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 式がブール値を返す必要があります。返さない場合は必ず式が失敗します。

ポリシーと互換性がある 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 内に含まれます。

Was this article helpful?

💙 Thanks for your feedback!