Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,71 @@

The first JJWT release that uses Java 8+ features. This release is not strictly backwards compatible and will also not work with Java 7.

#### `java.time.Instant` Support

JJWT now uses `java.time.Instant` internally for all date/time values, and the following `Instant` methods have been added:

- `Claims`: `expiration()`, `notBefore()` and `issuedAt()`.
- `ClaimsMutator` (and therefore `JwtBuilder` and `ClaimsBuilder`): `expiration(Instant)`, `notBefore(Instant)` and `issuedAt(Instant)`.
- `JwtParserBuilder`: `requireExpiration(Instant)`, `requireNotBefore(Instant)` and `requireIssuedAt(Instant)`.
- `Clock`: `instant()`. JJWT's `JwtParser` now only calls `Clock.instant()` to obtain the current time.
- `DateFormats`: `formatIso8601(Instant)`, `formatIso8601(Instant, boolean)` and `parseIso8601Instant(String)`.
- `FixedClock` (`jjwt-impl`): `FixedClock(Instant)`.
- `Claims.get(claimName, Instant.class)` and `JwtParserBuilder.require(claimName, anInstant)` now convert claim values
to `Instant` using the same heuristics as `Date` (`Number` values are interpreted as milliseconds, and ISO-8601
strings are supported).

`Instant` values in custom claims are serialized as ISO-8601 strings with millisecond precision (e.g.
`"2026-10-03T10:00:00.123Z"`), consistent with how `Date` values are represented, and can be read back via
`Claims.get(claimName, Instant.class)`:

- `jjwt-jackson`: JJWT's default `ObjectMapper` (de)serializes `Instant` values without requiring the
`jackson-datatype-jsr310` module, so a `JacksonDeserializer` claim type map can also specify `Instant.class`. An
application-provided `ObjectMapper` is not modified, so any `java.time` configuration it already has (e.g.
`JavaTimeModule`) is retained.
- `jjwt-gson`: JJWT's default `Gson` instance registers the new `GsonInstantTypeAdapter`. If you provide your own
`Gson` instance, register it via `gsonBuilder.registerTypeAdapter(Instant.class, GsonInstantTypeAdapter.INSTANCE)`.
- `jjwt-orgjson`: `Instant` values are supported automatically.

All new methods are additive, and those that are `interface` methods have `default` implementations, so existing
`Claims`, `ClaimsMutator`, `JwtParserBuilder` and `Clock` implementations continue to work without changes.

The equivalent `java.util.Date` methods (`getExpiration()`, `expiration(Date)`, `requireExpiration(Date)`,
`Clock.now()`, `DateFormats.formatIso8601(Date)`, `FixedClock(Date)`, etc) are now deprecated and will be removed
before the JJWT 1.0 release.

`Clock.now()` remains the only abstract `Clock` method until it is removed, so existing `Clock` implementations and
lambdas (e.g. `() -> new Date()`) remain compatible. New implementations should override `instant()` and implement
`now()` as `return Date.from(instant());`.

#### Behavior Changes

- Passing a `null` literal to a method that now has both `Date` and `Instant` overloads no longer compiles because
the call is ambiguous, for example `builder.expiration(null)` or `new FixedClock(null)`. Use an explicit cast
instead, e.g. `builder.expiration((Instant) null)`. This ambiguity will disappear when the `Date` methods are removed.
- Out-of-range `exp`, `nbf` and `iat` values now result in an exception during parsing instead of silently
overflowing to an incorrect date.
- A very large allowed clock skew (via `JwtParserBuilder.clockSkewSeconds`) no longer overflows during `nbf` validation,
which previously caused tokens within the allowed skew to be rejected as premature.
- `IncorrectClaimException.getClaimValue()` now returns an `Instant` (instead of a `Date`) when a `requireExpiration`,
`requireNotBefore` or `requireIssuedAt` assertion fails, and the exception message renders that value in
ISO-8601 format (e.g. `2026-10-03T10:00:00Z`) instead of `Date.toString()` format.
- Some exception messages produced when `exp`, `nbf` or `iat` values cannot be converted have changed. For example
`Cannot create Date from object of type ...` is now `Cannot create Instant from object of type ...`, and the cause
of an invalid ISO-8601 string is now reported by `java.time.format.DateTimeFormatter` (e.g.
`Text '-42-' could not be parsed at index 1`) instead of `java.text.SimpleDateFormat`
(e.g. `Unparseable date: "-42-"`).
- `Claims.getExpiration()`, `getNotBefore()` and `getIssuedAt()` and `FixedClock.now()` now return a new `Date`
instance on each invocation, so the returned instance can no longer be used to mutate internal state.
- `DateFormats.formatIso8601(Date)` and `formatIso8601(Date, boolean)` now delegate to their `Instant` equivalents.
Output is unchanged for any date between the Gregorian calendar cutover (`1582-10-15`) and the year `9999`.
Earlier dates are now formatted using the proleptic Gregorian calendar as required by ISO-8601 (instead of the
Julian calendar), and years after `9999` are prefixed with a `+` sign (e.g. `+10000-01-01T00:00:00.000Z`).
This also affects custom `Date` claims serialized by the `jjwt-orgjson` extension.
- `DateFormats.parseIso8601Instant` is strict: out-of-range field values (e.g. month `13`), trailing characters, and
millisecond notation other than exactly three digits are rejected. The deprecated `parseIso8601Date` method retains
its existing lenient behavior.

#### Backwards Compatibility Breaking Changes

- The `io.jsonwebtoken.lang.Supplier` interface has been renamed and moved to `io.jsonwebtoken.security.ConfidentialValue` to avoid any potential risk of conflict or accidental use
Expand Down
79 changes: 69 additions & 10 deletions README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -628,6 +628,14 @@ dependencies {
Android projects will want to define the following dependencies and Proguard exclusions, and optional
BouncyCastle `Provider`:

[NOTE]
====
JJWT uses `java.time.Instant` for date/time values, which is natively available on Android API level 26 (Android 8.0)
and later. If your application supports earlier API levels, enable
https://developer.android.com/studio/write/java8-support#library-desugaring[Java 8+ API desugaring support] in your
Android build.
====

+++<a name="install-android-dependencies">++++++</a>+++

==== Dependencies
Expand Down Expand Up @@ -1063,14 +1071,24 @@ String jws = Jwts.builder()
.issuer("me")
.subject("Bob")
.audience().add("you").and()
.expiration(expiration) //a java.util.Date
.notBefore(notBefore) //a java.util.Date
.issuedAt(new Date()) // for example, now
.expiration(expiration) //a java.time.Instant
.notBefore(notBefore) //a java.time.Instant
.issuedAt(Instant.now()) // for example, now
.id(UUID.randomUUID().toString()) //just an example id

/// ... etc ...
----

[NOTE]
====
As of JJWT 0.14.0, the `expiration`, `notBefore` and `issuedAt` methods accept `java.time.Instant` values, and the
equivalent `Claims` accessors are `expiration()`, `notBefore()` and `issuedAt()`. The previous `java.util.Date`
variants (e.g. `expiration(Date)` and `getExpiration()`) are deprecated and will be removed before the 1.0 release.

Because both variants exist until then, passing a `null` literal is ambiguous and will not compile. Use an explicit
cast instead, for example `expiration((Instant) null)`.
====

+++<a name="jwt-claims-custom">++++++</a>++++++<a name="jws-create-claims-custom">++++++</a>+++
// legacy anchors for old links

Expand Down Expand Up @@ -1527,13 +1545,36 @@ during parsing for timestamp comparisons can be obtained via a custom time sourc
----
Clock clock = new MyClock();

Jwts.parser().clock(myClock) //... etc ...
Jwts.parser().clock(clock) //... etc ...
----

The ``JwtParser``'s default `Clock` implementation simply returns `new Date()` to reflect the time when parsing occurs,
as most would expect. However, supplying your own clock could be useful, especially when writing test cases to
The ``JwtParser``'s default `Clock` implementation simply returns `Instant.now()` to reflect the time when parsing
occurs, as most would expect. However, supplying your own clock could be useful, especially when writing test cases to
guarantee deterministic behavior.

The `JwtParser` obtains the current time by calling `Clock.instant()`, so custom implementations should override that
method. Until the deprecated `Clock.now()` method is removed before the 1.0 release, it is still the interface's only
abstract method, so implement it by delegating to `instant()`:

[,java]
----
public class MyClock implements Clock {

@Override
public Instant instant() {
return getMyTime(); //implement me
}

@Override
public Date now() { // deprecated, will be removed before 1.0
return Date.from(instant());
}
}
----

Existing `Clock` implementations (and lambdas) that only implement `now()` continue to work unchanged, since the
default `instant()` implementation returns `now().toInstant()`.

+++<a name="jwt-read-decompression">++++++</a>+++

=== JWT Decompression
Expand Down Expand Up @@ -3398,12 +3439,20 @@ Jwts.parser()
// ... etc ...
----

[NOTE]
====
JJWT's default `ObjectMapper` (de)serializes `java.time.Instant` values in custom claims as ISO-8601 strings
(e.g. `"2026-10-03T10:00:00.123Z"`) without requiring the `jackson-datatype-jsr310` module. If you provide your own
`ObjectMapper`, JJWT does not change its `java.time` handling, so if you use `Instant` values in custom claims, ensure
your `ObjectMapper` supports them (e.g. by registering Jackson's `JavaTimeModule`).
====

+++<a name="json-jackson-custom-types">++++++</a>+++

==== Parsing of Custom Claim Types

By default, JJWT will only convert simple claim types: String, Date, Long, Integer, Short and Byte. If you need to
deserialize other types you can configure the `JacksonDeserializer` by passing a `Map` of claim names to types in
By default, JJWT will only convert simple claim types: String, Date, Instant, Long, Integer, Short and Byte. If you
need to deserialize other types you can configure the `JacksonDeserializer` by passing a `Map` of claim names to types in
through a constructor. For example:

[,java]
Expand Down Expand Up @@ -3468,13 +3517,16 @@ If you're curious, JJWT will automatically create an internal default Gson insta
----
new GsonBuilder()
.registerTypeHierarchyAdapter(io.jsonwebtoken.security.ConfidentialValue.class, GsonConfidentialValueSerializer.INSTANCE)
.registerTypeAdapter(java.time.Instant.class, GsonInstantTypeAdapter.INSTANCE)
.setObjectToNumberStrategy(ToNumberPolicy.LONG_OR_DOUBLE)
.setNumberToNumberStrategy(ToNumberPolicy.LONG_OR_DOUBLE)
.disableHtmlEscaping()
.create();
----

The `registerTypeHierarchyAdapter` builder call is required to serialize JWKs with secret or private values.
The `registerTypeHierarchyAdapter` builder call is required to serialize JWKs with secret or private values. The
`registerTypeAdapter` call ensures `java.time.Instant` values in custom claims are serialized as ISO-8601 strings
(e.g. `"2026-10-03T10:00:00.123Z"`).

However, if you prefer to use a different Gson instance instead of JJWT's default, you can configure JJWT to use your
own - just *don't forget to register the necessary JJWT type hierarchy adapter*.
Expand Down Expand Up @@ -3511,6 +3563,8 @@ And then you can specify the `GsonSerializer` using your own `Gson` instance on
Gson gson = new GsonBuilder()
// don't forget this line!:
.registerTypeHierarchyAdapter(io.jsonwebtoken.security.ConfidentialValue.class, GsonConfidentialValueSerializer.INSTANCE)
// and this one if you use java.time.Instant values in custom claims:
.registerTypeAdapter(java.time.Instant.class, GsonInstantTypeAdapter.INSTANCE)
.setObjectToNumberStrategy(ToNumberPolicy.LONG_OR_DOUBLE)
.setNumberToNumberStrategy(ToNumberPolicy.LONG_OR_DOUBLE)
.disableHtmlEscaping().create();
Expand Down Expand Up @@ -3542,7 +3596,12 @@ Again, as shown above, it is critical to create your `Gson` instance using the `
.registerTypeHierarchyAdapter(io.jsonwebtoken.security.ConfidentialValue.class, GsonConfidentialValueSerializer.INSTANCE)
----

to ensure JWK serialization works as expected.
to ensure JWK serialization works as expected. If you use `java.time.Instant` values in custom claims, also include:

[,java]
----
.registerTypeAdapter(java.time.Instant.class, GsonInstantTypeAdapter.INSTANCE)
----

+++<a name="base64">++++++</a>+++

Expand Down
63 changes: 62 additions & 1 deletion api/src/main/java/io/jsonwebtoken/Claims.java
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
*/
package io.jsonwebtoken;

import java.time.Instant;
import java.util.Date;
import java.util.Map;
import java.util.Set;
Expand Down Expand Up @@ -105,29 +106,89 @@ public interface Claims extends Map<String, Object>, Identifiable {
* <p>A JWT obtained after this timestamp should not be used.</p>
*
* @return the JWT {@code exp} value or {@code null} if not present.
* @deprecated since 0.14.0 in favor of {@link #expiration()}. This method will be removed before the
* JJWT 1.0 release.
*/
@Deprecated
Date getExpiration();

/**
* Returns the JWT <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.4">
* <code>exp</code></a> (expiration) timestamp or {@code null} if not present.
*
* <p>A JWT obtained after this timestamp should not be used.</p>
*
* <p>The default implementation returns {@code getExpiration().toInstant()} for compatibility with existing
* {@code Claims} implementations. Implementations are encouraged to override this method directly.</p>
*
* @return the JWT {@code exp} value or {@code null} if not present.
* @since 0.14.0
*/
default Instant expiration() {
Date date = getExpiration();
return date != null ? date.toInstant() : null;
}

/**
* Returns the JWT <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.5">
* <code>nbf</code></a> (not before) timestamp or {@code null} if not present.
*
* <p>A JWT obtained before this timestamp should not be used.</p>
*
* @return the JWT {@code nbf} value or {@code null} if not present.
* @deprecated since 0.14.0 in favor of {@link #notBefore()}. This method will be removed before the
* JJWT 1.0 release.
*/
@Deprecated
Date getNotBefore();

/**
* Returns the JWT <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.5">
* <code>nbf</code></a> (not before) timestamp or {@code null} if not present.
*
* <p>A JWT obtained before this timestamp should not be used.</p>
*
* <p>The default implementation returns {@code getNotBefore().toInstant()} for compatibility with existing
* {@code Claims} implementations. Implementations are encouraged to override this method directly.</p>
*
* @return the JWT {@code nbf} value or {@code null} if not present.
* @since 0.14.0
*/
default Instant notBefore() {
Date date = getNotBefore();
return date != null ? date.toInstant() : null;
}

/**
* Returns the JWT <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.6">
* <code>iat</code></a> (issued at) timestamp or {@code null} if not present.
*
* <p>If present, this value is the timestamp when the JWT was created.</p>
*
* @return the JWT {@code iat} value or {@code null} if not present.
* @deprecated since 0.14.0 in favor of {@link #issuedAt()}. This method will be removed before the
* JJWT 1.0 release.
*/
@Deprecated
Date getIssuedAt();

/**
* Returns the JWT <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.6">
* <code>iat</code></a> (issued at) timestamp or {@code null} if not present.
*
* <p>If present, this value is the timestamp when the JWT was created.</p>
*
* <p>The default implementation returns {@code getIssuedAt().toInstant()} for compatibility with existing
* {@code Claims} implementations. Implementations are encouraged to override this method directly.</p>
*
* @return the JWT {@code iat} value or {@code null} if not present.
* @since 0.14.0
*/
default Instant issuedAt() {
Date date = getIssuedAt();
return date != null ? date.toInstant() : null;
}

/**
* Returns the JWTs <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.7">
* <code>jti</code></a> (JWT ID) value or {@code null} if not present.
Expand All @@ -147,7 +208,7 @@ public interface Claims extends Map<String, Object>, Identifiable {
* Returns the JWTs claim ({@code claimName}) value as a {@code requiredType} instance, or {@code null} if not
* present.
*
* <p>JJWT only converts simple String, Date, Long, Integer, Short and Byte types automatically. Anything more
* <p>JJWT only converts simple String, Date, Instant, Long, Integer, Short and Byte types automatically. Anything more
* complex is expected to be already converted to your desired type by the JSON parser. You may specify a custom
* JSON processor using the {@code JwtParserBuilder}'s
* {@link JwtParserBuilder#json(io.jsonwebtoken.io.Deserializer) json(Deserializer)} method. See the JJWT
Expand Down
Loading