Flex Gateway新着情報
Governance新着情報
Monitoring API Managerポリシー名 |
JWT 検証 |
|||
概要 |
JWT トークンを検証する |
|||
カテゴリ |
セキュリティ |
|||
使用可能な最小 Mule バージョン |
v4.1.0 |
|||
返される状況コード |
||||
400 - トークンが要求で提供されなかった。
|
JSON Web Token (JWT) は、2 者間で転送されるクレームを表す URL セキュアな方法です。JWT のクレームは、JSON Web Signature (JWS) のペイロードまたはプレーンテキストの JSON Web Encryption (JWE) 構造として使用される JSON オブジェクトとしてエンコードされます。これにより、クレームはデジタル署名したり、メッセージ認証コード (MAC) で整合性を保護したりできます。トークンは署名されるので、その情報と情報源を信頼できます。
JWT 検証ポリシーは、トークンの署名を検証し、JWS 形式の JWT を使用してすべての受信要求のクレームの値をアサートします。このポリシーでは、JWE を使用する JWT は検証されません。
UI からポリシーを API に適用するときに、環境に Mule アプリケーションがあるか非 Mule アプリケーションがあるかに基づいて、パラメーターのリストが表示されます。
Mule アプリケーションの場合、環境に Mule アプリケーションがあるかどうかに基づいて、次のパラメーターが表示されます。
要素 | 説明 | 例 |
---|---|---|
JWT Origin (元の JWT) |
要求のどこから JWT が抽出されるのかを指定します。 * HTTP ベアラー認証ヘッダー * カスタム式 この項目を |
|
Token Expression (トークン式) |
[JWT Origin (元の JWT)] を |
|
JWT Signing Method (JWT 署名方法) |
受信 JWT に期待される署名方法を指定します。JWT の署名方法が異なっている場合、ポリシーはトークンを拒否します。 |
RSA、HMAC、ES、None |
JWT Signing Key Length (JWT 署名キーの長さ) |
署名方法で使用されるキーの長さ (HMAC アルゴリズムの場合) またはアルゴリズム (RSA の場合) を指定します。 |
256、384、512。ES メソッドの場合、Flex Gateway は 256 キーの長さのみをサポートします。 |
JWT Key Origin (元の JWT キー) |
署名検証用のキーの取得元を指定します。 |
|
JWT Key (JWT キー) |
この項目は、[JWT Key Origin (元の JWT キー)] で [Text (テキスト)] を選択した場合に表示されます。 |
HMAC の場合は 32、48、または 64 文字の文字列の共有シークレット、ES の場合は 32 文字の文字列の共有シークレット、RSA の場合はヘッダーとフッターのない PEM 公開キーを入力します。 |
JWKS URL |
この項目は、[JWT Key Origin (元の JWT キー)] で [JWKS] を選択した場合に表示されます。 |
JWKS サーバーの URL。 |
JWKS Caching Time To Live (JWKS キャッシュの存続時間) |
JKWS が有効な時間 (分)。JKWS の有効期限が切れると、ポリシーによってもう一度取得されます。デフォルト値は 60 分です。 |
この項目の入力値は、ポリシーで JWKS が有効とみなされる時間 (分) です。 |
JWKS サービス接続タイムアウト (ミリ秒)。 |
アクセストークン検証エンドポイントを認証するときに、応答を待機する最大時間 (ミリ秒単位) を設定します。 |
|
Skip Client ID Validation (クライアント ID 検証をスキップ) |
この項目をオンにすると、JWT から抽出したクライアント ID が API の有効なクライアントアプリケーションと一致することの確認はされません。 |
|
Client ID Expression (クライアント ID 式) |
[Skip Client ID Validation (クライアント ID 検証をスキップ)] を設定しない場合は、クライアント ID をトークンから抽出する必要があります。 |
デフォルトでは、この値は Oauth 2.0 トークンエクスチェンジドラフトで指定されているように、式 |
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 変数を提供します。次に例を示します。
すべての DataWeave 式がブール値を返す必要があります。返さない場合は必ず式が失敗します。 |
Anypoint Service Mesh (非 Mule アプリケーション) の場合、JWT 検証ポリシーを同じ方法で設定しますが、次の違いがあります。
ポリシーはクレーム検証の DataWeave 式を受け入れません。
次の表で説明しているように、トークン取得およびクライアント ID 検証パラメーターは異なります。
要素 | 説明 | 例 |
---|---|---|
JWT Origin (元の JWT) |
要求のどこから JWT を抽出するかを指定します。
|
|
Token Header (トークンヘッダー) |
[JWT Origin (元の JWT)] を |
|
Client ID Claim (クライアント ID クレーム) |
[Skip Client ID Validation (クライアント ID 検証をスキップ)] を設定しない場合、クライアント 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 を使用すると、前の要求が失敗した場合でも、今後の要求にキャッシュされた値を適用できます。
サポートされていない形式の既存の RSA キーを使用する場合、まずキーを PEM 公開キーに変換します。JWT ポリシーは、PEM 形式の公開 RSA キーを使用します。
タスクの前提条件
既存のキーを変換する前に次の作業を行います。
public.pem
キーを取得します。
キーをポリシー設定に貼り付ける前に、-----BEGIN PUBLIC KEY----- ヘッダーと -----END PUBLIC KEY----- フッターを削除します。
次の表に、現在の形式に基づいて既存のキーを変換する手順を示します。
開始点 | 手順 |
---|---|
以前の証明書なし |
|
PEM 証明書 |
|
DER 証明書 |
|
JWKS の x5c 項目 |
|