Add duplicate claim name detection per RFC 7519 Section 4 #713

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

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.

ydah · 2026-01-29T13:17:54Z

lib/jwt/json.rb

+
+    # @api private
+    # Checks for duplicate keys in a JSON string using a StringScanner-based tokenizer
+    # rubocop:disable Style/RedundantRegexpArgument


see: https://github.com/jwt/ruby-jwt/actions/runs/21479506016/job/61871895439

anakinj · 2026-01-29T17:10:45Z

lib/jwt/encoded_token.rb

    # @raise [ArgumentError] if the provided JWT is not a String.
-    def initialize(jwt)
+    # @raise [JWT::DuplicateKeyError] if allow_duplicate_keys is false and duplicate keys are found.
+    def initialize(jwt, allow_duplicate_keys: true)


Would like to avoid bloating the initializer with feature parameters, the original JWT.encode and JWT.decode methods became parameter monsters over time.

A few random options, not sure if Im a fan of either of my own suggestions :)

token = EncodedToken.new(jwt) token.raise_on_duplicate_keys!

token = EncodedToken.new(jwt) token.decode_payload!(raise_on_duplicate_keys:true)

Or allowing changing the default JSON decoder with a stricter one, token.raise_on_duplicate_keys! could internally do something like this.

token = EncodedToken.new(jwt) token.parser = JWT::JSON.new(raise_on_duplicate_keys:true)

I've organized it. What do you think?

anakinj · 2026-01-29T17:15:57Z

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)
+        DuplicateKeyChecker.check!(data) unless allow_duplicate_keys


Should we try to use the built-in-soon-to-be-default ::JSON.parse(data, allow_duplicate_key: false) to deal with this issue. Feels like this gem is not supposed to be dealing with parsing concerns.

Also the new default will kick in in json 3.0. Think if the user has not taken a stance the default behavior of the json gem should be honored.

So adding as little logic as possible related to this feature will make future maintenance easier.

anakinj · 2026-01-29T17:19:51Z

lib/jwt/decode.rb

      token.header['alg']
    end
+
+    def allow_duplicate_keys?(options)


I have the urge not to add features to the old API anymore. Could we try that and document how to use this feature using the new EncodedToken class.

I've added instructions for use. How does that look?

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.

…dToken API

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.

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

I updated this PR. WDYT?

anakinj · 2026-02-03T19:30:05Z

lib/jwt/json.rb

  # @api private
  class JSON
    class << self
+      # Generates a JSON string from the given data


As these apis are marked private and pretty self-explanatory I would not bother having detailed comments on them.

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,

anakinj · 2026-02-03T19:33:31Z

lib/jwt/encoded_token.rb

+    # @return [self]
+    # @raise [JWT::DuplicateKeyError] if duplicate keys are found during subsequent parsing.
+    def raise_on_duplicate_keys!
+      @allow_duplicate_keys = false


Could we here detect if the JSON gem is supporting the feature and raise if we are not compatible? Would allow us to support older Ruby versions still.

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 🤔

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

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

anakinj reviewed Jan 29, 2026

View reviewed changes

ydah added 2 commits January 30, 2026 18:49

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

71b43ea

…dToken API

Update Ruby version requirements and modify CI configurations

11450ac

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

ydah added 2 commits February 4, 2026 23:23

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

7925810

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

Remove verbose YARD documentation comments from JWT::JSON class

189507f

Add duplicate claim name detection per RFC 7519 Section 4 #713

Are you sure you want to change the base?

Add duplicate claim name detection per RFC 7519 Section 4 #713

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!

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!

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!

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!

ydah commented Jan 30, 2026

Uh oh!

Choose a reason for hiding this comment

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!

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!

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 Feb 3, 2026 •

edited

Loading