このページの内容は 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 には追加の制限があり、たとえば、英数字以外の文字は自動的に削除されます。必要に応じて、 |
なし | 必須 |
continueOnError |
ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、 |
false | 省略可 |
有効 |
ポリシーを適用するには、true に設定します。ポリシーを無効にするには、 |
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 が無効か、形式が正しくないか、それ以外の理由でデコードできない可能性があります。 | build |
steps.jwt.FailedToResolveVariable |
401 |
ポリシーの <Source> 要素で指定されたフロー変数が存在しない場合に発生します。 |
|
steps.jwt.InvalidToken |
401 |
ポリシーの <Source> 要素で指定されたフロー変数が範囲外であるか、解決できない場合に発生します。 |
build |
デプロイエラー
以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。
エラー名 | 原因 | 修正 |
---|---|---|
InvalidEmptyElement |
デコードする JWT を含むフロー変数が、ポリシーの <Source> 要素で指定されていない場合に発生します。 |
build |
障害変数
ランタイム エラーが発生すると、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。
変数 | 説明 | 例 |
---|---|---|
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>