Skip to content

Allow a leeway to be given for the iat claim verification - #747

Merged
anakinj merged 3 commits into
jwt:mainfrom
denis1011101:add-iat-leeway
Sep 5, 2026
Merged

Allow a leeway to be given for the iat claim verification#747
anakinj merged 3 commits into
jwt:mainfrom
denis1011101:add-iat-leeway

Conversation

@denis1011101

Copy link
Copy Markdown
Contributor

Adds an optional leeway to the iat verification. Refs #353.

Right now iat is compared exactly against the local clock, so a token gets
rejected as soon as the issuer's clock is slightly ahead of the verifier's.
There's no way to allow for that: the global leeway doesn't apply to this
claim, and iat_leeway was dropped in 2.2.0.

In #353 (comment) anakinj
suggested keeping the comparison exact and letting the caller say how much drift
is acceptable, so that's what this does:

JWT.decode(token, secret, true, verify_iat: { leeway: 30 }, algorithm: 'HS256')
JWT::Claims.verify_payload!(payload, iat: { leeway: 30 })

It defaults to 0, so nothing changes for existing code. The value is read from
the claim's own options, as in that comment, which keeps the old iat_leeway
name out of the API.

Refs rather than Closes, since the default behaviour stays as it was.

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

The iat claim is verified with an exact comparison against the local
clock, so a token is rejected whenever the clock of the issuer is even
marginally ahead of the clock of the verifier. There was no way to
tolerate that drift: the global leeway option does not apply to this
claim and iat_leeway was removed in 2.2.0.

Accept a leeway for the claim, defaulting to 0 so that the current
behaviour is unchanged, and keep the comparison exact:

  JWT.decode(token, secret, true, verify_iat: { leeway: 30 })
  JWT::Claims.verify_payload!(payload, iat: { leeway: 30 })

Refs jwt#353
@anakinj

anakinj commented Sep 2, 2026

Copy link
Copy Markdown
Member

Thanks, I like this approach — opt-in per-claim keeps the default strict, and I confirmed verify_iat: true still rejects a future iat.

iat: true raises TypeError via dig, but so do exp: true and nbf: true today. Consistent, so I'll fix all three separately.

Two optional nits:

  • README.md:535 still says leeway isn't taken into account for this claim — readers will stop there and miss your new snippet below.
  • Boundary cases in issued_at_spec.rb sit well inside/outside the window; exactly at the edge and one second past would catch a > vs >= slip.

Clarify the README and add specs for values at and just beyond the allowed boundary.
@denis1011101

Copy link
Copy Markdown
Contributor Author

Thanks! Addressed both nits in 11226259:

  • Updated the README wording. I also moved the leeway and iat_leeway notes out of the RFC blockquote since they aren't part of RFC 7519;

  • Added boundary specs at the exact limit and one second past it, with and without leeway.

The latest workflow run is waiting for approval.

@anakinj
anakinj merged commit 232b855 into jwt:main Sep 5, 2026
15 checks passed
@anakinj

anakinj commented Sep 5, 2026

Copy link
Copy Markdown
Member

Thank you @denis1011101 for the contribution.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants