Generate JWT (jwt-generate)

IBM® API Connect の Generate JWT セキュリティー・ポリシーは、JSON Web トークン (JWT) を生成するために使用します。

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

概要

JSON Web トークン (JWT) は、2 つのパーティー間で転送されるクレームを表すための、コンパクトで、URL セーフな手段です。Generate JWT ポリシーは、クレームを生成することを可能にし、それらのクレームが JSON Web 署名 (JWS) 構造のペイロードとして、または JSON Web 暗号化 (JWE) 構造のプレーン・テキストとして使用されるかどうか構成することを可能にします。JWS と JWE の両方の暗号資料を指定することで、ネストされた JWT が生成されます。この JWT は、デジタル署名され、暗号化もされています。その後、JWT はベアラー・トークンとして許可ヘッダーに割り当てられるか (デフォルト・オプション)、JSON Web トークン (JWT) プロパティー内のランタイム変数に割り当てられます (指定した場合)。

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

REST
SOAP

注:

アルゴリズム・タイプが HS256、HS384、および HS512 の場合、参照される暗号オブジェクトは共有秘密鍵でなければなりません。
アルゴリズム・タイプが RS256、RS384、RS512、ES256、ES384、および ES512 の場合、参照される暗号オブジェクトは暗号鍵 (秘密鍵) でなければなりません。
暗号資料は、JSON Web Key (JWK) を介して提供できます。
暗号オブジェクトと 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. Generate JWT ポリシーのプロパティー
プロパティー・ラベル	プロパティー名	必須	説明	データ型
タイトル	title	いいえ	ポリシーのタイトル。デフォルト値は、`jwt-generate` です。	ストリング
説明	description	いいえ	ポリシーの説明。	ストリング
JSON Web トークン (JWT)	jwt	いいえ	生成された JWT を格納するためのランタイム変数。デフォルト値は、`generated.jwt` です。ただし、設定しない場合、生成された JWT はベアラー・トークンとして許可ヘッダーに書き込まれます。	ストリング
JWT ID クレーム	jti-claim	いいえ	JWT ID (jti) クレームを JWT に追加するかどうかを指定します。選択した場合、プロパティーが `true` に設定され、UUID が生成されて JTI クレーム値として設定されます。	ブール
Issuer クレーム	iss-claim	はい	Issuer (iss) クレーム・ストリングの取得元となるランタイム変数。このクレームは、JWT を発行したプリンシパルを表しています。デフォルト値は、`iss.claim` です。	ストリング
Subject クレーム	sub-claim	いいえ	Subject (sub) クレーム・ストリングの取得元となるランタイム変数。	ストリング
Audience クレーム	aud-claim	いいえ	Audience (aud) クレーム・ストリングの取得元となるランタイム変数。複数の変数を設定する場合は、コンマ区切りのストリングを使用します。	ストリング
有効期間	exp-claim	はい	JWT が有効とみなされる期間として、現在の日時に追加される時間の長さ (秒)。デフォルト値は `3600` です。	整数
プライベート・クレーム	private-claims	いいえ	一連の有効な JSON クレームの取得元となるランタイム変数。これらのクレームは、前に指定した任意の一連のクレームに追加されます。	ストリング
署名用 JWK 変数名	jws-jwk	いいえ	JWT に署名するために使用される JWK を含むランタイム変数。¹	ストリング
暗号アルゴリズム	jws-alg	いいえ	使用する暗号アルゴリズム。有効な値は次のとおりです。 HS256 HS384 HS512 RS256 RS384 RS512 ES256 ES384 ES512 なし	ストリング
署名用暗号オブジェクト	jws-crypto	いいえ	JWT に署名するために使用する暗号オブジェクト。¹	ストリング
暗号化アルゴリズム	jwe-enc	いいえ	使用する暗号化アルゴリズム。有効な値は次のとおりです。 A128CBC-HS256 A192CBC-HS384 A256CBC-HS512	ストリング
暗号化用 JWK 変数名	jwe-jwk	いいえ	JWT を暗号化するために使用する JWK を格納するランタイム変数。	ストリング
鍵暗号化アルゴリズム	jwe-alg	いいえ	使用する鍵暗号化アルゴリズム。有効な値は次のとおりです。 RSA1_5 RSA-OAEP RSA-OAEP-256 dir A128KW A192KW A256KW	ストリング
暗号化用暗号オブジェクト	jwe-crypto	いいえ	クレームを暗号化するために使用する暗号オブジェクト。	ストリング

例

- jwt-generate:
    title: jwt-generate
    iss-claim: iss.claim
    exp-claim: 3600
    jwt: generated.jwt
    jti-claim: true
    sub-claim: sub.claim
    aud-claim: aud.claim
    private-claims: private.claims
    jws-jwk: jws.jwk
    jws-alg: HS256
    jws-crypto: jwsCryptoObjectName
    jwe-enc: A128CBC-HS256
    jwe-jwk: jwe.jwk
    jwe-alg: A128KW
    jwe-crypto: jweCryptoObjectName

エラー

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

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

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

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

最終更新: 2017 年 10 月 31 日