Decode a JWT Token in Java

1. Overview

A JSON Web Token (JWT) is often used in REST API security. Though the token can be parsed by frameworks such as Spring Security OAuth, we may wish to process the token in our own code.

In this tutorial, we'll decode and verify the integrity of a JWT.

2. Structure of JWT Token

First, let's understand the structure of a JWT token:

• header
• payload (often referred to as body)
• signature

The signature is optional. A valid JWT token can consist of just the header and payload sections. However, we use the signature section to verify the contents of the header and payload for security authorization.

Sections are represented as base64 encoded strings separated by a period (‘.') delimiter. By design, anyone can decode a JWT token and read the contents of the header and payload sections. However, we need access to the secret key used to create the signature to verify a token's integrity.

Most commonly, the JWT contains a user's “claims”. These represent data about the user, which the API can use to grant permissions or trace the user providing the token. Decoding the token allows the application to use the data, and validation allows the application to trust that the JWT was generated by a trusted source.

Let's look at how we can decode and valid a token in Java.

3. Decoding a JWT Token

We can decode a token using built-in Java functions.

First, let's split up the token into its sections:

String[] chunks = token.split("\\.");

We should note that the regular expression passed to String.split uses an escaped ‘.' character to avoid ‘.' meaning “any character”.

Our chunks array should now have 2 or 3 elements corresponding to the sections of the JWT.

Next, let's decode the header and payload parts using a base64 decoder:

Base64.Decoder decoder = Base64.getDecoder();
String header = new String(decoder.decode(chunks[0]));
String payload = new String(decoder.decode(chunks[1]));

Let's run this code with a JWT token (we can decode online to compare results):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkJhZWxkdW5nIFVzZXIiLCJpYXQiOjE1MTYyMzkwMjJ9.qH7Zj_m3kY69kxhaQXTa-ivIpytKXXjZc1ZSmapZnGE

The output will give us the decoded header any payload:

{"alg":"HS256","typ":"JWT"}{"sub":"1234567890","name":"Baeldung User","iat":1516239022}

If only the header and payload sections are defined in a JWT token, then we are finished and have the information decoded successfully.

4. Verifying JWT Token

Next, we can verify the integrity of the header and payload to ensure that they have not been altered by using the signature section.

4.1. Dependencies

For the verification, we can add jjwt to our pom.xml:

<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt</artifactId>
    <version>0.7.0</version>
</dependency>

We should note that we need a version of this library from version 0.7.0 onwards.

4.2. Configuring Signature Algorithm and Key Specification

To begin verifying the payload and header, we need both the signature algorithm that was used originally to sign the token and the secret key:

SignatureAlgorithm sa = HS256;
SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), sa.getJcaName());

In this example, we've hard-coded our signature algorithm to HS256. However, we could decode the JSON of the header and read the alg field to get this value.

We should also note that the variable secretKey is a String representation of the secret key. We might provide this to our application via its configuration or via a REST API exposed by the service which issues the JWT.

4.3. Performing The Verification

Now that we have the signature algorithm and secret key, we can begin to perform the verification. Let's recombine the header and payload into an unsigned JWT, joining them with the ‘.' delimiter:

String tokenWithoutSignature = chunks[0] + "." + chunks[1];
String signature = chunks[2];

Now we have the unsigned token and the provided signature. We can use the library to validate it:

DefaultJwtSignatureValidator validator = new DefaultJwtSignatureValidator(sa, secretKeySpec);
if (!validator.isValid(tokenWithoutSignature, signature)) {
    throw new Exception("Could not verify JWT token integrity!");
}

Let's break this down.

First, we create a validator with the chosen algorithm and secret. Then we provide it the unsigned token data and the provided signature.

Then. the validator generates a fresh signature and compares it against the provided signature. If they are equal, then we have verified the integrity of the header and payload.

5. Conclusion

In this tutorial, we looked at the structure of a JWT and how to decode it into JSON.

Then we used a library to verify the integrity of a token using its signature, algorithm, and secret key.

As always, the code examples from this tutorial can be found over on GitHub.