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. 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 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-api</artifactId>
<version>0.12.3</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 = SignatureAlgorithm.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.
Now that we have the signature algorithm and secret key, we can begin to perform the verification.
JwtParser jwtParser = Jwts.parser()
.verifyWith(secretKeySpec)
.build();
try {
jwtParser.parse(token);
} catch (Exception e) {
throw new Exception("Could not verify JWT token integrity!", e);
}
Let’s break this down.
First, we create a JwtParser with the chosen algorithm and secret. Then we parse the token with the JwtParser. The inner implementation of the parse method 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. If any exception is thrown, it means that the token is not valid (it can be malformed, expired, etc).
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.
