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 が検出されるとポリシーが想定するフロー変数を指定します。

デフォルト 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.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 では、この変数は設定されません。

エラー リファレンス

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.jwt.FailedToDecode 401 Occurs when the policy is unable to decode the JWT. The JWT may be malformed, invalid or otherwise not decodable.
steps.jwt.FailedToResolveVariable 401 Occurs when the flow variable specified in the <Source> element of the policy does not exist.
steps.jwt.InvalidToken 401 Occurs when the flow variable specified in the <Source> element of the policy is out of scope or can't be resolved.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidEmptyElement Occurs when the flow variable containing the JWT to be decoded is not specified in the <Source> element of the policy.

障害変数

ランタイム エラーが発生すると、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

変数 説明
fault.name="fault_name" fault_name は、上記のランタイム エラーの表に記載されている障害の名前です。障害コードの最後の部分が障害名になります。 fault.name Matches "TokenExpired"
JWT.failed 障害の場合、すべての JWT ポリシーで同じ変数が設定されます。 JWT.failed = true

エラー レスポンスの例

JWT ポリシーの障害コード

ベスト プラクティスとして、エラー処理では、エラー レスポンスの errorcode の部分をトラップすることをおすすめします。faultstring のテキストには依存しないでください。この部分は変更される可能性があります。

障害ルールの例

    <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>