Validate JWT (jwt-validate)

Validate JWT セキュリティー・ポリシーは、API へのアクセスを許可する前に、要求内の JSON Web トークン (JWT) の検証を可能にするために使用します。

制約事項: Validate JWT ポリシーは、DataPower® Gateway にのみ使用できます。

概要

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

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

このポリシーを以下の API フローに付加できます。

REST
SOAP

注:

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

前提条件

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

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

プロパティー

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

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

例

- jwt-validate:
    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 経由で取得できます。

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

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

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

最終更新: 2017 年 10 月 31 日