DecodeJWT ポリシー

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

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

ポリシー アイコン

概要

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

JWT Decode ポリシーは、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 プロキシの後続のポリシーまたは条件でそれらの値を調べることができます。このポリシーの変数のリストについては、フロー変数をご覧ください。

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 を探すフロー変数を指定します。

デフォルト request.header.authorization(デフォルトに関する重要な情報については上記の注を参照)。
要否 省略可
文字列
有効な値 Apigee フロー変数名

フロー変数

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

エラー リファレンス

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

ランタイム エラー

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

障害コード 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 "InvalidToken"
JWT.failed 障害の場合、すべての JWT ポリシーで同じ変数が設定されます。 JWT.failed = true

エラー レスポンスの例

JWT ポリシーの障害コード

ベスト プラクティスとして、エラー処理では、エラー レスポンスの 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>