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 では、この変数は設定されません。

エラー リファレンス

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

ランタイム エラー

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

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

デプロイエラー

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

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

障害変数

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

変数 説明
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>