Skip to content

Internet Engineering Task Force (IETF) Y. Sheffer\ Request for Comments: 8725 Intuit\ BCP: 225 D. Hardt\ Updates: 7519\ Category: Best Current Practice M. Jones\ ISSN: 2070-1721 Microsoft\ February 2020

JSON Web Token Best Current Practices

Abstract

JSON Web Tokens（JWTs とも呼ばれる）は、URL-safe な JSON ベースのセキュリティトークンであり、署名および／または暗号化できる一連の claims を含みます。JWTs は、デジタル identity の領域およびその他の application 領域の双方において、多数の protocol と application で、単純なセキュリティトークン形式として広く使用・展開されています。この Best Current Practices 文書は RFC 7519 を更新し、JWTs の安全な実装および展開につながる、実行可能なガイダンスを提供します。

Status of This Memo

このメモは Internet Best Current Practice を文書化します。

本文書は Internet Engineering Task Force（IETF）の成果物です。IETF コミュニティのコンセンサスを反映しています。公開レビューを受け、Internet Engineering Steering Group（IESG）により出版が承認されています。BCP に関する追加情報は RFC 7841 の Section 2 にあります。

本文書の最新ステータス、errata、ならびにフィードバック提供方法についての情報は、以下から入手できます。\ https://www.rfc-editor.org/info/rfc8725

Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved.

本文書は、公開日時点で有効な BCP 78 および IETF Trust の IETF 文書に関する法的規定（https://trustee.ietf.org/license-info）の対象です。これらの文書には、本文書に関する権利および制限が記載されているため、注意深く確認してください。本書から抽出された Code Components には、Trust Legal Provisions の Section 4.e に記載の Simplified BSD License の文言を含める必要があり、また Simplified BSD License に記載のとおり無保証で提供されます。

Table of Contents

1. Introduction

JSON Web Tokens（JWTs とも呼ばれる）[RFC7519] は、URL-safe な JSON ベースのセキュリティトークンであり、署名および／または暗号化できる一連の claims を含みます。JWT の仕様は、セキュリティ上関連する情報を 1 つの保護しやすい場所にカプセル化でき、また広く利用可能なツールを用いて容易に実装できることから、急速に採用が進みました。JWTs が一般的に使用される application 領域の 1 つは、OpenID Connect ID Tokens [OpenID.Core] や OAuth 2.0 [RFC6749] の access tokens および refresh tokens のような、デジタル identity 情報を表現することです。これらの詳細は deployment 固有です。

JWT 仕様が公開されて以降、実装および展開に対する、広く公表された攻撃がいくつも存在します。そのような攻撃は、セキュリティ機構の仕様不足、ならびに不完全な実装や application による誤った使用に起因します。

本文書の目的は、JWTs の安全な実装および展開を促進することです。本書の推奨事項の多くは、JSON Web Signature (JWS) [RFC7515]、JSON Web Encryption (JWE) [RFC7516]、および JSON Web Algorithms (JWA) [RFC7518] により定義される JWT の基盤となる暗号機構の実装と利用に関するものです。その他は、JWT の claims 自体の利用に関するものです。

これらは、実装および展開のシナリオの大部分における JWTs の利用に対する最小限の推奨事項として意図されています。本文書を参照する他の仕様は、特定の事情に基づき、形式の 1 つ以上の側面に関して、より厳格な要件を持つ場合があります。その場合、実装者はそれらのより厳格な要件に従うことが推奨されます。さらに、本書は天井ではなく床を提供するものであり、より強力な選択肢は常に許容されます（例：暗号強度の重要性と計算負荷の評価が異なる場合など）。

さまざまな algorithm の強度や実行可能な攻撃に関するコミュニティ知見は急速に変化し得ます。また、セキュリティに関する Best Current Practice (BCP) 文書は時点依存の声明であることが経験的に示されています。読者は、本文書に適用される errata や更新がないかを確認することが推奨されます。

1.1. Target Audience

本文書が想定する読者は次のとおりです。

  • JWT libraries（およびそれらの libraries が使用する JWS と JWE の libraries）の実装者
  • そのような libraries を使用するコードの実装者（ある機構が libraries により提供されない範囲、または提供されるまでの範囲）
  • IETF 内外を問わず、JWTs に依拠する仕様の開発者

1.2. Conventions Used in this Document

本文書中のキーワード "MUST"、"MUST NOT"、"REQUIRED"、"SHALL"、"SHALL NOT"、"SHOULD"、"SHOULD NOT"、"RECOMMENDED"、"NOT RECOMMENDED"、"MAY"、"OPTIONAL" は、ここに示すように全て大文字で出現する場合に限り、BCP 14 [RFC2119] [RFC8174] に記載のとおりに解釈されます。

2. Threats and Vulnerabilities

この Section は、JWT の実装および展開に関して既知および可能性のある問題を列挙します。各問題の説明の後に、その問題に対する 1 つ以上の緩和策への参照が続きます。

2.1. Weak Signatures and Insufficient Signature Validation

署名付き JSON Web Tokens は、暗号の俊敏性を促進するために、"alg" Header Parameter の形で署名 algorithm の明示的な指示を持ちます。これが、一部の libraries と applications の設計上の欠陥と相まって、いくつかの攻撃につながっています。

  • 攻撃者が algorithm を "none" に変更でき、いくつかの libraries はこの値を信頼して、署名を一切チェックせずに JWT を「validate」してしまいます。
  • "RS256"（RSA、2048 bit）の parameter 値を "HS256"（HMAC、SHA-256）に変更でき、いくつかの libraries は HMAC-SHA256 を用いて署名を validate しようとして、RSA 公開鍵を HMAC の共有秘密鍵として使用してしまいます（[McLean] と [CVE-2015-9235] を参照）。

緩和策については Section 3.1 と 3.2 を参照してください。

2.2. Weak Symmetric Keys

さらに、一部の applications は "HS256" のような keyed Message Authentication Code (MAC) algorithm を使用して tokens に署名する一方で、entropy が不十分な弱い symmetric key（人間が覚えられる password など）を与えています。そのような keys は、攻撃者がそのような token を入手すると、オフラインの brute-force または辞書攻撃に対して脆弱です [Langkemper]。

緩和策については Section 3.5 を参照してください。

2.3. Incorrect Composition of Encryption and Signature

JWE で暗号化された JWT を復号して JWS 署名された object を得る一部の libraries は、内部の signature を常に validate するとは限りません。

緩和策については Section 3.3 を参照してください。

2.4. Plaintext Leakage through Analysis of Ciphertext Length

多くの暗号化 algorithms は、algorithm と動作 mode に応じた程度の差はあるものの、plaintext の長さに関する情報を漏えいします。この問題は、plaintext が最初に圧縮されるとさらに悪化します。なぜなら、圧縮後の plaintext、ひいては ciphertext の長さが、元の plaintext の長さだけでなく、その内容にも依存するためです。圧縮攻撃は、secret data と同じ圧縮空間に攻撃者が制御可能な data が存在する場合に特に強力であり、これは HTTPS に対する一部の攻撃で当てはまります。

圧縮と暗号化に関する一般的な背景については [Kelsey] を、HTTP cookies に対する攻撃の具体例としては [Alawatugoda] を参照してください。

緩和策については Section 3.6 を参照してください。

2.5. Insecure Use of Elliptic Curve Encryption

[Sanso] によれば、いくつかの Javascript Object Signing and Encryption (JOSE) libraries は、elliptic curve key agreement（"ECDH-ES" algorithm）を実行する際に入力を正しく validate できません。無効な curve points を使用する任意の JWEs を送信でき、かつ無効な curve points による復号の結果として得られる cleartext 出力を観測できる攻撃者は、この脆弱性を利用して受信者の private key を回復できます。

緩和策については Section 3.4 を参照してください。

2.6. Multiplicity of JSON Encodings

旧版の JSON 形式（廃止された [RFC7159] など）では、UTF-8、UTF-16、UTF-32 といった複数の文字 encodings が許容されていました。しかし、最新の標準 [RFC8259] では、"closed ecosystem" 内での内部利用を除き UTF-8 のみが許容されます。この曖昧さにより、古い実装や閉じた環境で使用される実装が非標準の encodings を生成し、受信者によって JWT が誤って解釈される可能性があります。その結果、悪意のある送信者が受信者の validation チェックを回避するために利用し得ます。

緩和策については Section 3.7 を参照してください。

2.7. Substitution Attacks

ある受信者に対して本来意図された JWT がその受信者に与えられ、その後、その JWT が意図されていない別の受信者で使用されようとする攻撃があります。例えば、OAuth 2.0 [RFC6749] の access token が、本来の対象である OAuth 2.0 保護 resource に正当に提示された場合、その保護 resource が、アクセス獲得を目的として、同じ access token を、本来の対象ではない別の保護 resource に提示するかもしれません。そのような状況が検出されないと、攻撃者が権限のない resources へのアクセスを得てしまう可能性があります。

緩和策については Section 3.8 と 3.9 を参照してください。

2.8. Cross-JWT Confusion

JWTs が多様な application 領域でより多くの異なる protocols に使用されるようになるにつれ、ある目的のために発行された JWT tokens が別の目的に転用される事例を防ぐことが、ますます重要になります。これは substitution attack の特定の一種である点に留意してください。JWT が、他種の JWTs と混同され得る application context で使用され得るならば、これらの substitution attacks を防ぐために緩和策が適用されなければなりません（MUST）。

緩和策については Section 3.8、3.9、3.11、3.12 を参照してください。

2.9. Indirect Attacks on the Server

さまざまな JWT claims は、受信者が database や Lightweight Directory Access Protocol (LDAP) 検索などの lookup operations を行うために使用されます。その他の例として、server が同様に lookup する URLs を含むものもあります。これらの claims のいずれも、攻撃者が injection attacks または server-side request forgery (SSRF) attacks のベクトルとして使用し得ます。

緩和策については Section 3.10 を参照してください。

3. Best Practices

以下の best practices は、前 Section に列挙された脅威を緩和するために、実務者により適用されるべきです。

3.1. Perform Algorithm Verification

Libraries は、呼び出し側がサポートされる algorithms の集合を指定できるようにしなければならず（MUST）、暗号 operations を実行する際にそれ以外の algorithms を使用してはなりません（MUST NOT）。Library は、"alg" または "enc" header が、暗号 operation に使用される algorithm と同一の algorithm を指定していることを保証しなければなりません（MUST）。さらに、各 key は厳密に 1 つの algorithm のみで使用されなければならず（MUST）、暗号 operation の実行時にこれがチェックされなければなりません（MUST）。

3.2. Use Appropriate Algorithms

[RFC7515] の Section 5.2 が述べるように、「ある context でどの algorithms を使用できるかは application の判断である。たとえ JWS が正常に validate できたとしても、JWS で使用された algorithm(s) が application にとって許容可能でない場合、application はその JWS を無効と見なすべきである（SHOULD）」。

したがって、applications は、application のセキュリティ要件を満たす暗号学的に最新の algorithms の利用のみを許可しなければなりません（MUST）。この集合は、新しい algorithms の導入や、暗号学的弱点の発見により既存の algorithms が非推奨となることで、時間とともに変化します。よって applications は暗号の俊敏性を可能にするように設計されなければなりません（MUST）。

とはいえ、JWT が TLS のような transport layer により、暗号学的に最新の algorithms を用いて end-to-end に保護されている場合、JWT に別の層の暗号保護を適用する必要がないかもしれません。そのような場合、"none" algorithm の利用は十分に許容可能になり得ます。"none" algorithm は、JWT が他の手段で暗号学的に保護されている場合にのみ使用されるべきです。JWTs が "none" を使用するのは、内容が任意に署名される application contexts においてしばしば見られます。その場合、URL-safe な claims の表現と処理は、署名あり／なしの両方で同一にできます。JWT libraries は、呼び出し側から明示的に要求されない限り、"none" を使用する JWTs を生成すべきではありません（SHOULD NOT）。同様に、JWT libraries は、呼び出し側から明示的に要求されない限り、"none" を使用する JWTs を消費すべきではありません（SHOULD NOT）。

Applications は、以下の algorithm 固有の推奨に従うべきです（SHOULD）。

  • RSA-PKCS1 v1.5 encryption algorithms（[RFC8017] Section 7.2）をすべて避け、RSAES-OAEP（[RFC8017] Section 7.1）を優先してください。
  • Elliptic Curve Digital Signature Algorithm (ECDSA) signatures [ANSI-X962-2005] は、署名する各 message ごとに一意な random value を必要とします。複数の messages 間で random value のほんの数 bits でも予測可能であれば、signature scheme のセキュリティが損なわれる可能性があります。最悪の場合、private key が攻撃者により回復され得ます。これらの attacks に対抗するため、JWT libraries は [RFC6979] で定義される deterministic approach を用いて ECDSA を実装すべきです（SHOULD）。この approach は既存の ECDSA verifiers と完全に互換であり、新しい algorithm identifiers を要求することなく実装できます。

3.3. Validate All Cryptographic Operations

JWT 内で使用されるすべての暗号 operations は validate されなければならず（MUST）、いずれかが validate に失敗した場合は JWT 全体が reject されなければなりません（MUST）。これは、単一の Header Parameters の集合を持つ JWTs に限らず、外側と内側の両方の operations が、application により提供される keys と algorithms を用いて validate されなければならない（MUST）Nested JWTs に対しても当てはまります。

3.4. Validate Cryptographic Inputs

Elliptic Curve Diffie-Hellman key agreement（"ECDH-ES"）のような一部の暗号 operations は、無効な値を含み得る inputs を取ります。これには、指定された elliptic curve 上にない points や、その他の無効な points（例：[Valenta] Section 7.1）が含まれます。JWS/JWE library 自体は、それらを使用する前にこれらの inputs を validate しなければなりません（MUST）。あるいは、そうする下位の暗号 libraries を使用しなければなりません（MUST）（またはその両方）。

Elliptic Curve Diffie-Hellman Ephemeral Static（ECDH-ES）の ephemeral public key (epk) inputs は、受信者が選択した elliptic curve に従って validate されるべきです（SHOULD）。NIST の prime-order curves である P-256、P-384、P-521 については、"Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography" [nist-sp-800-56a-r3] の Section 5.6.2.3.4（ECC Partial Public-Key Validation Routine）に従って validation が実行されなければなりません（MUST）。"X25519" または "X448" [RFC8037] の algorithms が使用される場合は、[RFC8037] の security considerations が適用されます。

3.5. Ensure Cryptographic Keys Have Sufficient Entropy

[RFC7515] の Section 10.1 にある Key Entropy と Random Values に関する助言、および [RFC7518] の Section 8.8 にある Password Considerations に従わなければなりません（MUST）。とりわけ、人間が記憶可能な passwords は、"HS256" のような keyed-MAC algorithm の key として、直接使用されてはなりません（MUST NOT）。さらに、passwords は、[RFC7518] の Section 4.8 に記載のとおり、content encryption ではなく key encryption を実行するためにのみ使用されるべきです（SHOULD）。なお、key encryption に使用した場合でも、password-based encryption は依然として brute-force 攻撃の対象となります。

3.6. Avoid Compression of Encryption Inputs

暗号化前に data を圧縮すべきではありません（SHOULD NOT）。圧縮された data は、しばしば plaintext に関する情報を漏えいするためです。

3.7. Use UTF-8

[RFC7515]、[RFC7516]、[RFC7519] はすべて、Header Parameters と JWT Claims Sets に用いられる JSON の encoding および decoding に UTF-8 を使用することを規定しています。これは最新の JSON 仕様 [RFC8259] にも合致します。実装と applications はこれを行わなければならず（MUST）、これらの目的のために他の Unicode encodings を使用したり、その使用を認めたりしてはなりません（MUST）。

3.8. Validate Issuer and Subject

JWT が "iss"（issuer）claim を含む場合、application は、JWT の暗号 operations に使用される暗号 keys が issuer に属することを validate しなければなりません（MUST）。属さない場合、application は JWT を reject しなければなりません（MUST）。

Issuer が所有する keys を決定する手段は application 固有です。一例として、OpenID Connect [OpenID.Core] の issuer 値は "https" URLs であり、"jwks_uri" 値を含む JSON metadata document を参照します。この "jwks_uri" 値は、issuer の keys を JWK Set [RFC7517] として取得するための "https" URL です。同じ mechanism は [RFC8414] でも使用されます。他の applications は issuer に keys を結び付ける別の手段を使用する場合があります。

同様に、JWT が "sub"（subject）claim を含む場合、application は subject 値が application における有効な subject および／または issuer-subject の組に対応することを validate しなければなりません（MUST）。これには、issuer が application により信頼されていることの確認を含み得ます。issuer、subject、またはその組が無効である場合、application は JWT を reject しなければなりません（MUST）。

3.9. Use and Validate Audience

同一 issuer が、複数の relying party または application により使用されることを意図した JWTs を発行し得る場合、JWT は "aud"（audience）claim を含まなければなりません（MUST）。これは、その JWT が意図した party により使用されているのか、あるいは攻撃者により意図しない party において置き換えられたのかを判断するために使用できます。

そのような場合、relying party または application は audience 値を validate しなければならず（MUST）、audience 値が存在しない、または受信者と関連付いていない場合には、JWT を reject しなければなりません（MUST）。

3.10. Do Not Trust Received Claims

"kid"（key ID）header は、relying application が key lookup を実行するために使用されます。applications は、受信した値を validate および／または sanitizing することで、これが SQL または LDAP injection 脆弱性を作らないようにすべきです（SHOULD）。

同様に、任意の URL を含み得る "jku"（JWK set URL）または "x5u"（X.509 URL）header を盲目的にたどることは、server-side request forgery (SSRF) attack を引き起こし得ます。applications は、そのような攻撃から保護すべきです（SHOULD）。例えば、URL を許可された location の whitelist と照合し、GET request で cookies が送信されないことを保証する、などです。

3.11. Use Explicit Typing

ある種の JWT が別の JWT と混同されることがあります。特定種の JWT がそのような混同の対象となる場合、その JWT は明示的な JWT type 値を含めることができ、validation rules で type のチェックを指定できます。この mechanism は混同を防ぐことができます。明示的な JWT typing は、"typ" Header Parameter を使用して行われます。例えば、[RFC8417] 仕様は、Security Event Tokens（SETs）を明示的に型付けするために "application/secevent+jwt" media type を使用します。

[RFC7515] の Section 4.1.9 における "typ" の定義に従い、"typ" 値から "application/" prefix を省略することが推奨されます（RECOMMENDED）。したがって、例えば SET の type を明示的に含めるために使用される "typ" 値は "secevent+jwt" とすべきです（SHOULD）。JWT に対して明示的 typing を用いる場合、"application/example+jwt" の形式の media type 名を使用することが推奨されます（RECOMMENDED）。ここで "example" は、その特定種の JWT の identifier で置き換えられます。

Nested JWT に明示的 typing を適用する場合、明示的 type 値を含む "typ" Header Parameter は、Nested JWT の内側の JWT（payload が JWT Claims Set である JWT）に存在しなければなりません（MUST）。場合によっては、Nested JWT 全体を明示的に型付けするために、同一の "typ" Header Parameter 値が外側の JWT にも存在することがあります。

明示的 typing の使用は、既存種の JWTs からの曖昧性解消を達成できない場合がある点に留意してください。既存種の JWTs の validation rules は、しばしば "typ" Header Parameter 値を使用しません。明示的 typing は、新しい JWT の利用に対して推奨されます（RECOMMENDED）。

3.12. Use Mutually Exclusive Validation Rules for Different Kinds of JWTs

各 application は、必須および任意の JWT claims と、それらに関連付く validation rules を指定する profile を定義します。同一 issuer から複数種の JWT が発行され得る場合、それらの JWTs の validation rules は、相互に排他的となるように書かれなければならず（MUST）、誤った種の JWTs を reject しなければなりません（MUST）。ある context の JWTs が別の context に置き換えられることを防ぐために、application 開発者は複数の戦略を採用し得ます。

  • 異なる種の JWTs に対して明示的 typing を使用する。そうすれば、異なる "typ" 値を用いて、異なる種の JWTs を区別できます。
  • 必須 claims の集合を変える、または必須 claim 値を変える。そうすれば、ある種の JWT の validation rules は、異なる claims や値を持つものを reject します。
  • 必須 Header Parameters の集合を変える、または必須 Header Parameter 値を変える。そうすれば、ある種の JWT の validation rules は、異なる Header Parameters や値を持つものを reject します。
  • 異なる種の JWTs に対して異なる keys を使用する。そうすれば、ある種の JWT を validate するために使用される keys は、他の種の JWTs を validate できません。
  • 同一 issuer からの JWTs の異なる用途に対して異なる "aud" 値を使用する。そうすれば、audience validation は、不適切な contexts に置き換えられた JWTs を reject します。
  • 異なる種の JWTs に対して異なる issuers を使用する。そうすれば、異なる "iss" 値を用いて、異なる種を分離できます。

JWT の利用と applications の多様性が広いことを踏まえると、異なる種の JWTs を区別するための type、必須 claims、値、Header Parameters、key usages、および issuers の最適な組み合わせは、一般に application 固有です。Section 3.11 で述べたとおり、新しい JWT applications に対しては、明示的 typing の使用が推奨されます（RECOMMENDED）。

4. Security Considerations

本文書全体は、JSON Web Tokens を実装および展開する際の security considerations について述べています。

5. IANA Considerations

本文書には IANA actions はありません。

6. References

6.1. Normative References

6.2. Informative References

Acknowledgements

"ECDH-ES" の invalid point attack に JWE と JWT の実装者が注意を払うよう促してくれた Antonio Sanso に感謝します。Tim McLean は RSA/HMAC confusion attack [McLean] を公開しました。明示的 typing の利用を提唱してくれた Nat Sakimura に感謝します。多数のコメントをくれた Neil Madden、ならびにレビューをしてくれた Carsten Bormann、Brian Campbell、Brian Carpenter、Alissa Cooper、Roman Danyliw、Ben Kaduk、Mirja Kühlewind、Barry Leiba、Eric Rescorla、Adam Roach、Martin Vigoureux、Éric Vyncke に感謝します。

Authors' Addresses

Yaron Sheffer\ Intuit

Email: yaronf.ietf@gmail.com

Dick Hardt

Email: dick.hardt@gmail.com

Michael B. Jones\ Microsoft

Email: mbj@microsoft.com\ URI: https://self-issued.info/