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 に設定します。

ポリシーを無効にするには、false に設定します。ポリシーがフローに添付されている場合でも強制されません。

true 省略可
async この属性は非推奨となりました。 false 非推奨

<DisplayName>

    <DisplayName>Policy Display Name</DisplayName>
    

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

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

<Source>

    <Source>jwt-variable</Source>
    

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

デフォルト request.header.authorization (デフォルトについての重要な情報は上記の注をご覧ください)。
必須? 省略可
文字列
有効な値 Edge のフロー変数名

Flow variables

Upon success, the Verify JWT and Decode JWT policies set context variables according to this pattern:

jwt.{policy_name}.{variable_name}

For example, if the policy name is jwt-parse-token , then the policy will store the subject specified in the JWT to this context variable: jwt.jwt-parse-token.subject

Variable name Description
claim.audience The JWT audience claim. This value may be a string, or an array of strings.
claim.expiry The expiration date/time, expressed in seconds since epoch.
claim.issuedat The Date the token was issued, expressed in seconds since epoch.
claim.issuer The JWT issuer claim.
claim.notbefore If the JWT includes a nbf claim, this variable will contain the value. This is expressed in seconds since epoch.
claim.subject The JWT subject claim.
claim.name The value of the named claim (standard or additional) in the payload. One of these will be set for every claim in the payload.
decoded.claim.name The JSON-parsable value of the named claim (standard or additional) in the payload. One variable is set for every claim in the payload. While you can also use the claim.name flow variables, this is the recommended variable to use to access a claim.
decoded.header.name The JSON-parsable value of a header in the payload. One variable is set for every header in the payload. While you can also use the header.name flow variables, this is the recommended variable to use to access a header.
expiry_formatted The expiration date/time, formatted as a human-readable string. Example: 2017-09-28T21:30:45.000+0000
header.algorithm The signing algorithm used on the JWT. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more.
header.kid The Key ID, if added when the JWT was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT policies overview to verify a JWT. See (Key ID) Header Parameter for more.
header.type Will be set to JWT.
header.name The value of the named header (standard or additional). One of these will be set for every additional header in the header portion of the JWT.
header-json The header in JSON format.
is_expired true or false
payload-claim-names An array of claims supported by the JWT.
payload-json
The payload in JSON format.
seconds_remaining The number of seconds before the token will expire. If the token is expired, this number will be negative.
time_remaining_formatted The time remaining before the token will expire, formatted as a human-readable string. Example: 00:59:59.926
valid In the case of VerifyJWT, this variable will be true when the signature is verified, and the current time is before the token expiry, and after the token notBefore value, if they are present. Otherwise false.

In the case of DecodeJWT, this variable is not set.

エラー リファレンス

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

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

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>