Check JWT Expiry Without Throwing Exceptions

1. Introduction

A JWT (JSON Web Token) is basically a JSON Object which is used to transfer information over the web securely. This information can be verified and trusted because it’s digitally signed.

In this tutorial, we’ll first look at the difference between verifying a JWT and decoding a JWT. We’ll then learn how to check for a JWT’s expiry without throwing any exceptions in Java.

2. Difference Between Verifying and Decoding a JWT

Before we start looking at how we can check for a JWT’s expiry, let’s first understand some of the fundamentals.

As we know, a JWT in its compact form is a Base64-encoded string containing three parts: the header, the payload, and the signature. Anyone accessing a JWT can easily decode it and view its contents. Hence, to trust a token, it’s essential that we verify the signature contained within the JWT.

There are various Java JWT libraries available to create and manage JWTs. We’ll be using the Auth0 JWT Java Library for our code examples. It’s an easy-to-use library for creating and managing JWTs.

2.1. Dependencies

To get started, we add the Auth0 Java JWT library’s Maven dependency to our project’s pom.xml file:

<dependency>
    <groupId>com.auth0</groupId>
    <artifactId>java-jwt</artifactId>
    <version>4.2.1</version>
</dependency>

Next, let’s understand the difference between decoding and verifying a JWT.

2.2. Decoding a JWT

We can decode a JWT by simply Base64-decoding its various parts. Decoding a JWT returns the decoded payload without verifying if the JWT signature is valid. This operation is not recommended to be used for any untrusted messages and is merely used for viewing the JWT contents.

To decode a JWT, we use the JWT.decode(String) method. This method parses the JWT and returns an instance of DecodedJWT.

The DecodedJWT instance provides various convenience methods that we can use to fetch the data contained in the JWT. If the JWT is not a valid Base64-encoded string, the method throws a JWTDecodeException.

Let’s take a look at the code to decode a JWT:

try {
    DecodedJWT decodedJWT = JWT.decode(jwtString);
    return decodedJWT;
} catch (JWTDecodeException e) {
    // ...
}

Once we obtain an instance of the DecodedJWT instance, we can use its various getter methods to obtain the decoded data.

For example, to obtain the token expiry time, we use the DecodedJWT.getExpiresAt() method. This method returns an instance of a java.util.Date containing the token expiry time:

Date expiresAt = decodedJWT.getExpiresAt();

Next, let’s have a look at the JWT verification operation.

2.3. Verifying a JWT

Verifying the JWT ensures that the contained signature is valid. Optionally, it also checks for expiry time, not-valid-before time, issuer, audience, or any other claims if the JWT contains any.

To verify a JWT, we use the JWTVerifier.verify(String) method. The verification operation also returns an instance of DecodedJWT if the signature is valid. Only when both – the signature and all the claims are valid it returns the decoded JWT. If the signature is invalid or if any of the claim validations fail, it throws a JWTVerificationException.

Let’s check the code to verify a JWT:

try {
    DecodedJWT decodedJWT = verifier.verify(jwtString);
} catch (JWTVerificationException e) {
    // ...
}

It’s clear from the above code snippet that the verify() method throws an exception if the JWT isn’t valid. Since the method also decodes the token after verification, it provides a safer and more secure way to decode the token. The decode() method, on the other hand, simply decodes the provided JWT token. Hence, for verifying the expiry time of a token without throwing any exceptions, we use the JWT.decode() method.

3. Checking JWT Expiry

To simply read the data contained in the JWT, we can decode the JWT and parse the data. Let’s have a look at the Java code to check whether a JWT has expired:

boolean isJWTExpired(DecodedJWT decodedJWT) {
    Date expiresAt = decodedJWT.getExpiresAt();
    return expiresAt.before(new Date());
}

As mentioned earlier, we use the DecodedJWT.getExpiresAt() method to obtain the expiry time of a JWT. We then match the expiry time with the current time to check whether the token has expired.

The JWT.decode() method and the JWTVerifier.verify() method both return an instance of DecodedJWT. The only difference is that the verify() method also checks the signature for validity and returns an exception if invalid. Hence, we must only use the decode() method for trusted messages. For any untrusted messages, we should always use the verify() method, which ensures a valid signature and any other claims within those JWTs.

4. Conclusion

In this article, we first looked at the difference between JWT decode and JWT verification operations.

We then looked at how the decode operation is used to check for JWT’s expiry without throwing any exceptions.