Add duplicate claim name detection per RFC 7519 Section 4 by ydah · Pull Request #713 · jwt/ruby-jwt

ydah · 2026-01-29T13:12:57Z

Description

Implements duplicate claim name detection as specified in RFC 7519 Section 4, which states:

The Claim Names within a JWT Claims Set MUST be unique; JWT parsers MUST either reject JWTs with duplicate Claim Names or use a JSON parser that returns only the lexically last duplicate member name.

see: https://datatracker.ietf.org/doc/html/rfc7519#section-4

This feature allows users to reject JWTs that contain duplicate keys in the header or payload, which is recommended for security-sensitive applications to prevent claim confusion attacks.

Checklist

Before the PR can be merged be sure the following are checked:

There are tests for the fix or feature added/changed
A description of the changes and a reference to the PR has been added to CHANGELOG.md. More details in the CONTRIBUTING.md

lib/jwt/json.rb

lib/jwt/encoded_token.rb

lib/jwt/json.rb

lib/jwt/decode.rb

lib/jwt/configuration/decode_configuration.rb

anakinj · 2026-01-29T17:31:04Z

Overall I support this feature and think it should be the default behavior.

My biggest concern is adding a lot of logic to this now it will stay and live in the gem in the future.

Would almost just like to require json >= 2.13.0 and always parse the json with allow_duplicate_key: false. Then ship a jwt gem with this potentially breaking change. If needed we can then add a feature to loosen this behavior by for example allowing swapping the JSON parser.

ydah · 2026-01-30T10:03:11Z

.github/workflows/test.yml

        os:
          - ubuntu-latest
        ruby:
-          - "2.5"


MEMO: We added json gem >= 2.13.0 to the dependencies, but this version requires Ruby 2.7+. Since ruby-jwt has required_ruby_version = ‘>= 2.5’, dependency resolution fails during bundle install in a Ruby 2.5 environment.

Would like to support as many versions as possible, what about dynamically figure out if its possible to enable this feature or not.

Indeed, I've restored support for 2.5 and 2.6.

ydah · 2026-01-30T10:03:28Z

I updated this PR. WDYT?

lib/jwt/json.rb

anakinj · 2026-02-03T19:32:03Z

lib/jwt/json.rb

+      #   JWT::JSON.parse('{"a":1,"a":2}', allow_duplicate_keys: false)
+      #   # => raises JWT::DuplicateKeyError
+      def parse(data, allow_duplicate_keys: true)
+        ::JSON.parse(data, allow_duplicate_key: allow_duplicate_keys)


This is problematic in a way that when JSON 3.0 ships with the switched default we still are allowing duplicate keys by default. Would rather at that point enforce the new default for everyone.

Could we pass the parameter to the JSON lib only if the parameter is false,

I fixed it. Please point out if I understand something wrong.

lib/jwt/encoded_token.rb

anakinj · 2026-02-03T19:34:17Z

lib/jwt/encoded_token.rb

  #   encoded_token.verify_signature!(algorithm: 'HS256', key: 'secret')
  #   encoded_token.payload # => {'pay' => 'load'}
-  class EncodedToken
+  class EncodedToken # rubocop:disable Metrics/ClassLength


Wonder if we could do something to not need to disable cops 🤔

I've extracted some classes. WDYT?

The refactorings are pretty nice but could we do those in a separate PR?

Implements duplicate claim name detection as specified in RFC 7519 Section 4, which states: > The Claim Names within a JWT Claims Set MUST be unique; JWT parsers MUST either reject JWTs with duplicate Claim Names or use a JSON parser that returns only the lexically last duplicate member name. This feature allows users to reject JWTs that contain duplicate keys in the header or payload, which is recommended for security-sensitive applications to prevent claim confusion attacks.

…dToken API

…on a runtime feature check instead of a hard dependency on json >= 2.13.0

… single call with conditional options

…licate_keys! method

… SignatureVerifier classes to reduce class complexity

…N gem version support

anakinj · 2026-02-15T10:02:02Z

Sorry for the back and forth but im a bit starting to regret my suggestions to only allowing enabling it per instance. I wonder if it would still be easier for most users to enable this globally for the gem. Also setting the flag to true/false would allow disabling of the strictness when JSON 3.0 is out with the new default.

What do you think:

JWT.configuration.decode.allow_duplicate_json_keys 

nil/not set - default behavior of the JSON gem
false - always deny, if set require the JSON gem that supports it
true - always allow, no gem restrictions

Also as mentioned earlier maybe do the refactorings in separate to keep the scope of this change on the new feature?

anakinj · 2026-02-15T09:40:15Z

CHANGELOG.md

+**Breaking changes:**
+- Drop support for Ruby 2.6 and older [#713](https://github.com/jwt/ruby-jwt/pull/713) ([@ydah](https://github.com/ydah))
+- Bump minimum json gem version to 2.6 [#713](https://github.com/jwt/ruby-jwt/pull/713) ([@ydah](https://github.com/ydah))
+


Suggested change

**Breaking changes:**

- Drop support for Ruby 2.6 and older [#713](https://github.com/jwt/ruby-jwt/pull/713) ([@ydah](https://github.com/ydah))

- Bump minimum json gem version to 2.6 [#713](https://github.com/jwt/ruby-jwt/pull/713) ([@ydah](https://github.com/ydah))

No breaking changes anymore, right?

anakinj · 2026-02-15T09:58:09Z

lib/jwt/encoded_token.rb

  #   encoded_token.verify_signature!(algorithm: 'HS256', key: 'secret')
  #   encoded_token.payload # => {'pay' => 'load'}
-  class EncodedToken
+  class EncodedToken # rubocop:disable Metrics/ClassLength


The refactorings are pretty nice but could we do those in a separate PR?

ydah force-pushed the duplicate_claim_detection branch from 0838041 to bf095f9 Compare January 29, 2026 13:17

ydah commented Jan 29, 2026

View reviewed changes

lib/jwt/json.rb Outdated Show resolved Hide resolved

anakinj reviewed Jan 29, 2026

View reviewed changes

lib/jwt/encoded_token.rb Outdated Show resolved Hide resolved

lib/jwt/json.rb Outdated Show resolved Hide resolved

lib/jwt/decode.rb Outdated Show resolved Hide resolved

lib/jwt/configuration/decode_configuration.rb Outdated Show resolved Hide resolved

ydah force-pushed the duplicate_claim_detection branch from 1acb9e3 to 11450ac Compare January 30, 2026 10:00

ydah requested a review from anakinj January 30, 2026 10:01

ydah commented Jan 30, 2026

View reviewed changes

anakinj reviewed Feb 3, 2026

View reviewed changes

lib/jwt/json.rb Outdated Show resolved Hide resolved

anakinj reviewed Feb 3, 2026

View reviewed changes

lib/jwt/encoded_token.rb Show resolved Hide resolved

anakinj reviewed Feb 3, 2026

View reviewed changes

ydah force-pushed the duplicate_claim_detection branch from 225ddb0 to 6ef1d19 Compare February 4, 2026 22:26

ydah added 10 commits February 5, 2026 07:34

Remove duplicate key detection from JWT.decode API in favor of Encode…

798b92e

…dToken API

Update Ruby version requirements and modify CI configurations

bb1f74c

Lower minimum Ruby version to 2.5 and make JSON duplicate key detecti…

5328698

…on a runtime feature check instead of a hard dependency on json >= 2.13.0

Remove verbose YARD documentation comments from JWT::JSON class

9e357f2

Simplify JSON parse logic by consolidating duplicate branching into a…

730ebdc

… single call with conditional options

Add UnsupportedError for unsupported features and update raise_on_dup…

22db63a

…licate_keys! method

Extract EncodedToken internals into ClaimsContext, SegmentParser, and…

f3365e6

… SignatureVerifier classes to reduce class complexity

Revert drop 2.5, 2.6 support

befe5a8

Add conditional guards for duplicate key detection specs based on JSO…

ad53ab7

…N gem version support

ydah force-pushed the duplicate_claim_detection branch from 905c978 to ad53ab7 Compare February 4, 2026 22:34

ydah requested a review from anakinj February 4, 2026 22:44

anakinj reviewed Feb 15, 2026

View reviewed changes

anakinj mentioned this pull request Feb 15, 2026

Implements Nested JWT functionality as defined in RFC 7519 Section 5.2, 7.1, 7.2, and Appendix A.2. #712

Open

2 tasks

	Breaking changes:
	- Drop support for Ruby 2.6 and older [#713](https://github.com/jwt/ruby-jwt/pull/713) ([@ydah](https://github.com/ydah))
	- Bump minimum json gem version to 2.6 [#713](https://github.com/jwt/ruby-jwt/pull/713) ([@ydah](https://github.com/ydah))

Conversation

ydah commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

anakinj commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ydah commented Jan 30, 2026

Uh oh!

Uh oh!

anakinj Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anakinj commented Feb 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ydah commented Jan 29, 2026 •

edited

Loading

anakinj commented Jan 29, 2026 •

edited

Loading

anakinj Feb 3, 2026 •

edited

Loading

anakinj commented Feb 15, 2026 •

edited

Loading