DecodeJWT ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

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

注: デフォルトでは、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 フロー変数名

フロー変数

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>