JWT の検証

「JWT の検証」セキュリティー・ポリシーを使用して、API へのアクセスを許可する前に、要求内の JSON Web Token (JWT) の検証を有効にします。

ゲートウェイのサポート

表 1. このポリシーをサポートするゲートウェイと、対応するポリシーのバージョンを示す表
ゲートウェイ	ポリシーのバージョン
DataPower® Gateway (v5 compatible)	1.0.0
DataPower API Gateway	2.0.0

このトピックでは、アセンブリー・ユーザー・インターフェースでのポリシーの構成方法について説明します。 OpenAPI ソースでのポリシーの構成方法について詳しくは、 jwt-validateを参照してください。

製品情報

JSON Web トークン (JWT) は、2 つのパーティー間で転送されるクレームを表すための、コンパクトで、URL セーフな手段です。「JWT の検証」ポリシーを使用すると、JWT 検証を使用して API へのアクセスを保護できます。例えば、ヘッダーに JWT を含む入力要求が受信されると、「JWT の検証」ポリシーはトークンを抽出し、署名を検証および暗号化解除 (該当する場合) し、クレームを検証します。有効であれば、そのクレームはランタイム変数に入力され (必要な場合、後で使用するため)、API へのアクセスが許可されます。クレームが無効な場合、アクセスは拒否されます。

「JWT の検証」ポリシーで指定されているすべてのクレームが検証されますが、これは必ずしも JWT に含まれているすべてのクレームではありません。 JWT 内のすべてのクレームを妥当性検査する必要はありませんが、「JWT の妥当性検査」ポリシーで指定されたクレームのいずれかが失敗した場合、妥当性検査全体が失敗します。妥当性検査が成功すると、JWT に含まれているクレームの完全なセットが、 Output Claims プロパティーで指定されているランタイム変数に書き込まれます。その結果、必要に応じて、任意の後続のアクションがこのランタイム変数を使用して、JWT に存在したクレーム一式をさらに検証できます。

注:

オリジナル・メッセージが共有秘密鍵で署名された場合は、指定される暗号オブジェクトも共有秘密鍵でなければなりません。
オリジナル・メッセージが秘密鍵で署名された場合は、指定される暗号オブジェクトは暗号証明書 (パブリック証明書) でなければなりません。
暗号資料は、JSON Web Key (JWK) を介して提供できます。
JWK ヘッダー・パラメーターは JWT のヘッダーに含まれ、そのパラメーターはポリシーに指定された JWK または暗号オブジェクトと一致する必要があります。一致しない場合、JWT 検証は失敗します。
暗号オブジェクトと JWK の両方を指定した場合、暗号オブジェクトが JWT の暗号化解除または検証に使用されます。
DataPower API Gateway 上の JWT 検証アクションは、単一の JWK または JWK セットのいずれかを使用して JWT を検証できます。

前提条件

以下の前提条件が適用されます。

IBM® DataPower V7.5 (Application Optimization (AO) オプション付き)。
1つ以上の暗号化オブジェクト（cryptoオブジェクト）を使用している場合は、それらをアプライアンス上の IBM API Connect ドメインに配置する必要があります。 DataPower アプライアンス上に暗号オブジェクトは、JWT コンテンツの暗号化解除と署名の検証に必要な共有秘密鍵またはパブリック証明書を参照する必要があります。
JSON Web Key (JWK) または JWK セットが使用されている場合、ランタイム変数によって参照される必要があります。

プロパティ－

以下の表に、このポリシーのプロパティーをリストします。表には、プロパティーが必須かどうか、入力用の有効な値とデフォルト値、および値のデータ型が示されています。

表 2. JWT ポリシー・プロパティーの検証
プロパティー・ラベル	必須	説明	データ・タイプ
タイトル	はい	ポリシーのタイトル。デフォルト値は `jwt-validate`です。	ストリング
説明	いいえ	ポリシーの説明。	ストリング
JSON Web トークン (JWT)	はい	検証対象の JWT を格納するコンテキストまたはランタイム変数。デフォルト値は、`request.headers.authorization` です。ただし、このプロパティーを設定しない場合、ポリシーはデフォルトで `request.headers.authorization` ロケーションで JWT を検索します。注: 許可ヘッダーの形式は、以下のとおりでなければなりません。 `"Authorization: Bearer jwt-token"` ここで、`jwt-token` は、エンコードされた JWT です。	ストリング
出力クレーム	はい	JWT に含まれていクレーム一式が割り当てられるランタイム変数。デフォルト値は、`decoded.claims` です。	ストリング
Issuer クレーム	いいえ	Issuer (iss) クレームを検証するために使用する Perl Compatible Regular Expressions (PCRE) 。	ストリング
Audience クレーム	いいえ	Audience (aud) クレームを検証するために使用する PCRE。	ストリング
暗号化解除用の暗号オブジェクト	いいえ	クレームをデコードするために使用する暗号オブジェクト (共有鍵または証明書)。^¹	ストリング
暗号化解除用の暗号 JWK 変数名	いいえ	JWT を暗号化解除するために使用する JWK を格納するランタイム変数。^¹	ストリング
検証用暗号オブジェクト	いいえ	署名の検証に使用する暗号オブジェクト (共有鍵または証明書)。^²	ストリング
検証用暗号 JWK 変数名	いいえ	署名を検証するために使用する JWK または JWK セットを格納するランタイム変数。^²	ストリング

例

- jwt-validate:
    version: 1.0.0
    title: jwt-validate
    jwt: request.headers.authorization
    output-claims: decoded.claims
    iss-claim: "'^data.*'"
    aud-claim: "'^id.*'"
    jwe-crypto: jweCryptoObjectName
    jwe-jwk: jwe.jwk
    jws-crypto: jwsCryptoObjectName
    jws-jwk: jws.jwk

エラー

ポリシーの実行中に以下のエラーがスローされることがあります。

RuntimeError - ポリシーの実行中に発生するすべてのエラーをキャプチャーする一般的なエラー。検証が失敗した時、基礎となる JOSE モジュールから受け取った詳細なエラー・メッセージがデフォルトのシステム・ログにエラー・メッセージとして書き込まれます。この詳細なエラー・メッセージは、ランタイム変数 jwt-validate.error-message にも割り当てられるため、catch 経由で取得できます。

キャッチが構成されていない場合、検証エラーが発生すると、 JWTポリシーの検証は HTTP コード500 Invalid-JWT-Validate エラーを返します。基礎となる JOSE モジュールからの詳細なエラー・メッセージは、システム・ログで見つけることができます。

重要: 顧客の 1 人が API で発生した障害をトラブルシューティングしている API 開発者は、ログ・メッセージの正確な内容を顧客に送信する前に、セキュリティー上のリスクを考慮してください。ログ・メッセージから得た情報を基に攻撃される可能性を回避するために、顧客にはメッセージの一般的な情報のみを送信してください。

例については、 jwt-validateを参照してください。

¹ JWK も暗号オブジェクトも、JWT の暗号化解除に必要な暗号データを提供する有効な方法です。ただし、両方のデータ型を指定した場合は、暗号オブジェクトのみが使用されます。 1つ以上の暗号化オブジェクト（cryptoオブジェクト）を使用している場合は、それらをアプライアンス上の IBM API Connect ドメインに配置する必要があります。 DataPower アプライアンス上に暗号オブジェクトは、JWT コンテンツの暗号化解除と署名の検証に必要な共有秘密鍵またはパブリック証明書を参照する必要があります。

² JWK も JWK も JWK も JWK も暗号オブジェクトも JWT の検証に必要な暗号データを提供する有効な方法です。ただし、両方のデータ型を指定した場合は、暗号オブジェクトのみが使用されます。