Security Top

I just announced the new Learn Spring Security course, including the full material focused on the new OAuth2 stack in Spring Security 5:

>> CHECK OUT THE COURSE
REST Top

Get started with Spring 5 and Spring Boot 2, through the reference Learn Spring course:

>> CHECK OUT THE COURSE

1. Overview

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

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

2. Structure of a JWT

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

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

The signature is optional. A valid JWT 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 base64url-encoded strings separated by a period (‘.') delimiter. By design, anyone can decode a JWT and read the contents of the header and payload sections. But 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 validate a token in Java.

3. Decoding a JWT

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 two or three elements corresponding to the sections of the JWT.

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

Base64.Decoder decoder = Base64.getUrlDecoder();

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

Let's run this code with a JWT (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, we are finished and have the information decoded successfully.

4. Verifying JWT

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 that 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, we have verified the integrity of the header and payload.

5. Conclusion

In this article, 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 article can be found over on GitHub.

Security bottom

I just announced the new Learn Spring Security course, including the full material focused on the new OAuth2 stack in Spring Security 5:

>> CHECK OUT THE COURSE
REST bottom

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course :

>> CHECK OUT THE COURSE
REST footer banner
Comments are closed on this article!