JSON Web Token or JWT has been famous as a way to communicate securely between services. There are two form of JWT, JWS and JWE. The difference between them is that JWS' payload is not encrypted while JWE is.
This article will explore the implementation of the JWT in Java Spring Boot. If you want to learn more about the JWT itself, you can visit my other article here.
The code in this article is hosted on the following GitHub repository: https://github.com/brilianfird/jwt-demo.
Library
For this article, we will use the jose4j
library. jose4j
is one of the popular JWT libraries in Java and has a full feature. If you want to check out other libraries (whether it's for Java or not), jwt.io has compiled a list of them.
<dependency>
<groupId>org.bitbucket.b_c</groupId>
<artifactId>jose4j</artifactId>
<version>0.7.12</version>
</dependency>
Implementing JWS in Java
JSON Web Signature (JWS) consists of three parts:
- JOSE Header
- Payload
- Signature
Let's see an example of the JOSE header:
{
alg:"HS264"
}
JOSE header store the metadata about how to handle the JWS.
alg
stores information about which signing algorithm the JWT uses.
Next, let's check the payload:
{
"sub": "1234567890",
"name": "Brilian Firdaus",
"iat": 1651422365
}
JSON payload stores the data that we want to transmit to the client. It also stores some JWT claims for information purposes that we can verify.
In the example above, we have three fields registered as JWT claims.
-
sub
indicates the user's unique id -
name
indicates the name of the user -
iat
indicates when we created the JWT in an epoch
The last part is the signature, which is the one that makes JWS secure. Usually, the signature of the JWS will be in the form of bytes. Let's see an example of a Base64 Encoded signature:
qsg3HKPxM96PeeXl-sMrao00yOh1T0yQfZa-BsrtjHI
Now, if we see the three parts above, you might wonder how to transfer those three parts seamlessly to the consumer. The answer is with compact serialization. Using compact serialization, we can easily share the JWS with the consumer because the JWS will become one long string.
Base64.encode(JOSE Header) + "." + Base64.encode(Payload) + "." + Base64.encode(signature)
The result will be:
eyJhbGciOiJIUzI1NiIsImtpZCI6IjIwMjItMDUtMDEifQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkJyaWxpYW4gRmlyZGF1cyIsImlhdCI6MTY1MTQyMjM2NX0.qsg3HKPxM96PeeXl-sMrao00yOh1T0yQfZa-BsrtjHI
The compact serialization part is also mandatory in the JWT specification. So for a JWS to be considered a JWT, we must do a compact serialization.
Unprotected
The first type of JWS we will explore is an unprotected JWS. People rarely use his type of JWS (Basically just a regular JSON), but let's explore this first to understand the base of the implementation.
Let's start by creating the header. Unlike the previous example where we used the HS256
algorithm, now we will use no algorithm.
Producing Unprotected JWS
@Test
public void JWS_noAlg() throws Exception {
JwtClaims jwtClaims = new JwtClaims();
jwtClaims.setSubject("7560755e-f45d-4ebb-a098-b8971c02ebef"); // set sub
jwtClaims.setIssuedAtToNow(); // set iat
jwtClaims.setExpirationTimeMinutesInTheFuture(10080); // set exp
jwtClaims.setIssuer("https://codecurated.com"); // set iss
jwtClaims.setStringClaim("name", "Brilian Firdaus"); // set name
jwtClaims.setStringClaim("email", "brilianfird@gmail.com");//set email
jwtClaims.setClaim("email_verified", true); //set email_verified
JsonWebSignature jws = new JsonWebSignature();
jws.setAlgorithmConstraints(AlgorithmConstraints.NO_CONSTRAINTS);
jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.NONE);
jws.setPayload(jwtClaims.toJson());
String jwt = jws.getCompactSerialization(); //produce eyJ.. JWT
System.out.println("JWT: " + jwt);
}
Let's see what we did in the code.
- We set a bunch of claims (
sub
,iat
,exp
,iss
,name
,email
,email_verified
) - We set the signing algorithm to
NONE
and the algorithm constraint toNO_CONSTRAINT
becausejose4j
will throw an exception because the algorithm lack security - We packaged JWS in the compact serialization, which will produce one string containing the JWS. The result is a JWT complied String.
Let's see what output we get by calling the jws.getCompactSerialization()
:
eyJhbGciOiJub25lIn0.eyJzdWIiOiI3NTYwNzU1ZS1mNDVkLTRlYmItYTA5OC1iODk3MWMwMmViZWYiLCJpYXQiOjE2NTI1NTYyNjYsImV4cCI6MTY1MzE2MTA2NiwiaXNzIjoiaHR0cHM6Ly9jb2RlY3VyYXRlZC5jb20iLCJuYW1lIjoiQnJpbGlhbiBGaXJkYXVzIiwiZW1haWwiOiJicmlsaWFuZmlyZEBnbWFpbC5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZX0.
If we try to decode it, we'll get the JWS with fields that we set before:
{
"header": {
"alg": "none"
},
"payload": {
"sub": "7560755e-f45d-4ebb-a098-b8971c02ebef",
"iat": 1652556266,
"exp": 1653161066,
"iss": "https://codecurated.com",
"name": "Brilian Firdaus",
"email": "brilianfird@gmail.com",
"email_verified": true
}
}
We've successfully created a JWT with Java's jose4j
library! Now, let's proceed to the JWT-consuming process.
To consume the JWT, we can use the JwtConsumer
class in the jose4j
library. Let's see an example:
@Test
public void JWS_consume() throws Exception {
String jwt = "eyJhbGciOiJub25lIn0.eyJzdWIiOiI3NTYwNzU1ZS1mNDVkLTRlYmItYTA5OC1iODk3MWMwMmViZWYiLCJpYXQiOjE2NTI1NTYyNjYsImV4cCI6MTY1MzE2MTA2NiwiaXNzIjoiaHR0cHM6Ly9jb2RlY3VyYXRlZC5jb20iLCJuYW1lIjoiQnJpbGlhbiBGaXJkYXVzIiwiZW1haWwiOiJicmlsaWFuZmlyZEBnbWFpbC5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZX0.";
JwtConsumer jwtConsumer = new JwtConsumerBuilder()
// required for NONE alg
.setJwsAlgorithmConstraints(AlgorithmConstraints.NO_CONSTRAINTS)
// disable signature requirement
.setDisableRequireSignature()
// require the JWT to have iat field
.setRequireIssuedAt()
// require the JWT to have exp field
.setRequireExpirationTime()
// expect the iss to be https://codecurated.com
.setExpectedIssuer("https://codecurated.com")
.build();
// process JWT to jwt context
JwtContext jwtContext = jwtConsumer.process(jwt);
// get JWS object
JsonWebSignature jws = (JsonWebSignature)jwtContext.getJoseObjects().get(0);
// get claims
JwtClaims jwtClaims = jwtContext.getJwtClaims();
// print claims as map
System.out.println(jwtClaims.getClaimsMap());
}
By using JwtConsumer
, we can easily make rules about what to validate when processing incoming JWT. It also provides an easy way to get the JWS Object and the claims by using .getJoseObjects()
and getJwtClaims()
, respectively.
Now that we know how to produce and consume JWT without a signing algorithm, it will be much easier to understand the one with it. The difference is that we need to set the algorithm and create a key(s) to generate/validate the JWT.
HMAC SHA-256
HMAC SHA-256(HS256
) is a MAC function with a symmetric key. We will need to generate at least 32 bytes for its secret key and feed it to the HmacKey
class in the jose4j
library to ensure security.
We'll use the SecureRandom
library in Java to ensure the key randomity.
byte[] key = new byte[32];
SecureRandom secureRandom = new SecureRandom();
secureRandom.nextBytes(key);
HmacKey hmacKey = new HmacKey(key);
The secret key should be considered as a credential, hence it should be stored in a secure environment. For recommendation, you can store it as a environment variable or in Vault.
Let's see how to create and consume the JWT signed with HS256
:
@Test
public void JWS_HS256() throws Exception {
// generate key
byte[] key = new byte[32];
SecureRandom secureRandom = new SecureRandom();
secureRandom.nextBytes(key);
HmacKey hmacKey = new HmacKey(key);
JwtClaims jwtClaims = new JwtClaims();
jwtClaims.setSubject("7560755e-f45d-4ebb-a098-b8971c02ebef"); // set sub
jwtClaims.setIssuedAtToNow(); // set iat
jwtClaims.setExpirationTimeMinutesInTheFuture(10080); // set exp
jwtClaims.setIssuer("https://codecurated.com"); // set iss
jwtClaims.setStringClaim("name", "Brilian Firdaus"); // set name
jwtClaims.setStringClaim("email", "brilianfird@gmail.com");//set email
jwtClaims.setClaim("email_verified", true); //set email_verified
JsonWebSignature jws = new JsonWebSignature();
// Set alg header as HMAC_SHA256
jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.HMAC_SHA256);
// Set key to hmacKey
jws.setKey(hmacKey);
jws.setPayload(jwtClaims.toJson());
String jwt = jws.getCompactSerialization(); //produce eyJ.. JWT
// we don't need NO_CONSTRAINT and disable require signature anymore
JwtConsumer jwtConsumer = new JwtConsumerBuilder()
.setRequireIssuedAt()
.setRequireExpirationTime()
.setExpectedIssuer("https://codecurated.com")
// set the verification key
.setVerificationKey(hmacKey)
.build();
// process JWT to jwt context
JwtContext jwtContext = jwtConsumer.process(jwt);
// get JWS object
JsonWebSignature consumedJWS = (JsonWebSignature)jwtContext.getJoseObjects().get(0);
// get claims
JwtClaims consumedJWTClaims = jwtContext.getJwtClaims();
// print claims as map
System.out.println(consumedJWTClaims.getClaimsMap());
// Assert header, key, and claims
Assertions.assertEquals(jws.getAlgorithmHeaderValue(), consumedJWS.getAlgorithmHeaderValue());
Assertions.assertEquals(jws.getKey(), consumedJWS.getKey());
Assertions.assertEquals(jwtClaims.toJson(), consumedJWTClaims.toJson());
}
There isn't much difference in the code compared to creating a JWS without a signing algorithm. We first made the key using SecureRandom
and HmacKey
classes. Since HS256
uses a symmetric key, we only need one key that we will use to sign and verify the JWT.
We also set the algorithm header value to HS256
by using jws.setAlgorithmheaderValue(AlgorithmIdentifiers.HMAC_SHA256
and the key with jws.setKey(hmacKey)
.
In the JWT consumer, we only need to set the HMAC key by using .setVerificationKey(hmacKey)
on the jwtConsumer
object jose4j
will automatically determine which algorithm is used in the JWS by parsing its JOSE header.
ES256
Unlike the HS256
that only needs one key, we need to generate two keys for the ES256
algorithm, private and public keys.
We can use the private key to create and verify the JWT, while we can only use public keys to verify the JWT. Due to those traits, a private key is usually stored as a credential, while a public key can be hosted in public as JWK so the consumer of the JWT can query the host and get the key by themself.
jose4j
library provides a simple API to generate private and public keys as a JWK.
EllipticCurveJsonWebKey ellipticCurveJsonWebKey = EcJwkGenerator.generateJwk(EllipticCurves.P256);
// get private key
ellipticCurveJsonWebKey.getPrivateKey();
// get public key
ellipticCurveJsonWebKey.getECPublicKey();
Now that we know how to generate the key creating the JWT with the ES256
algorithm is almost the same as creating a JWT with the HS256
algorithm.
...
JsonWebSignature jws = new JsonWebSignature();
// Set alg header as ECDSA_USING_P256_CURVE_AND_SHA256
jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.ECDSA_USING_P256_CURVE_AND_SHA256);
// Set key to the generated private key
jws.setKey(ellipticCurveJsonWebKey.getPrivateKey());
jws.setPayload(jwtClaims.toJson());
...
JwtConsumer jwtConsumer = new JwtConsumerBuilder()
.setRequireIssuedAt()
.setRequireExpirationTime()
.setExpectedIssuer("https://codecurated.com")
// set the verification key as the public key
.setVerificationKey(ellipticCurveJsonWebKey.getECPublicKey())
.build();
...
The only different things are:
- We set the algorithm header as
ECDSA_USING_P256_CURVE_AND_SHA256
- We use the private key when creating the JWT
- We use the public key for verifying the JWT
Hosting JWK
We can easily create JSON Web Key Set using the JsonWebKeySet
class.
@GetMapping("/jwk")
public String jwk() throws JoseException {
// Create public key and private key pair
EllipticCurveJsonWebKey ellipticCurveJsonWebKey = EcJwkGenerator.generateJwk(EllipticCurves.P256);
// Create JsonWebkeySet object
JsonWebKeySet jsonWebKeySet = new JsonWebKeySet();
// Add the public key to the JsonWebKeySet object
jsonWebKeySet.addJsonWebKey(ellipticCurveJsonWebKey);
// toJson() method by default won't host the private key
return jsonWebKeySet.toJson();
}
We also need to change some properties of the key resolver:
// Define verification key resolver
HttpsJwks httpsJkws = new HttpsJwks("http://localhost:8080/jwk");
HttpsJwksVerificationKeyResolver verificationKeyResolver =
new HttpsJwksVerificationKeyResolver(httpsJkws);
JwtConsumer jwtConsumer = new JwtConsumerBuilder()
.setRequireIssuedAt()
.setRequireExpirationTime()
.setExpectedIssuer("https://codecurated.com")
// set verification key resolver
.setVerificationKeyResolver(verificationKeyResolver)
.build();
Since we hosted the JSON Web Key Set, we need to query the host. jose4j
is also providing a simple way to do this by using HttpsJwksVerificationKeyResolver
.
Implementing JWE in Java
JSON Web Encryption, unlike JWS, is a type of JWT that is encrypted so that no one can see its content except the one with the private key. First, let's see an example of it.
eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkExMjhDQkMtSFMyNTYiLCJlcGsiOnsia3R5IjoiRUMiLCJ4IjoiMEdxMEFuWUk1RVFxOUVZYjB4dmxjTGxKanV6ckxhSjhUYUdHYzk5MU9sayIsInkiOiJya1Q2cjlqUWhjRU1xaGtubHJ6S0hVemFKMlhWakFpWGpIWGZYZU9aY0hRIiwiY3J2IjoiUC0yNTYifX0.DUrC7Y_ejpt1n9c8wXetwU65sxkEYxG6RBsCUdokVODJBtwypL9VjQ.ydZx-UDWDN7jbGeESXvPHg.6ksHUeeGgGj0txFNXmsSQUCnAv52tJuGR5vgrX54vnLkryPFv2ATdLwYXZz3mAjeDes4s9otz4-Fzg1IBZ4qsfCVa6_3CVdkb8BTU4OvQx23SFEgtj8zh-8ZrqZbpKIT.p-E09mQIleNCCmwX3YL-uQ
The structure of the JWE is:
BASE64URL(UTF8(JWE Protected Header)) || ’.’ ||
BASE64URL(JWE Encrypted Key) || ’.’ ||
BASE64URL(JWE Initialization Vector) || ’.’ ||
BASE64URL(JWE Ciphertext) || ’.’ ||
BASE64URL(JWE Authentication Tag)
And if we decrypt the JWE, we will get the following claims:
{
"iss":"https://codecurated.com",
"exp":1654274573,
"iat":1654256573,
"sub":"12345"
}
Now, let's see how we create the JWE:
@Test
public void JWE_ECDHES256() throws Exception {
// Determine signature algorithm and encryption algorithm
String alg = KeyManagementAlgorithmIdentifiers.ECDH_ES_A256KW;
String encryptionAlgorithm = ContentEncryptionAlgorithmIdentifiers.AES_128_CBC_HMAC_SHA_256;
// Generate EC JWK
EllipticCurveJsonWebKey ecJWK = EcJwkGenerator.generateJwk(EllipticCurves.P256);
// Create
JwtClaims jwtClaims = new JwtClaims();
jwtClaims.setIssuer("https://codecurated.com");
jwtClaims.setExpirationTimeMinutesInTheFuture(300);
jwtClaims.setIssuedAtToNow();
jwtClaims.setSubject("12345");
// Create JWE
JsonWebEncryption jwe = new JsonWebEncryption();
jwe.setPlaintext(jwtClaims.toJson());
// Set JWE's signature algorithm and encryption algorithm
jwe.setAlgorithmHeaderValue(alg);
jwe.setEncryptionMethodHeaderParameter(encryptionAlgorithm);
// Unlike JWS, to create the JWE we use the public key
jwe.setKey(ecJWK.getPublicKey());
String compactSerialization = jwe.getCompactSerialization();
System.out.println(compactSerialization);
// Create JWT Consumer
JwtConsumer jwtConsumer =
new JwtConsumerBuilder()
// We set the private key as decryption key
.setDecryptionKey(ecJWK.getPrivateKey())
// JWE doesn't have signature, so we disable it
.setDisableRequireSignature()
.build();
// Get the JwtContext of the JWE
JwtContext jwtContext = jwtConsumer.process(compactSerialization);
System.out.println(jwtContext.getJwtClaims());
}
The main difference between creating and consuming JWE compared to JWS are:
- We use a public key as the encryption key and a private key as the decryption key
- We don't have a signature in JWE, so the consumer will need to skip the signature requirement
Conclusion
In this article, we've learned to create both JWS and JWE in Java using jose4j
. Hopefully, this article is useful to you. If you want to learn more about the concept of JWT, you can visit my other article.
Top comments (0)