Partner – Moderne – NPI EA (cat=Spring Boot)
announcement - icon

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Course – Black Friday 2026 – NPI EA – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

1. Overview

In this tutorial, we’ll explore how to effectively mock JWT (JSON Web Token) for unit testing Spring Security applications that use JWT authentication. Testing JWT-secured endpoints often requires simulating different JWT scenarios without relying on actual token generation or validation. This approach allows us to write robust unit tests without the complexity of managing real JWT tokens during testing.

Mocking JWT decoding is important in unit testing because it allows us to isolate the authentication logic from external dependencies, such as token generation services or third-party identity providers. By simulating different JWT scenarios, we can ensure that our application handles valid tokens, custom claims, invalid tokens, and expired tokens correctly.

We’ll learn how to use Mockito to mock the JwtDecoder, create custom JWT claims, and test various scenarios. By the end of this tutorial, we’ll be able to write comprehensive unit tests for Spring Security JWT-based authentication logic.

2. Setup and Configuration

Before we begin writing tests, let’s set up our testing environment with the necessary dependencies.

2.1. Dependencies

We’ll use Spring Security OAuth2, Mockito, and JUnit 5 for our tests:

<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-oauth2-jose</artifactId>
    <version>6.4.2</version>
</dependency>
<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-core</artifactId>
    <version>5.15.2</version>
    <scope>test</scope>
</dependency>

The spring-security-oauth2-jose dependency supports JWT in Spring Security, including the JwtDecoder interface, which is used to decode and validate JWTs. The mockito-core dependency allows us to mock dependencies in our tests, ensuring that we can isolate the unit under test, UserController,  from external systems.

2.2. Create UserController

Next, we’ll create UserController with the @GetMapping(“/user”) endpoint to retrieve user information based on a JWT token. It validates the token, checks for expiration, and extracts the user’s subject:

@GetMapping("/user")
public ResponseEntity<String> getUserInfo(@AuthenticationPrincipal Jwt jwt) {
    if (jwt == null || jwt.getSubject() == null) {
        throw new JwtValidationException("Invalid token", Arrays.asList(new OAuth2Error("invalid_token")));
    }

    Instant expiration = jwt.getExpiresAt();
    if (expiration != null && expiration.isBefore(Instant.now())) {
        throw new JwtValidationException("Token has expired", Arrays.asList(new OAuth2Error("expired_token")));
    }

    return ResponseEntity.ok("Hello, " + jwt.getSubject());
}

2.3. Setting up the Test Class

Let’s create a test class MockJwtDecoderJUnitTest and use Mockito to mock the JwtDecoder. Here’s the initial setup:

@ExtendWith(MockitoExtension.class)
public class MockJwtDecoderJUnitTest {
    @Mock
    private JwtDecoder jwtDecoder;

    @InjectMocks
    private UserController userController;

    @BeforeEach
    void setUp() {
        SecurityContextHolder.clearContext();
    }
}

In this setup, we use @ExtendWith(MockitoExtension.class) to enable Mockito in our JUnit tests. The JwtDecoder is mocked using @Mock, and the UserController is injected with the mocked JwtDecoder using @InjectMocks. The SecurityContextHolder is cleared before each test to ensure a clean state.

3. Mocking JWT Decoding

With our environment setup, we write tests to mock JWT decoding. We start by testing a valid JWT token.

3.1. Testing a Valid Token

The application should return the user information when a valid token is provided. Here’s how we test this scenario:

@Test
void whenValidToken_thenReturnsUserInfo() {
    Map<String, Object> claims = new HashMap<>();
    claims.put("sub", "john.doe");
    
    Jwt jwt = Jwt.withTokenValue("token")
      .header("alg", "none")
      .claims(existingClaims -> existingClaims.putAll(claims))
      .build();

    JwtAuthenticationToken authentication = new JwtAuthenticationToken(jwt);
    SecurityContextHolder.getContext().setAuthentication(authentication);

    ResponseEntity<String> response = userController.getUserInfo(jwt);
    
    assertEquals("Hello, john.doe", response.getBody());
    assertEquals(HttpStatus.OK, response.getStatusCode());
}

In this test, we create a mock JWT with a sub (subject) claim. The JwtAuthenticationToken is used to set up the security context, and the UserController processes the token and returns a response. We verify the response using assertions.

3.2. Testing Custom Claims

Sometimes, JWTs contain custom claims such as roles or email addresses. For example, if the UserController uses the roles claim to authorize access, the test should check that the controller behaves as expected based on the claimed roles:

@Test
void whenTokenHasCustomClaims_thenProcessesCorrectly() {
    Map<String, Object> claims = new HashMap<>();
    claims.put("sub", "john.doe");
    claims.put("roles", Arrays.asList("ROLE_USER", "ROLE_ADMIN"));
    claims.put("email", "[email protected]");

    Jwt jwt = Jwt.withTokenValue("token")
      .header("alg", "none")
      .claims(existingClaims -> existingClaims.putAll(claims))
      .build();

    List authorities = ((List) jwt.getClaim("roles"))
      .stream()
      .map(role -> new SimpleGrantedAuthority(role))
      .collect(Collectors.toList());

    JwtAuthenticationToken authentication = new JwtAuthenticationToken(
      jwt,
      authorities,
      jwt.getClaim("sub")
    );

    SecurityContextHolder.getContext().setAuthentication(authentication);

    ResponseEntity response = userController.getUserInfo(jwt);

    assertEquals("Hello, john.doe", response.getBody());
    assertEquals(HttpStatus.OK, response.getStatusCode());

    assertTrue(authentication.getAuthorities().stream()
      .anyMatch(auth -> auth.getAuthority().equals("ROLE_ADMIN")));
}

In this test, we verify that the roles claim is correctly processed and that the user has the expected authorities (in this case, ROLE_ADMIN).

4. Testing Other Scenarios

Next, we explore testing different cases.

4.1. Testing an Invalid Token

When an invalid token is provided, the application should throw a JwtValidationException. Let’s write a quick test to verify that the JwtDecoder properly throws an exception when attempting to decode an invalid token:

@Test
void whenInvalidToken_thenThrowsException() {
    Map<String, Object> claims = new HashMap<>();
    claims.put("sub", null);

    Jwt invalidJwt = Jwt.withTokenValue("invalid_token")
      .header("alg", "none")
      .claims(existingClaims -> existingClaims.putAll(claims))
      .build();

    JwtAuthenticationToken authentication = new JwtAuthenticationToken(invalidJwt);
    SecurityContextHolder.getContext()
      .setAuthentication(authentication);

    JwtValidationException exception = assertThrows(JwtValidationException.class, () -> {
      userController.getUserInfo(invalidJwt);
    });

    assertEquals("Invalid token", exception.getMessage());
}

In this test, we mock JwtDecoder to throw a JwtValidationException when a null token is processed.

The test asserts that a JwtValidationException is thrown with the message “Invalid token“.

4.2. Testing an Expired Token

When an expired token is provided, the application should throw a JwtValidationException. The test below verifies that the JwtDecoder properly throws an exception when attempting to decode an expired token:

@Test
void whenExpiredToken_thenThrowsException() throws Exception {
    Map<String, Object> claims = new HashMap<>();
    claims.put("sub", "john.doe");
    claims.put("exp", Instant.now().minus(1, ChronoUnit.DAYS));

    Jwt expiredJwt = Jwt.withTokenValue("expired_token")
      .header("alg", "none")
      .claims(existingClaims -> existingClaims.putAll(claims))
      .build();

    JwtAuthenticationToken authentication = new JwtAuthenticationToken(expiredJwt);
    SecurityContextHolder.getContext()
      .setAuthentication(authentication);
    JwtValidationException exception = assertThrows(JwtValidationException.class, () -> {
      userController.getUserInfo(expiredJwt);
    });

    assertEquals("Token has expired", exception.getMessage());
}

In this test, we set the expiration to 1 day in the past to simulate an expired token.

The test asserts that a JwtValidationException is thrown with the message “Token has expired“.

5. Conclusion

In this tutorial, we’ve learned how to mock JWT decoding in JUnit tests using Mockito. We covered various scenarios, including testing valid tokens with custom claims, handling invalid tokens, and managing expired tokens.

By mocking JWT decoding, we can write unit tests for spring security applications without relying on external token generation or validation services. This approach ensures that our tests are fast, reliable, and independent of external dependencies.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.
Partner – Moderne – NPI EA (tag=Refactoring)
announcement - icon

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.

Course – Black Friday 2026 – NPI EA – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

2 Comments
Oldest
Newest