このページは Apigee と Apigee ハイブリッドに適用されます。
Apigee Edge のドキュメントを表示します。
概要
構成可能な一連のクレームを含む署名付き JWS を生成します。生成された JWS はクライアントに返すだけでなく、バックエンド ターゲットに送信するなど、他の方法で使用することもできます。詳細については、JWS ポリシーと JWT ポリシーの概要をご覧ください。
JWS の構成要素、暗号化と署名の方法については、RFC7515 をご覧ください。
このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。
動画
署名付き JWT の生成方法について短い動画をご覧ください。この動画では JWT の生成方法について説明していますが、コンセプトの多くは JWS と同じです。
サンプル
HS256 で署名された JWS を生成する
このサンプル ポリシーでは、HS256 アルゴリズムを使用して署名された JWS を生成します。HS256 では、署名と検証の両方に共有シークレットを利用します。この JWS では、連結されたコンテンツが使用されます。つまり、エンコードされたヘッダー、ペイロード、署名がドットで連結されて最終的な JWS が生成されます。
[header].[payload].[signature]
<Payload> 要素を使用して、エンコードされていない未加工の JWS ペイロードを指定します。この例では、変数にペイロードが含まれています。このポリシー アクションがトリガーされると、Apigee は JWS ヘッダーとペイロードをエンコードし、エンコードされた署名を追加して JWS にデジタル署名します。
次のポリシー構成では、変数 my-payload に含まれるペイロードから JWS を作成し、結果の JWS を変数 output-variable に格納します。
<GenerateJWS name="JWS-Generate-HS256">
<DisplayName>JWS Generate HS256</DisplayName>
<Algorithm>HS256</Algorithm>
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
<SecretKey>
<Value ref="private.secretkey"/>
<Id>1918290</Id>
</SecretKey>
<Payload ref="my-payload"/>
<OutputVariable>output-variable</OutputVariable>
</GenerateJWS>
HS256 署名付き JWT を生成する
この例では、HS256 アルゴリズムで署名された連結コンテンツを含む JWS も生成します。この場合、ペイロードは JSON です。typ ヘッダーを JWT に設定すると、署名付き JWT でもある署名付き JWS が生成されます。（リファレンス）
次のポリシー構成では、変数 json-content に含まれるペイロードから JWS を作成し、結果の JWS を変数 output-variable に格納します。json-content 変数が JSON ペイロードを含み、その JSON ペイロード内のプロパティが JWT に対して有効である場合にのみ、署名付き JWT になります。たとえば、exp プロパティが存在する場合は、プロパティの値は数値である必要があります。aud プロパティが存在する場合は、文字列または文字列の配列である必要があります。このような条件を満たす必要があります。JWT クレームで有効な値については、IETF RFC7519 をご覧ください。
<GenerateJWS name="JWS-Generate-HS256-JWT">
<Algorithm>HS256</Algorithm>
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
<SecretKey>
<Value ref="private.secretkey"/>
</SecretKey>
<Payload ref="json-content"/>
<AdditionalHeaders>
<Claim name="typ">JWT</Claim>
</AdditionalHeaders>
<OutputVariable>output-variable</OutputVariable>
</GenerateJWS>
分離 JWS を生成する
このサンプル ポリシーでは、RS256 アルゴリズムで署名され、分離コンテンツを使用した JWS を生成します。RS256 署名を生成するには RSA 秘密鍵が必要です。この秘密鍵は PEM エンコード形式で提供する必要があります。
分離コンテンツを含む JWS では、生成された JWS からペイロードが省略されます。
[header]..[signature]
<Payload> 要素を使用して、エンコードされていない未加工の JWS ペイロードを指定します。このポリシーがトリガーされると、Apigee は JWS ヘッダーとペイロードをエンコードし、エンコードされた署名を生成します。ただし、生成された JWS では、シリアル化された JWS からエンコードされたペイロードが省略されます。これは、署名されたコンテンツが大きいか、バイナリ（画像や PDF など）の場合に役立ちます。検証を行うには、JWS と署名付きコンテンツに含まれるペイロードの両方の要素を検証側に渡す必要があります。VerifyJWS ポリシーを使用して JWS を検証する場合は、VerifyJWS ポリシーの <DetachedContent> 要素を使用して、ペイロードを含む変数を指定できます。
<GenerateJWS name="JWS-Generate-RS256">
<DisplayName>JWS Generate RS256</DisplayName>
<Algorithm>RS256</Algorithm>
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
<PrivateKey>
<Value ref="private.privatekey"/>
<Password ref="private.privatekey-password"/>
<Id ref="private.privatekey-id"/>
</PrivateKey>
<Payload ref="my-payload"/>
<DetachContent>true</DetachContent>
<OutputVariable>output-variable</OutputVariable>
</GenerateJWS>
鍵要素の設定
次の表に示すように、JWS の生成で鍵の指定に使用する要素は、選択したアルゴリズムによって異なります。
| アルゴリズム | 鍵要素 | |
|---|---|---|
| HS{256/384/512}* | <SecretKey> <Value ref="private.secretkey"/> <Id>1918290</Id> </SecretKey> |
|
| RS/PS/ES{256/384/512}* | <PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="private.privatekey-id"/> </PrivateKey>
|
|
| * 鍵の要件については、署名の暗号化アルゴリズムについてをご覧ください。 | ||
GenerateJWS の要素リファレンス
このポリシー リファレンスでは、GenerateJWS ポリシーの要素と属性について説明しています。
注: 構成は、使用する暗号化アルゴリズムによって多少異なります。特定のユースケースの構成例については、サンプルをご覧ください。
最上位の要素に適用される属性
<GenerateJWS name="JWS" continueOnError="false" enabled="true" async="false">
次の属性は、すべてのポリシーの親要素に共通です。
| 属性 | 説明 | デフォルト | 要否 |
|---|---|---|---|
| name |
ポリシーの内部名。名前に使用できる文字は A-Z0-9._\-$ % のみです。ただし、Apigee UI には追加の制限があり、たとえば、英数字以外の文字は自動的に削除されます。必要に応じて、 |
なし | 必須 |
| continueOnError |
ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、 |
false | 省略可 |
| 有効 |
ポリシーを適用するには、true に設定します。ポリシーを無効にするには、 |
true | 省略可 |
| 非同期 | この属性は非推奨となりました。 | false | 非推奨 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
name 属性に加えて、Apigee UI プロキシ エディタでポリシーを別の自然言語名でラベル付けするために使用します。
| デフォルト | この要素を省略した場合、ポリシーの name 属性の値が使用されます。 |
| 要否 | 省略可 |
| 型 | 文字列 |
<Algorithm>
<Algorithm>algorithm-here</Algorithm>
トークンに署名する暗号化アルゴリズムを指定します。
| デフォルト | 該当なし |
| 要否 | 必須 |
| 型 | 文字列 |
| 有効な値 | HS256、HS384、HS512、RS256、RS384、RS512、ES256、ES384、ES512、PS256、PS384、PS512 |
<AdditionalHeaders/Claim>
<AdditionalHeaders>
<Claim name='claim1'>explicit-value-of-claim-here</Claim>
<Claim name='claim2' ref='variable-name-here'/>
<Claim name='claim3' ref='variable-name-here' type='boolean'/>
<Claim name='claim4' ref='variable-name' type='string' array='true'/>
</AdditionalHeaders>
JWS のヘッダーに追加のクレーム名と値のペアを挿入します。
| デフォルト | 該当なし |
| 要否 | 任意 |
| 有効な値 | 追加のクレームに使用する任意の値。クレームは、文字列、数値、ブール値、マップ、または配列として明示的に指定できます。 |
<Claim> 要素には次の属性があります。
- name -（必須）クレームの名前。パラメータとも呼ばれます。
- ref -（省略可）フロー変数の名前。設定された場合、ポリシーはこの変数の値をクレームとして使用します。ref 属性と明示的なクレーム値の両方が指定された場合、明示的な値がデフォルトとなり、参照されたフロー変数が解決されない場合に使用されます。
- type -（省略可）文字列（デフォルト）、数値、ブール値、マッピングのいずれか
- array -（省略可）値が型の配列かどうかを示すには true に設定します。デフォルト: false
<CriticalHeaders>
<CriticalHeaders>a,b,c</CriticalHeaders> or: <CriticalHeaders ref="variable_containing_headers"/>
JWS にクリティカル ヘッダーである crit を追加します。crit ヘッダーはヘッダー名の配列で、JWS の受信側に認識されている必要があります。たとえば、デコード時に次のような JWS ヘッダーを生成するために、この構成要素を使用できます。
{
"typ": "...",
"alg" : "...",
"hyb" : "some-value-here",
"crit" : [ "hyb" ],
}
この JWS ヘッダーは、hyb ヘッダー パラメータが非常に重要で、JWS の受信側がそのパラメータの意味と値を理解する必要があることを示します。
IETF RFC 7515 に従い、JWS の受信側は、crit パラメータで参照される 1 つ以上のパラメータを理解できなければ、JWS を無効として拒否する必要があります。Apigee では、VerifyJWS ポリシーがこの動作に準拠しています。crit パラメータに指定されているパラメータごとに、VerifyJWS ポリシーの <KnownHeaders> 要素がそのパラメータを指定していることを確認しますVerifyJWS ポリシーが crit で検出したヘッダーの中に <KnownHeaders> にないものがあると、VerifyJWS ポリシーは JWS を拒否します。
| デフォルト | 該当なし |
| 要否 | 省略可 |
| 型 | 1 つ以上の文字列のカンマ区切り配列 |
| 有効な値 | 配列、または配列を含む変数への参照。 |
<DetachContent>
<DetachContent>true|false</DetachContent>
分離ペイロードを使用した JWS を生成するかどうかを指定します。使用する場合は <DetachContent>true</DetachContent>、そうでない場合は <DetachContent>false</DetachContent> を指定します。
false（デフォルト）の場合、次の形式の JWS が生成されます。
[header].[payload].[signature]
true を指定して分離ペイロードを使用する JWS を作成する場合、生成される JWS ではペイロードが省略され、次の形式になります。
[header]..[signature]
分離ペイロードを使用する JWS の場合、エンコードされていない元のペイロードをシリアル化された JWS とともに検証側に渡すかどうかは任意です。
| デフォルト | false |
| 要否 | 省略可 |
| 型 | ブール値 |
| 有効な値 | true または false |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
false に設定すると、ポリシーで指定された参照値が解決できない場合にエラーを返します。true に設定すると、解決できない変数を空の文字列（null）として扱います。
| デフォルト | false |
| 要否 | 省略可 |
| 型 | ブール値 |
| 有効な値 | true または false |
<OutputVariable>
<OutputVariable>output-variable</OutputVariable>
ポリシーにより、生成された JWS が格納されるコンテキスト変数の名前を指定します。デフォルトでは、JWS は jws.POLICYNAME.generated_jws という名前のコンテキスト変数に格納されます。
| デフォルト | jws.POLICYNAME.generated_jws |
| 要否 | 省略可 |
| 型 | 文字列（フロー変数名） |
<Payload>
<Payload ref="flow-variable-name-here" /> or <Payload>payload-value</Payload>
エンコードされていない未加工の JWS ペイロードを指定します。ペイロードを含む変数または文字列を指定します。
| デフォルト | 該当なし |
| 要否 | 必須 |
| 型 | 文字列、バイト配列、ストリーム、エンコードされていない JWS ペイロードのその他の表現 |
| 有効な値 | メッセージ テンプレート、またはペイロードを含む変数への参照。 |
<PrivateKey> 要素
省略可。<Algorithm> が RS*、PS*、ES* のいずれかの場合にのみ使用されます。署名に使用する秘密鍵と、秘密鍵に関連するその他の情報を指定します。これは、アルゴリズムが非対称アルゴリズムである場合に使用されます。
<PrivateKey> <Value ref="private.privatekey"</Value> </PrivateKey>
| デフォルト: | なし |
| 要否: | 省略可。ただし、<PrivateKey> または <SecretKey> のいずれかの要素のみを含める必要があります。アルゴリズムが RS*、PS*、ES* の場合は <PrivateKey> 要素を使用し、アルゴリズムが HS* の場合は <SecretKey> 要素を使用します。 |
| 型: | なし |
<PrivateKey/Id>
<PrivateKey> <Id ref="flow-variable-name-here"/> </PrivateKey> or <PrivateKey> <Id>your-id-value-here</Id> </PrivateKey>
JWS ヘッダーに含める鍵 ID（kid）を指定します。
| デフォルト | 該当なし |
| 要否 | 省略可 |
| 型 | 文字列 |
| 有効な値 | フロー変数または文字列 |
<PrivateKey/Password>
<PrivateKey> <Password ref="private.privatekey-password"/> </PrivateKey>
ポリシーで秘密鍵の復号に使用するパスワードを指定します（必要な場合）。ref 属性を使用して、フロー変数に鍵を渡します。
| デフォルト | 該当なし |
| 要否 | 省略可 |
| 型 | 文字列 |
| 有効な値 |
フロー変数の参照。注: ref 属性を使用してフロー変数を指定する必要があります。パスワードが平文で指定されているポリシー構成は無効として拒否されます。フロー変数には接頭辞 private が必要です。例: |
<PrivateKey/Value>
<PrivateKey> <Value ref="private.variable-name-here"/> </PrivateKey>
JWS への署名に使用され、PEM エンコードされた秘密鍵を指定します。ref 属性を使用して、フロー変数に鍵を渡します。
| デフォルト | 該当なし |
| 要否 | ポリシーを使用して、RS*、PS*、ES* アルゴリズムのいずれかを使用して JWS を生成する場合に必要です。 |
| 型 | 文字列 |
| 有効な値 |
PEM エンコードされた秘密鍵の値を表す文字列を含むフロー変数。 注: フロー変数には接頭辞 private が必要です。たとえば、 |
<SecretKey>
<SecretKey encoding="base16|hex|base64|base64url" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.variable-here"/> </SecretKey>
対称（HS*）アルゴリズム（HS256、HS384、HS512 のいずれか）を使用する JWS の生成時に使用する秘密鍵を指定します。
この要素はオプションです。ただし、<PrivateKey> または <SecretKey> のいずれかの要素のみを含める必要があります。非対称アルゴリズム（RS*、PS*、ES* のいずれか）で署名された JWS を生成する場合は <PrivateKey> 要素を使用し、対称アルゴリズム（HS* などのアルゴリズム）で署名された JWS を生成する場合は <SecretKey> 要素を使用します。
<SecretKey> の子
次の表に、<SecretKey> の子要素と属性の説明を示します。
| 子 | 要否 | 説明 |
|---|---|---|
| エンコード（属性） | 省略可 | 参照される変数での鍵のエンコード方法を指定します。デフォルトでは、 <SecretKey encoding="hex" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.secretkey"/> </SecretKey> 上記の例では、エンコードが |
| Id（要素） | 省略可 | 鍵識別子。値には任意の文字列を指定できます。値は、リテラル テキスト値として、または変数参照によって間接的に、 <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.variable-here"/> </SecretKey> or <SecretKey> <Id>your-id-value-here</Id> <Value ref="private.variable-here"/> </SecretKey> この鍵識別子は、生成された JWS のヘッダーに |
| 値（要素） | 必須 | エンコードされた秘密鍵。ペイロードの署名に使用する秘密鍵を指定します。 <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.my-secret-variable"/> </SecretKey> Apigee は、HS256 / HS384 / HS512 アルゴリズムに対して最小限の鍵強度を適用します。鍵の最小長は、HS256 で 32 バイト、HS384 で 48 バイト、HS512 で 64 バイトです。強度の低い鍵を使用すると実行時エラーが発生します。 |
<Type>
<Type>type-string-here</Type>
値として Signed のみが許可される省略可能な要素です。ポリシーによって署名付き JWS が生成されることを指定します。<Type> は、GenerateJWT ポリシーと VerifyJWT ポリシーで対応する要素と合わせるために提供されます（Signed か Encrypted のいずれかの値を使用できます）。
| デフォルト | 該当なし |
| 要否 | 省略可 |
| 型 | 文字列 |
| 有効な値 | Signed |
フロー変数
GenerateJWT ポリシーではフロー変数を設定しません。
エラー リファレンス
このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。
ランタイム エラー
このエラーは、ポリシーの実行時に発生することがあります。
| 障害コード | HTTP ステータス | 発生条件 |
|---|---|---|
steps.jws.GenerationFailed |
401 |
ポリシーで JWS を生成できなかった場合。 |
steps.jws.InsufficientKeyLength |
401 |
HS256 アルゴリズムの鍵が 32 バイト未満の場合。 |
steps.jws.InvalidClaim |
401 |
クレームが欠落しているか、一致していない場合。または、ヘッダーが欠落しているか、一致していない場合。 |
steps.jws.InvalidCurve |
401 |
鍵で指定された曲線が、楕円曲線アルゴリズムでは無効な場合。 |
steps.jws.InvalidJsonFormat |
401 |
JWS ヘッダーで無効な JSON が検出された場合。 |
steps.jws.InvalidPayload |
401 |
JWS ペイロードが無効な場合。 |
steps.jws.InvalidSignature |
401 |
<DetachedContent> が省略され、JWS に分離されたコンテンツ ペイロードがある場合。 |
steps.jws.KeyIdMissing |
401 |
Verify ポリシーが公開鍵のソースとして JWKS を使用しているが、署名付き JWS のヘッダーに kid プロパティが含まれてない場合。 |
steps.jws.KeyParsingFailed |
401 |
指定された鍵情報で公開鍵を解析できない場合。 |
steps.jws.MissingPayload |
401 |
JWS ペイロードが欠落している場合。 |
steps.jws.NoAlgorithmFoundInHeader |
401 |
JWS がアルゴリズム ヘッダーを省略すると発生します。 |
steps.jws.SigningFailed |
401 |
GenerateJWS で、HS384 または HS512 アルゴリズムの鍵が最小サイズより小さい場合。 |
steps.jws.UnknownException |
401 |
不明な例外が発生した場合。 |
steps.jws.WrongKeyType |
401 |
鍵のタイプが正しくない場合。たとえば、楕円曲線アルゴリズムで RSA 鍵を指定した場合や、RSA アルゴリズムで曲線鍵を指定した場合など。 |
デプロイエラー
以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。
| エラー名 | 発生条件 |
|---|---|
InvalidAlgorithm |
有効な値: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512,
HS256, HS384, HS512 |
|
|
発生の可能性があるその他のデプロイエラー。 |
障害変数
ランタイム エラーが発生すると、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。
| 変数 | 説明 | 例 |
|---|---|---|
fault.name="fault_name" |
fault_name は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。 | fault.name Matches "TokenExpired" |
JWS.failed |
障害の場合は、すべての JWS ポリシーで同じ変数が設定されます。 | jws.JWS-Policy.failed = true |
エラー レスポンスの例
ベスト プラクティスとして、エラー処理でエラー レスポンスの errorcode の部分をトラップすることをおすすめします。faultstring のテキストには依存しないでください。この部分は変更される可能性があります。
障害ルールの例
<FaultRules>
<FaultRule name="JWS Policy Errors">
<Step>
<Name>JavaScript-1</Name>
<Condition>(fault.name Matches "TokenExpired")</Condition>
</Step>
<Condition>JWS.failed=true</Condition>
</FaultRule>
</FaultRules>