DecodeJWT ポリシー

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

概要

JWT の署名を検証せずに JWT をデコードします。これは、JWT の署名を検証する前に、JWT 内からのクレームの値を知っておく必要がある場合に、VerifyJWT ポリシーと組み合わせて使用すると非常に便利です。

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

このポリシーは、標準ポリシーであり、任意の環境タイプにデプロイできます。ポリシーのタイプと、各環境タイプで使用可能かどうかは、ポリシータイプをご覧ください。

動画

注: 次の動画では、Apigee UI に従来のプロキシ エディタが表示されています。Apigee では、プロキシ エディタの新しいバージョンが導入されています。新しいバージョンは、この動画に表示される従来のバージョンとはデザインが異なります。

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

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

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

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

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

DecodeJWT の要素リファレンス

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

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Source>

<Source>jwt-variable</Source>

この要素を使用する場合、ポリシーがデコード対象の JWT を探すフロー変数を指定します。

注: デフォルトでは、JWT は変数 request.header.authorization から取得されます。この場合、Apigee はリクエストの 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（デフォルトに関する重要な情報については上記の注を参照）。
要否	省略可
型	文字列
有効な値	Apigee フロー変数名

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 the context variable named jwt.jwt-parse-token.decoded.claim.sub. (For backward compatibility, it will also be available in jwt.jwt-parse-token.claim.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 milliseconds since epoch.
claim.issuedat	The Date the token was issued, expressed in milliseconds since epoch.
claim.issuer	The JWT issuer claim.
claim.notbefore	If the JWT includes a nbf claim, this variable will contain the value, expressed in milliseconds 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. For example, you can use decoded.claim.iat to retrieve the issued-at time of the JWT, expressed in seconds since epoch. 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 Apigee 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 "InvalidToken"
JWT.failed	障害の場合、すべての JWT ポリシーで同じ変数が設定されます。	JWT.failed = true

エラー レスポンスの例

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

障害ルールの例

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