DecodeJWT ポリシー

概要

JWT の署名を検証せずに JWT をデコードします。このポリシーは、JWT の署名を検証する前に JWT 内のクレームの値を把握しなければならない場合に、Verify JWT ポリシーと一緒に使用すると便利です。

Decode JWT ポリシーは、JWT を署名するために使用したアルゴリズムに関係なく動作します。詳細については、JWS ポリシーと JWT ポリシーの概要をご覧ください。

動画

JWT をデコードする方法について解説する動画をご覧ください。

サンプル: JWT をデコードする

以下に示すポリシーでは、フロー変数 var.jwt 内の JWT をデコードします。この変数が存在し、かつ有効（デコード可能）な JWT が含まれている必要があります。このポリシーは、JWT をあらゆるフロー変数から得ることができます。

<DecodeJWT name="JWT-Decode-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Source>var.jwt</Source>
</DecodeJWT>

ポリシーは出力をコンテキスト変数に書き込み、後続のポリシーまたは API プロキシの条件でその値を調べられるようにします。このポリシーの変数のリストについては、フロー変数をご覧ください。

Decode JWT の要素リファレンス

このポリシーリファレンスでは、Decode JWT ポリシーの要素と属性について説明します。

最上位の要素に適用される属性

<DecodeJWT name="JWT" continueOnError="false" enabled="true" async="false">

次の属性は、すべてのポリシーの親要素に共通です。

属性	説明	デフォルト	要否
name	ポリシーの内部名。名前に使用できる文字は `A-Z0-9._\-$ %` のみです。ただし、Edge 管理 UI では、英数字以外の文字を自動的に削除するなど、追加の制限が適用されます。必要に応じて、`<displayname></displayname>` 要素を使用して、管理 UI プロキシエディタでポリシーに別の自然言語名でラベルを付けます。	なし	必須
continueOnError	ポリシーが失敗した場合にエラーを返すには、`false` に設定します。これはほとんどのポリシーで想定される動作です。ポリシーが失敗してもフロー実行を続行するには、`true` に設定します。	false	省略可
enabled	ポリシーを適用するには `true` に設定します。ポリシーを「turn off」するには、`false` に設定します。ポリシーがフローに接続されている場合でも適用されません。	true	省略可
async	この属性は非推奨となりました。	false	非推奨

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

name 属性に加えて、管理 UI プロキシエディタのポリシーに別の自然言語名でラベルを付けるために使います。

デフォルト	この要素を省略した場合、ポリシーの name 属性の値が使用されます。
要否	省略可
型	文字列

<Source>

<Source>jwt-variable</Source>

この要素が存在する場合、デコード対象の JWT が検出されるとポリシーが想定するフロー変数を指定します。

注: デフォルトでは、JWT は変数 request.header.authorization から取り出します。この場合、Edge はリクエストの Authorization ヘッダーで JWT を探します。Authorization ヘッダーに JWT を渡す場合、ポリシーに Source 要素を含める必要はありません。ただし、認可ヘッダーに Bearer を含める必要があります。たとえば、Authorization ヘッダーで JWT を次のように渡します。

curl -v http://52.200.92.187:9001/doctest-jwt/verify-rs256 -H "Authorization: Bearer <your JWT>"

フォームまたはクエリパラメータ変数やその他の変数から JWT を取り出すポリシーを構成できます。変数が存在しない場合、またはポリシーが JWT を見つけられない場合、ポリシーはエラーを返します。

デフォルト	`request.header.authorization`（デフォルトに関する重要な情報については、上記の注をご覧ください）。
要否	省略可
型	文字列
有効な値	Edge のフロー変数名

フロー変数

Verify JWT ポリシーと Decode JWT ポリシーは、成功すると次のパターンに従ってコンテキスト変数を設定します。

jwt.{policy_name}.{variable_name}

たとえば、ポリシー名が jwt-parse-token の場合、ポリシーは JWT で指定されたサブジェクトをコンテキスト変数 jwt.jwt-parse-token.decoded.claim.sub に保存します。（下位互換性を確保するため、jwt.jwt-parse-token.claim.subject でも利用できます）。

変数名	説明
`claim.audience`	JWT オーディエンスクレーム。この値は、文字列または文字列の配列です。
`claim.expiry`	有効期限の日時を示すエポックミリ秒。
`claim.issuedat`	トークンの発行日を示すエポックミリ秒。
`claim.issuer`	JWT 発行元クレーム。
`claim.notbefore`	JWT に nbf クレームが含まれている場合、この変数に値（エポックミリ秒）が含まれます。
`claim.subject`	JWT サブジェクトクレーム。
`claim.name`	ペイロードに含まれる名前付きクレームの値（標準または追加）。ペイロードに含まれるすべてのクレームに、これらのいずれかが設定されます。
`decoded.claim.name`	ペイロードに含まれる名前付きクレーム（標準または追加）の JSON 解析可能な値。ペイロードに含まれるすべてのクレームに 1 つの変数が設定されます。たとえば、`decoded.claim.iat` を使用して JWT の発行時刻（エポック秒）を取得できます。`claim.name` フロー変数を使用することもできますが、クレームへのアクセスにはこの変数を使用することをおすすめします。
`decoded.header.name`	ペイロードに含まれるヘッダーの JSON 解析可能な値。ペイロードに含まれるすべてのヘッダーに 1 つの変数が設定されます。`header.name` フロー変数を使用することもできますが、ヘッダーへのアクセスにはこの変数を使用することをおすすめします。
`expiry_formatted`	人間が読める文字列で表された有効期限の日時。例: 2017-09-28T21:30:45.000+0000
`header.algorithm`	JWT で使用される署名アルゴリズム。たとえば、RS256、HS384 など。詳細については、（アルゴリズム）ヘッダーパラメータをご覧ください。
`header.kid`	鍵 ID（JWT の生成時に追加された場合）。JWT を検証するため、JWT ポリシーの概要の「JSON Web Key Set（JWKS）の使用」もご覧ください。詳細は、（鍵 ID）Header パラメータをご覧ください。
`header.type`	`JWT` に設定されます。
`header.name`	指定されたヘッダーの値（標準または追加）。このいずれかが、JWT のヘッダー部分のすべての追加ヘッダーに設定されます。
`header-json`	JSON 形式のヘッダー。
`is_expired`	true または false
`payload-claim-names`	JWT でサポートされるクレームの配列。
`payload-json`	JSON 形式のペイロード。
`seconds_remaining`	トークンが期限切れになるまでの秒数。トークンが期限切れの場合、この数値は負の値になります。
`time_remaining_formatted`	トークンが期限切れになるまでの残り時間（人間が読める形式の文字列）。例: 00:59:59.926
`valid`	VerifyJWT では、署名が検証済みであり、現在時刻がトークンの有効期限よりも前で、notBefore トークンの値よりも後の場合、この変数は true になります。それ以外は、false になります。 DecodeJWT では、この変数は設定されません。

エラーリファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラーメッセージ、Edge によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイムエラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード	HTTP ステータス	原因
`steps.jwt.FailedToDecode`	401	ポリシーが JWT をデコードできない場合に発生します。JWT が無効か、形式が正しくないか、それ以外の理由でデコードできない可能性があります。
`steps.jwt.FailedToResolveVariable`	401	ポリシーの `<Source>` 要素で指定されたフロー変数が存在しない場合に発生します。
`steps.jwt.InvalidToken`	401	ポリシーの `<Source>` 要素で指定されたフロー変数が範囲外であるか、解決できない場合に発生します。

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

エラー名	原因	修正
`InvalidEmptyElement`	デコードする JWT を含むフロー変数が、ポリシーの `<Source>` 要素で指定されていない場合に発生します。

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "TokenExpired"`
`JWT.failed`	All JWT policies set the same variable in the case of a failure.	`JWT.failed = true`

Example error response

JWT Policy Fault Codes

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>