Creating a Spring Security Key for Signing a JWT Token

1. Overview

JSON Web Tokens (JWT) is the de facto standard for securing a stateless application. The Spring Security framework provides methods of integrating JWT to secure REST APIs. One of the key processes of generating a token is applying a signature to guarantee authenticity.

In this tutorial, we’ll explore a stateless Spring Boot application that utilizes JWT authentication. We’ll set up the necessary components and create a cryptographic SecretKey instance to sign and verify the JWT.

2. Project Setup

To begin with, let’s bootstrap a stateless Spring Boot application with Spring Security and JWT token.

2.1. Maven Dependencies

First, let’s add the spring-boot-starter-web, spring-boot-starter-security, spring-boot-starter-data-jpa, and h2 database dependencies to the pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.2.3</version> 
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId> 
    <version>3.2.3</version> 
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
    <version>3.2.3</version>  
</dependency>
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <version>2.2.224</version>
</dependency>

The Spring Boot Starter Web provides API to build REST APIs. Also, the Spring Boot Starter Security dependency helps provide authentication and authorization. We add an in-memory database for fast prototyping.

Next, let’s add the jjwt-api, jjwt-impl and jjwt-jackson dependencies to the pom.xml:

<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-api</artifactId>
    <version>0.12.5</version>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-impl</artifactId>
    <version>0.12.5</version>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-jackson</artifactId>
    <version>0.12.5</version>
</dependency>

These dependencies provide an API to generate and sign a JWT and integrate it into Spring Security.

2.2. JWT Configuration

First, let’s create an authentication entry point:

@Component
class AuthEntryPointJwt implements AuthenticationEntryPoint {
    // ...
}

Here, we create a class to handle authorized access attempts in a Spring Security application using JWT authentication. It acts as a gatekeeper, ensuring only users with valid access can access protected resources.

Then, let’s create a class named AuthTokenFilter that intercepts incoming requests, validates JWT tokens, and authenticates users if a valid token is present:

class AuthTokenFilter extends OncePerRequestFilter {
    // ...
}

Finally, let’s create the JwtUtil class, which provides methods for creating and verifying tokens:

@Component
class JwtUtils {
    // ... 
}

This class contains the logic that uses the signWith() method.

2.3. Security Configuration

Finally, let’s define the SecurityConfiguration class and integrate the JWT:

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
class SecurityConfiguration {
    // ...
    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.csrf(AbstractHttpConfigurer::disable)
          .cors(AbstractHttpConfigurer::disable)
          .authorizeHttpRequests(req -> req.requestMatchers(WHITE_LIST_URL)
            .permitAll()
            .anyRequest()
            .authenticated())
          .exceptionHandling(ex -> ex.authenticationEntryPoint(unauthorizedHandler))
          .sessionManagement(session -> session.sessionCreationPolicy(STATELESS))
          .authenticationProvider(authenticationProvider())
          .addFilterBefore(
              authenticationJwtTokenFilter(), 
              UsernamePasswordAuthenticationFilter.class
           );
        return http.build();
    }
    // ...
}

In the code above, we integrate the JWT entry point and filter to activate JWT authentication.

3. The signWith() Method

The JJWT library provides a signWith() method to help sign a JWT with a specific cryptographic algorithm and a secret key. This signing process is essential for ensuring the integrity and authenticity of the JWT.

The signWith() method accepts the Key or SecretKey instances and signature algorithm as arguments. The Hash-based Message Authentication Code (HMAC) algorithm is among the most commonly used signing algorithms.

Importantly, the method requires a secret key, typically a byte array, for the signing process. We can use the Key or SecretKey instance to convert a secret string to a secret key.

Notably, we can pass an ordinary string as a secret key. However, this lacks the security guarantees and randomness of cryptographic Key or SecretKey instances.

Using the SecretKey instance ensures the integrity and authenticity of JWT.

4. Signing JWT

We can create a strong secret key to sign JWT using the Key and SecretKey instance.

4.1. Using Key Instance

Essentially, we can convert a secret string to a Key instance to further encrypt it before using it to sign JWT.

First, let’s ensure the secret string is Base64 encoded:

private String jwtSecret = "4261656C64756E67";

Next, let’s create a Key object:

private Key getSigningKey() {
    byte[] keyBytes = Decoders.BASE64.decode(this.jwtSecret);
    return Keys.hmacShaKeyFor(keyBytes);
}

In the code above, we decode the jwtSecret into a byte array. Next, we invoke the hmacShaKeyFor() which accepts keyBytes as a parameter on the Keys instance. This generates a secret key based on the HMAC algorithm.

In the case where the secret key is not Base64 encoded, we can invoke the getByte() method on the plain string:

private Key getSigningKey() {
    byte[] keyBytes = this.jwtSecret.getBytes(StandardCharsets.UTF_8);
    return Keys.hmacShaKeyFor(keyBytes);
}

However, this is not recommended because the secret may be poorly formed, and the string may contain non-UTF-8 characters. Hence, we must ensure the key string is Base64 encoded before generating a secret key from it.

4.2. Using SecretKey Instance

Also, we can form a strong secret key using the HMAC-SHA Algorithm to create a SecretKey instance. Let’s create a SecretKey instance that returns a secret key:

SecretKey getSigningKey() {
    return Jwts.SIG.HS256.key().build();
}

Here, we directly use the HMAC-SHA algorithm without using a byte array. This forms a strong signature key. Next, we can update the signWith() method by passing the getSigningKey() as an argument.

Alternatively, we can create a SecretKey instance from a Base16 encoded string:

SecretKey getSigningKey() {
    byte[] keyBytes = Decoders.BASE64.decode(jwtSecret);
    return Keys.hmacShaKeyFor(keyBytes);
}

This generates a strong SecretKey type to sign and verify JWT.

Notably, using the SecretKey instance over the Key instance is advisable because the new method named verifyWith() to verify the token accepts the SecretKey type as a parameter.

4.3. Applying the Key

Now, let’s apply the secret key to sign the JWT of our application:

String generateJwtToken(Authentication authentication) {
    UserDetailsImpl userPrincipal = (UserDetailsImpl) authentication.getPrincipal();
    return Jwts.builder()
      .subject((userPrincipal.getUsername()))
      .issuedAt(new Date())
      .expiration(new Date((new Date()).getTime() + jwtExpirationMs))
      .signWith(key)
      .compact();
}

The signWith() method takes the SecretKey instance as a parameter to append a unique signature to the token.

5. Conclusion

In this article, we learned how to create a secret key using the Java Key and SecretKey instance. Also, we saw a stateless Spring Boot application that utilizes a JWT token for token integrity and applies a Key or SecretKey instance to sign and verify it. Using a plain string is no longer advisable.

As always, the full source code for the example code is available over on GitHub.