feat: implement self-contained JWT authentication for Phase 1 (#2)

apenlor · web-flow · commit 3e77215a71ab · 2025-08-01T12:29:00.000+02:00
### Lab Phase &amp; Objective

This PR completes **Phase 1: The Standalone Secure Monolith**.

The objective is to establish a robust security baseline for a standalone REST API. The service is responsible for both authenticating users and issuing its own JSON Web Tokens (JWTs) without any external identity providers.

### Key Architectural Decisions &amp; Trade-offs

- **Custom JWT Filter Pattern:** Adopted a custom `JwtAuthenticationFilter` extending `OncePerRequestFilter`. This provides explicit, granular control over the token validation lifecycle, which is the canonical pattern for a self-contained JWT system. It avoids configuration conflicts present in other approaches.

- **`io.jsonwebtoken` (`jjwt`) Library:** Chose the `jjwt` library for token generation and parsing. Its fluent, purpose-built API is the industry standard for this task. All token-related logic is encapsulated in a dedicated `TokenService` to adhere to the Single Responsibility Principle.

- **Delegation to `AuthenticationManager`:** The `AuthController` does not handle credential validation directly. It correctly delegates this responsibility to Spring Security's `AuthenticationManager`, which is configured with our `UserDetailsService` and `PasswordEncoder`. This decouples the controller from the authentication mechanism.

- **Explicit `AuthenticationEntryPoint`:** Configured a `HttpStatusEntryPoint(HttpStatus.UNAUTHORIZED)` in the security chain. This is the correct, modern way to ensure that authentication failures in a stateless API return a semantically correct `401 Unauthorized` status code.

### Verification Strategy

- [x] **Unit/Integration Tests:** All new and existing tests pass via `./mvnw clean verify`. Key test classes:
    - `com.apenlor.lab.resourceserver.controller.ApiControllerTests`
    - `com.apenlor.lab.resourceserver.controller.AuthControllerTests`
- [ ] **Docker Compose:** N/A. Deferred to Phase 2, where containerization is a primary objective.
- [x] **Manual Verification:** The application can be run locally with `./mvnw -pl resource-server spring-boot:run`. The following flow can be used to manually verify:

  1.  **Get a token:**
      ```bash
      TOKEN=$(curl -s -X POST http://localhost:8081/auth/login \
      -H "Content-Type: application/json" \
      -d '{"username":"user", "password":"password"}' | jq -r .jwtToken)
      ```
  2.  **Access the public endpoint (succeeds):**
      ```bash
      curl http://localhost:8081/api/public/info
      ```
  3.  **Access the secure endpoint without a token (fails with 401):**
      ```bash
      curl -i http://localhost:8081/api/secure/data
      ```
  4.  **Access the secure endpoint with the token (succeeds):**
      ```bash
      curl http://localhost:8081/api/secure/data -H "Authorization: Bearer $TOKEN"
      ```

### Definition of Done Checklist

- [x] The PR title follows the Conventional Commits specification (e.g., `feat: ...`, `fix: ...`).
- [x] The code adheres to SOLID principles and project conventions.
- [x] The `README.md` has been updated to reflect the new state of the project.
- [x] All new logic is covered by automated tests.
- [x] Security implications of the changes have been considered.
- [ ] Observability implications (metrics, logs, traces) have been considered. *(N/A for this phase)*
diff --git a/pom.xml b/pom.xml
@@ -34,6 +34,17 @@
     </dependencyManagement>
 
     <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.14.0</version>
+                <configuration>
+                    <source>${java.version}</source>
+                    <target>${java.version}</target>
+                </configuration>
+            </plugin>
+        </plugins>
         <pluginManagement>
             <plugins>
                 <plugin>
diff --git a/resource-server/pom.xml b/resource-server/pom.xml
@@ -24,10 +24,21 @@
             <artifactId>spring-boot-starter-security</artifactId>
         </dependency>
 
-        <!-- OAuth2 / JWT Support -->
+        <!-- JWT Support -->
         <dependency>
-            <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
+            <groupId>io.jsonwebtoken</groupId>
+            <artifactId>jjwt-api</artifactId>
+            <version>0.12.6</version>
+        </dependency>
+        <dependency>
+            <groupId>io.jsonwebtoken</groupId>
+            <artifactId>jjwt-impl</artifactId>
+            <version>0.12.6</version>
+        </dependency>
+        <dependency>
+            <groupId>io.jsonwebtoken</groupId>
+            <artifactId>jjwt-jackson</artifactId>
+            <version>0.12.6</version>
         </dependency>
 
         <!-- Test dependencies -->
diff --git a/resource-server/src/main/java/com/apenlor/lab/resourceserver/config/ApplicationConfig.java b/resource-server/src/main/java/com/apenlor/lab/resourceserver/config/ApplicationConfig.java
@@ -0,0 +1,61 @@
+package com.apenlor.lab.resourceserver.config;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.authentication.AuthenticationManager;
+import org.springframework.security.authentication.ProviderManager;
+import org.springframework.security.authentication.dao.DaoAuthenticationProvider;
+import org.springframework.security.core.userdetails.User;
+import org.springframework.security.core.userdetails.UserDetailsService;
+import org.springframework.security.crypto.factory.PasswordEncoderFactories;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.security.provisioning.InMemoryUserDetailsManager;
+
+@Configuration
+public class ApplicationConfig {
+
+    /**
+     * Creates a PasswordEncoder bean that uses a delegating strategy. This standard
+     * allows for multiple encoding algorithms to coexist (e.g., bcrypt, scrypt).
+     *
+     * @return A PasswordEncoder instance.
+     */
+    @Bean
+    public PasswordEncoder passwordEncoder() {
+        return PasswordEncoderFactories.createDelegatingPasswordEncoder();
+    }
+
+    /**
+     * Defines the user details service that provides user information to Spring Security.
+     * For Phase 1, we use a simple in-memory user.
+     *
+     * @param passwordEncoder The password encoder to use for encoding the user's password.
+     * @return A UserDetailsService instance.
+     */
+    @Bean
+    public UserDetailsService userDetailsService(PasswordEncoder passwordEncoder) {
+        // --- Architectural Note: In-Memory User Store ---
+        // For this lab phase, we define a single user in memory. The password is
+        // encoded using the application's standard PasswordEncoder. In a production
+        // scenario, this would be replaced with a database-backed UserDetailsService.
+        var user = User.withUsername("user")
+                .password(passwordEncoder.encode("password"))
+                .authorities("read", "write").build();
+        return new InMemoryUserDetailsManager(user);
+    }
+
+    /**
+     * Defines the AuthenticationManager, which is the core of Spring Security's
+     * authentication mechanism. It processes an authentication request.
+     *
+     * @param userDetailsService The service to load user-specific data.
+     * @param passwordEncoder    The encoder to use for password verification.
+     * @return An AuthenticationManager instance.
+     */
+    @Bean
+    public AuthenticationManager authenticationManager(UserDetailsService userDetailsService, PasswordEncoder passwordEncoder) {
+        var authProvider = new DaoAuthenticationProvider(userDetailsService);
+        authProvider.setPasswordEncoder(passwordEncoder);
+        return new ProviderManager(authProvider);
+    }
+}
diff --git a/resource-server/src/main/java/com/apenlor/lab/resourceserver/config/JwtAuthenticationFilter.java b/resource-server/src/main/java/com/apenlor/lab/resourceserver/config/JwtAuthenticationFilter.java
@@ -0,0 +1,80 @@
+package com.apenlor.lab.resourceserver.config;
+
+import com.apenlor.lab.resourceserver.service.TokenService;
+import io.jsonwebtoken.JwtException;
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.lang.NonNull;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.security.core.userdetails.UserDetails;
+import org.springframework.security.core.userdetails.UserDetailsService;
+import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
+import org.springframework.web.filter.OncePerRequestFilter;
+
+import java.io.IOException;
+
+/**
+ * Custom JWT authentication filter that runs once per request.
+ * This filter is responsible for validating the JWT from the Authorization header
+ * and setting the user's authentication in the Spring Security context.
+ */
+public class JwtAuthenticationFilter extends OncePerRequestFilter {
+
+    private static final Logger log = LoggerFactory.getLogger(JwtAuthenticationFilter.class);
+
+    private final TokenService tokenService;
+    private final UserDetailsService userDetailsService;
+
+    public JwtAuthenticationFilter(TokenService tokenService, UserDetailsService userDetailsService) {
+        this.tokenService = tokenService;
+        this.userDetailsService = userDetailsService;
+    }
+
+    @Override
+    protected void doFilterInternal(
+            @NonNull HttpServletRequest request,
+            @NonNull HttpServletResponse response,
+            @NonNull FilterChain filterChain) throws ServletException, IOException {
+
+        final String authHeader = request.getHeader("Authorization");
+        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
+            filterChain.doFilter(request, response);
+            return;
+        }
+
+        final String jwt = authHeader.substring(7);
+
+        try {
+            final String username = tokenService.getUsernameFromToken(jwt);
+
+            // If a username is extracted and the user is not already authenticated in the current context
+            if (username != null && SecurityContextHolder.getContext().getAuthentication() == null) {
+                // Load the user details from the database in real world (or in-memory store for our lab)
+                UserDetails userDetails = this.userDetailsService.loadUserByUsername(username);
+
+                // Validate the token against the user details
+                if (tokenService.isTokenValid(jwt, userDetails.getUsername())) {
+                    // Create an authentication token for the user
+                    UsernamePasswordAuthenticationToken authToken = new UsernamePasswordAuthenticationToken(
+                            userDetails,
+                            null,
+                            userDetails.getAuthorities()
+                    );
+                    // Add details from the current request to the authentication token
+                    authToken.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
+                    SecurityContextHolder.getContext().setAuthentication(authToken);
+                    log.info("Authenticated user '{}', setting security context", username);
+                }
+            }
+        } catch (JwtException e) {
+            log.warn("JWT token processing failed: {}", e.getMessage());
+        }
+
+        filterChain.doFilter(request, response);
+    }
+}
diff --git a/resource-server/src/main/java/com/apenlor/lab/resourceserver/config/SecurityConfig.java b/resource-server/src/main/java/com/apenlor/lab/resourceserver/config/SecurityConfig.java
@@ -0,0 +1,57 @@
+package com.apenlor.lab.resourceserver.config;
+
+import com.apenlor.lab.resourceserver.service.TokenService;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.http.HttpStatus;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
+import org.springframework.security.config.http.SessionCreationPolicy;
+import org.springframework.security.core.userdetails.UserDetailsService;
+import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.security.web.authentication.HttpStatusEntryPoint;
+import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
+
+@Configuration
+@EnableWebSecurity
+public class SecurityConfig {
+
+    private final TokenService tokenService;
+    private final UserDetailsService userDetailsService;
+
+    public SecurityConfig(TokenService tokenService, UserDetailsService userDetailsService) {
+        this.tokenService = tokenService;
+        this.userDetailsService = userDetailsService;
+    }
+
+    /**
+     * Defines the main security filter chain for the application. This bean is the primary
+     * point of configuration for all security aspects of the web layer.
+     *
+     * @param http The HttpSecurity object to configure.
+     * @return The configured SecurityFilterChain.
+     * @throws Exception If an error occurs during configuration.
+     */
+    @Bean
+    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
+        return http
+                // Disable CSRF protection, as it's not needed for stateless, token-based APIs.
+                .csrf(AbstractHttpConfigurer::disable)
+                // Configure authorization rules for all incoming HTTP requests.
+                .authorizeHttpRequests(auth -> auth
+                        // Allow unauthenticated access to the public info and login endpoints.
+                        .requestMatchers("/api/public/info", "/auth/login").permitAll()
+                        // All other requests must be authenticated.
+                        .anyRequest().authenticated())
+                // Add our custom JWT filter before the standard UsernamePasswordAuthenticationFilter.
+                .addFilterBefore(new JwtAuthenticationFilter(tokenService, userDetailsService), UsernamePasswordAuthenticationFilter.class)
+                // Configure auth exceptions to return 401 Unauthorized response.
+                .exceptionHandling(exceptions -> exceptions
+                        .authenticationEntryPoint(new HttpStatusEntryPoint(HttpStatus.UNAUTHORIZED))
+                )
+                // Configure session management to be stateless.
+                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)).build();
+    }
+
+}
diff --git a/resource-server/src/main/java/com/apenlor/lab/resourceserver/controller/ApiController.java b/resource-server/src/main/java/com/apenlor/lab/resourceserver/controller/ApiController.java
@@ -0,0 +1,25 @@
+package com.apenlor.lab.resourceserver.controller;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.Authentication;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/api")
+public class ApiController {
+
+    @GetMapping("/public/info")
+    public ResponseEntity<String> getPublicInfo() {
+        String body = "This is PUBLIC information. Anyone can see this.";
+        return ResponseEntity.ok(body);
+    }
+
+    @GetMapping("/secure/data")
+    public ResponseEntity<String> getSecureData(Authentication authentication) {
+        String username = authentication.getName();
+        String body = String.format("This is SECURE data for user: %s. You should only see this if you are authenticated.", username);
+        return ResponseEntity.ok(body);
+    }
+}
diff --git a/resource-server/src/main/java/com/apenlor/lab/resourceserver/controller/AuthController.java b/resource-server/src/main/java/com/apenlor/lab/resourceserver/controller/AuthController.java
@@ -0,0 +1,48 @@
+// File: resource-server/src/main/java/com/apenlor/lab/resourceserver/controller/AuthController.java
+
+package com.apenlor.lab.resourceserver.controller;
+
+import com.apenlor.lab.resourceserver.dto.LoginRequest;
+import com.apenlor.lab.resourceserver.dto.LoginResponse;
+import com.apenlor.lab.resourceserver.service.TokenService;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.authentication.AuthenticationManager;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.Authentication;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * Controller responsible for handling user authentication and issuing JWTs.
+ */
+@RestController
+@RequestMapping("/auth")
+public class AuthController {
+
+    private final AuthenticationManager authenticationManager;
+    private final TokenService tokenService;
+
+    public AuthController(AuthenticationManager authenticationManager, TokenService tokenService) {
+        this.authenticationManager = authenticationManager;
+        this.tokenService = tokenService;
+    }
+
+    /**
+     * Handles the login request from a user.
+     *
+     * @param loginRequest The request body containing username and password.
+     * @return A ResponseEntity containing the JWT if authentication is successful.
+     */
+    @PostMapping("/login")
+    public ResponseEntity<LoginResponse> login(@RequestBody LoginRequest loginRequest) {
+        Authentication authentication = authenticationManager.authenticate(
+                new UsernamePasswordAuthenticationToken(loginRequest.username(), loginRequest.password())
+        );
+        
+        String token = tokenService.generateToken(authentication);
+
+        return ResponseEntity.ok(new LoginResponse(token));
+    }
+}
diff --git a/resource-server/src/main/java/com/apenlor/lab/resourceserver/dto/LoginRequest.java b/resource-server/src/main/java/com/apenlor/lab/resourceserver/dto/LoginRequest.java
@@ -0,0 +1,10 @@
+package com.apenlor.lab.resourceserver.dto;
+
+/**
+ * Represents the data structure for a login request.
+ *
+ * @param username The user's username.
+ * @param password The user's password.
+ */
+public record LoginRequest(String username, String password) {
+}
diff --git a/resource-server/src/main/java/com/apenlor/lab/resourceserver/dto/LoginResponse.java b/resource-server/src/main/java/com/apenlor/lab/resourceserver/dto/LoginResponse.java
@@ -0,0 +1,9 @@
+package com.apenlor.lab.resourceserver.dto;
+
+/**
+ * Represents the data structure for a successful login response.
+ *
+ * @param jwtToken The generated JSON Web Token.
+ */
+public record LoginResponse(String jwtToken) {
+}
diff --git a/resource-server/src/main/java/com/apenlor/lab/resourceserver/service/TokenService.java b/resource-server/src/main/java/com/apenlor/lab/resourceserver/service/TokenService.java
diff --git a/resource-server/src/main/resources/application.properties b/resource-server/src/main/resources/application.properties
diff --git a/resource-server/src/test/java/com/apenlor/lab/resourceserver/controller/ApiControllerTests.java b/resource-server/src/test/java/com/apenlor/lab/resourceserver/controller/ApiControllerTests.java
diff --git a/resource-server/src/test/java/com/apenlor/lab/resourceserver/controller/AuthControllerTests.java b/resource-server/src/test/java/com/apenlor/lab/resourceserver/controller/AuthControllerTests.java
