このページは Apigee と Apigee ハイブリッドに適用されます。
Apigee Edge のドキュメントはこちらをご覧ください。
概要
JWS の署名を検証せずに JWS をデコードし、各ヘッダーをフロー変数に書き込みます。このポリシーは、JWS の署名の検証前に JWS 内のヘッダーの値がわかっている必要がある場合に、VerifyJWS ポリシーと組み合わせて使用すると非常に便利です。
JWS にはペイロードを含めることができます。その場合、次のような形式になります。
header.payload.signature
JWS でペイロードを省略することもできます（分離ペイロード）。その場合は次の形式になります。
header..signature
DecodeJWS ポリシーは、JWS のヘッダー部分のみをデコードするため、どちらの形式でも機能します。また、DecodeJWS ポリシーは、JWS の署名に使用されたアルゴリズムに関係なく動作します。
JWS の詳細と形式の概要については、JWS ポリシーと JWT ポリシーの概要をご覧ください。
このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。
動画
JWT のデコード方法について解説している動画をご覧ください。この動画では JWT について説明していますが、コンセプトの多くは JWS と同じです。
サンプル: JWS をデコードする
以下に示すポリシーでは、フロー変数 var.JWS 内の JWS をデコードします。この変数が存在し、かつ有効（デコード可能）な JWS が含まれている必要があります。このポリシーは、JWS をあらゆるフロー変数から得ることができます。
<DecodeJWS name="JWS-Decode-HS256">
<DisplayName>JWS Verify HS256</DisplayName>
<Source>var.JWS</Source>
</DecodeJWS>
JWS のヘッダー部分にあるヘッダーごとに、このポリシーで次の名前のフロー変数が設定されます。
jws.policy-name.header.header-name
JWS にペイロードが含まれている場合は、ペイロードに jws.policy-name.header.payload フロー変数を設定します。分離ペイロードの場合は、payload が空になります。このポリシーの変数のリストについては、フロー変数をご覧ください。
DecodeJWS の要素リファレンス
このポリシー リファレンスでは、DecodeJWS ポリシーの要素と属性について説明します。
最上位の要素に適用される属性
<DecodeJWS 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 属性に加えて、管理 UI プロキシ エディタでポリシーを別の自然言語名でラベル付けするために使用します。
| デフォルト | この要素を省略した場合、ポリシーの name 属性の値が使用されます。 |
| 要否 | 省略可 |
| 型 | 文字列 |
<Source>
<Source>JWS-variable</Source>
この要素を使用する場合、ポリシーがデコード対象の JWS を探すフロー変数を指定します。
| デフォルト | request.header.authorization（デフォルトに関する重要な情報については上記の注を参照）。 |
| 要否 | 省略可 |
| 型 | 文字列 |
| 有効な値 | Apigee フロー変数名 |
フロー変数
Verify JWS ポリシーと Decode JWS ポリシーは、成功すると、次のパターンに従ってコンテキスト変数を設定します。
jws.{policy_name}.{variable_name}
たとえば、ポリシー名が verify-jws の場合、ポリシーは JWS で指定されたアルゴリズムをコンテキスト変数 jws.verify-jws.header.algorithm に保存します。
| 変数名 | 説明 |
|---|---|
decoded.header.name |
ペイロードに含まれるヘッダーの JSON 解析可能な値。ペイロードに含まれるすべてのヘッダーに 1 つの変数が設定されます。header.name フロー変数を使用することもできますが、ヘッダーへのアクセスにはこの変数を使用することをおすすめします。 |
header.algorithm |
JWS で使用される署名アルゴリズム。たとえば、RS256、HS384 など。詳細については、（アルゴリズム）ヘッダー パラメータをご覧ください。 |
header.kid |
鍵 ID（JWS の生成時に追加された場合）。JWS を検証するため、JWT と JWS ポリシーの概要の「JSON Web Key Set（JWKS）の使用」もご覧ください。詳細については、（鍵 ID）ヘッダー パラメータをご覧ください。 |
header.type |
ヘッダータイプの値。詳細は、（タイプ）ヘッダー パラメータをご覧ください。 |
header.name |
名前付きヘッダーの値（標準または追加）。このいずれかが、JWS のヘッダー部分のすべての追加ヘッダーに設定されます。 |
header-json |
JSON 形式のヘッダー。 |
payload |
JWS ペイロード（JWS に接続されたペイロードが存在する場合）。分離されたペイロードの場合、この変数は空です。 |
valid |
VerifyJWS では、署名が検証済みで、現在時刻がトークンの有効期限よりも前で、notBefore トークンの値よりも後の場合、この変数は true になります。それ以外は、false になります。 DecodeJWS では、この変数は設定されません。 |
エラー リファレンス
このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。
ランタイム エラー
このエラーは、ポリシーの実行時に発生することがあります。
| 障害コード | HTTP ステータス | 発生条件 |
|---|---|---|
steps.jws.FailedToDecode |
401 |
ポリシーで JWS をデコードできなかった場合。JWS が破損している可能性があります。 |
steps.jws.FailedToResolveVariable |
401 |
ポリシーの <Source> 要素で指定されたフロー変数が存在しない場合に発生します。 |
steps.jws.InvalidClaim |
401 |
クレームが欠落しているか、一致していない場合。または、ヘッダーが欠落しているか、一致していない場合。 |
steps.jws.InvalidJsonFormat |
401 |
JWS ヘッダーで無効な JSON が検出された場合。 |
steps.jws.InvalidJws |
401 |
JWS 署名の検証で不合格だった場合。 |
steps.jws.InvalidPayload |
401 |
JWS ペイロードが無効な場合。 |
steps.jws.InvalidSignature |
401 |
<DetachedContent> が省略され、JWS に分離されたコンテンツ ペイロードがある場合。 |
steps.jws.MissingPayload |
401 |
JWS ペイロードが欠落している場合。 |
steps.jws.NoAlgorithmFoundInHeader |
401 |
JWS がアルゴリズム ヘッダーを省略すると発生します。 |
steps.jws.UnknownException |
401 |
不明な例外が発生した場合。 |
デプロイエラー
以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。
| エラー名 | 発生条件 |
|---|---|
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>