Repository navigation
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This MR migrates JJWT's internal date/time handling from
java.util.Datetojava.time.Instant, and addsInstant-based alternatives to every public API that accepts or returns aDate:Claims,ClaimsMutator,JwtBuilderandJwtParserBuilder(exp,nbf,iatand therequire*assertions)ClockDateFormatsThe
Datevariants are deprecated and will be removed before the 1.0 release.The change is additive and binary compatible. All new interface methods have
defaultimplementations, and noexisting signature was removed or changed, so existing
Claims,ClaimsMutator,JwtParserBuilderandClockimplementations keep working. japicmp against
0.13.0reports only added methods for these types.The Jackson, Gson and org.json extensions can now also serialize
Instantvalues in custom claims.Motivation
java.util.Dateis widely considered bad practice in modern Java code:Dateinstances from getters such asClaims.getExpiration()and
FixedClock.now(), so callers could change internal state.toString()in the JVM's default timezone, mostly deprecated calendar methods, and relies on the non-thread-safe
SimpleDateFormatfor formatting andparsing. That is why
DateFormatsneededThreadLocalcaches, which are never cleaned up in pooled threads.seconds * 1000) and clock skew arithmetic onlongmillis couldoverflow silently and produce incorrect dates.
java.time.Instant(Java 8+) is immutable, thread-safe, has clear arithmetic and comparison methods, and fails faston out-of-range values. JJWT 0.14.0 already requires Java 8, so this is the natural time to move to
java.timewhile giving users a deprecation period before 1.0.
Changes
Public API (
jjwt-api)Claims: newdefaultmethodsexpiration(),notBefore()andissuedAt()returningInstant.getExpiration(),getNotBefore()andgetIssuedAt()are deprecated.ClaimsMutatorandJwtBuilder: newdefaultmethodsexpiration(Instant),notBefore(Instant)andissuedAt(Instant). TheDateoverloads are deprecated, and thesetXxx(Date)javadoc now points to theInstantvariants.JwtParserBuilder: newdefaultmethodsrequireExpiration(Instant),requireNotBefore(Instant)andrequireIssuedAt(Instant). TheDateoverloads are deprecated.Clock: newdefault Instant instant(), which returnsnow().toInstant().Date now()is deprecated, but itstays the only abstract method until 1.0, so existing implementations and lambdas (
() -> new Date()) stillcompile and work.
DateFormats:formatIso8601(Instant),formatIso8601(Instant, boolean)andparseIso8601Instant(String), built onimmutable, thread-safe
DateTimeFormatterinstances.formatIso8601(Date, ...)now delegates to theInstantvariant.parseIso8601Datekeeps its lenientSimpleDateFormatbehavior. It now creates a new instance per call insteadof caching it in a
ThreadLocal, which fixes Sonarjava:S5164.Datevariants are deprecated.Implementation (
jjwt-impl)JwtInstantConverter: the converter for RFC 7519 NumericDate values. It readsexp/nbf/iatnumbers asseconds, and accepts
Instant,Date,Calendar, numeric strings and ISO-8601 strings. Out-of-range valuesthrow
IllegalArgumentExceptioninstead of overflowing.Parameters:rfcDate()was replaced byrfc(), which returns aParameter<Instant>.DefaultClaims:exp,nbfandiatare now stored asInstant.Dategetters return a newDatecopy on each call.get(name, Date.class)converts the storedInstantdirectly. Without this, the raw value in seconds would beread as milliseconds and produce a date in 1970.
get(name, Instant.class).DelegatingClaimsMutator,DefaultJwtBuilderandDefaultJwtParserBuilder: theInstantmethods hold thelogic, and the deprecated
Dateoverloads convert their argument and call them. Internal calls to deprecatedsetters were also replaced.
DefaultJwtParser:exp/nbfvalidation now uses onlyClock.instant(), truncated to milliseconds so the clock skew logic and theerror messages stay unchanged.
longoverflow innbfvalidation that occurred with a very large allowed clock skew.require(name, Instant)now converts the actual claim value before comparing it. Previously it never matched.DefaultClock:instant()returnsInstant.now(), andnow()returnsDate.from(instant()).FixedClock: stores anInstantinternally. AddedFixedClock(Instant), deprecatedFixedClock(Date), andnow()returns a newDatecopy on each call.JwtDateConverter: reduced to the statictoDate(Object)method, which the deprecatedClaims.get(name, Date.class)path still needs because it parses ISO-8601 strings leniently.JSON extensions
Instantvalues in custom claims are serialized as ISO-8601 strings with millisecond precision(e.g.
"2026-10-03T10:00:00.123Z"), the same format used forDate. They can be read back withClaims.get(name, Instant.class). Before this change, all three extensions threw an exception when serializing anInstant.jjwt-jackson:JacksonInstantSerializerandJacksonInstantDeserializer, sojackson-datatype-jsr310isnot required. The deserializer also makes
JacksonDeserializerclaim type maps work withInstant.class.ObjectMapper, never on an application-provided one, so an existingJavaTimeModuleconfiguration is not overridden.jjwt-gson: new publicGsonInstantTypeAdapter, registered on the defaultGsoninstance. Users with a customGsoninstance can register it themselves.jjwt-orgjson:OrgJsonSerializersupportsInstant.Behavior changes (documented in the CHANGELOG)
nullliteral ambiguity: calls such asbuilder.expiration(null)ornew FixedClock(null)no longer compile,because both a
Dateand anInstantoverload now exist. Use an explicit cast, e.g.expiration((Instant) null).The ambiguity disappears when the
Datevariants are removed.exp,nbfandiatvalues outside the supported range now fail during parsing insteadof silently overflowing.
IncorrectClaimException.getClaimValue(): returns anInstantfor failedexp/nbf/iatassertions, and theexception message shows the value in ISO-8601 format.
Cannot create Date from ...is nowCannot create Instant from ..., and ISO-8601 parse errors now come fromDateTimeFormatter.DateFormatsoutput:formatIso8601(Date)uses the proleptic Gregorian calendar for dates before 1582-10-15,and adds a
+prefix to years after 9999. Output is unchanged for all other dates.Build
pom.xml:jjwt.previousVersionchanged from0.11.2to0.13.0, so the japicmp report only lists changes introduced inthis release.
ignoreMissingClassesByRegularExpressionsentry forio.jsonwebtoken.lang.Supplier. That classwas renamed to
ConfidentialValueearlier in 0.14.0, and without this entry japicmp can't loadjjwt-gson0.13.0'sGsonSupplierSerializerfor comparison.Documentation
CHANGELOG.md: newjava.time.InstantSupport and Behavior Changes sections under 0.14.0.README.adoc:Instant.Clock.Instantwas added to the list of automatically converted claim types.Instanthandling for Jackson and Gson.Testing
JwtInstantConverterTest,DefaultClockTestandGsonInstantTypeAdapterTest.ClaimsTest,ClaimsMutatorTest,ClockTest,JwtBuilderTest,JwtParserBuilderTestandDateFormatsTest.JwtParserTest,DefaultJwtBuilderTest,FixedClockTestandJwtDateConverterTest.Instantoverload;get("exp", Date.class)regression;Clockwhosenow()throws, to verify the parser only callsinstant();require(name, Instant);DateFormatsoutput identical to the previousSimpleDateFormatimplementation;ObjectMapperkeeping its ownInstanthandling.Date-based tests were kept, because they cover the deprecated API../mvnw clean verifypasses, with japicmp enabled, across all modules: api 153, jackson 32, orgjson 66,gson 29, impl 1555 and tdjar 20 tests.
Contributed by: Jose Caselles Sanchez from @ Dempo