feat: add role-based authorization with JWT role claims

Agent-Logs-Url: https://github.com/vitorhugo-java/SpringBoot-JobApplyTracker/sessions/26afd256-5bd0-476c-910c-64e37aedb6aa

Co-authored-by: vitorhugo-java <65777252+vitorhugo-java@users.noreply.github.com>

Author: Copilot

README.md

@@ -8,7 +8,7 @@ A production-ready Spring Boot REST API for tracking job applications, built wit
 
 - **Java 21**
 - **Spring Boot 3.2** (Web, Data JPA, Security, Validation)
-- **Spring Security** with stateless JWT authentication
+- **Spring Security** with stateless JWT authentication + role-based authorization (`USER`, `BETA`, `ADMIN`)
 - **JWT + Refresh Tokens** (access: 15 min, refresh: 7 days with rotation)
 - **Resilience4j Rate Limiting** on auth endpoints
 - **MariaDB** (production) / **Testcontainers** (tests)
@@ -52,27 +52,38 @@ A production-ready Spring Boot REST API for tracking job applications, built wit
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| POST | `/api/auth/register` | Register a new user |
-| POST | `/api/auth/login` | Login and receive tokens |
-| POST | `/api/auth/refresh` | Refresh access token |
-| POST | `/api/auth/logout` | Logout and revoke refresh token |
-| POST | `/api/auth/forgot-password` | Request password reset |
-| POST | `/api/auth/reset-password` | Reset password with token |
-| GET | `/api/auth/me` | Get current user info |
+| POST | `/api/v1/auth/register` | Register a new user |
+| POST | `/api/v1/auth/login` | Login and receive tokens |
+| POST | `/api/v1/auth/refresh` | Refresh access token |
+| POST | `/api/v1/auth/logout` | Logout and revoke refresh token |
+| POST | `/api/v1/auth/forgot-password` | Request password reset |
+| POST | `/api/v1/auth/reset-password` | Reset password with token |
+| GET | `/api/v1/auth/me` | Get current user info |
 
 ### Applications
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| POST | `/api/applications` | Create application |
-| GET | `/api/applications` | List all (paginated + filterable) |
-| GET | `/api/applications/{id}` | Get by ID |
-| PUT | `/api/applications/{id}` | Full update |
-| PATCH | `/api/applications/{id}/status` | Update status |
-| PATCH | `/api/applications/{id}/reminder` | Toggle reminder |
-| DELETE | `/api/applications/{id}` | Delete |
-| GET | `/api/applications/upcoming` | Upcoming next steps |
-| GET | `/api/applications/overdue` | Overdue next steps |
+| POST | `/api/v1/applications` | Create application |
+| GET | `/api/v1/applications` | List all (paginated + filterable) |
+| GET | `/api/v1/applications/{id}` | Get by ID |
+| PUT | `/api/v1/applications/{id}` | Full update |
+| PATCH | `/api/v1/applications/{id}/status` | Update status |
+| PATCH | `/api/v1/applications/{id}/reminder` | Toggle reminder |
+| DELETE | `/api/v1/applications/{id}` | Delete |
+| GET | `/api/v1/applications/upcoming` | Upcoming next steps |
+| GET | `/api/v1/applications/overdue` | Overdue next steps |
+
+## Authorization Model
+
+- JWT access tokens now include a `roles` claim (e.g., `ROLE_USER`, `ROLE_ADMIN`).
+- Protected API routes require `ROLE_USER` (auth routes remain public).
+- A default `ROLE_USER` is assigned on registration.
+
+Flyway seeds the roles catalog (`USER`, `BETA`, `ADMIN`) and sample accounts:
+
+- `admin@jobtracker.local` / `Admin@1234` (`ROLE_ADMIN` + `ROLE_USER`)
+- `user@jobtracker.local` / `User@1234` (`ROLE_USER`)
 
 ### Gamification
 

docs/stories/role-based-authorization.md

@@ -0,0 +1,31 @@
+# Story: Role-based Authorization (USER, BETA, ADMIN)
+
+## Checklist
+
+- [x] Add Role entity/model and `User` ↔ `Role` many-to-many mapping
+- [x] Add `RoleRepository`
+- [x] Add Flyway migration for `roles`, `user_roles`, role seed, and sample admin/user assignments
+- [x] Include roles in JWT generation/parsing and authentication authorities
+- [x] Enforce baseline authorization (`ROLE_USER`) for protected API endpoints
+- [x] Add unit tests for JWT role claims and `UserDetailsService` role mapping
+- [x] Add integration test proving authenticated token without `ROLE_USER` is forbidden
+- [x] Update README with role-based auth and seeded account details
+
+## File List
+
+- `src/main/java/com/jobtracker/entity/enums/RoleName.java`
+- `src/main/java/com/jobtracker/entity/Role.java`
+- `src/main/java/com/jobtracker/entity/User.java`
+- `src/main/java/com/jobtracker/repository/RoleRepository.java`
+- `src/main/java/com/jobtracker/config/ApplicationConfig.java`
+- `src/main/java/com/jobtracker/config/JwtService.java`
+- `src/main/java/com/jobtracker/config/JwtAuthenticationFilter.java`
+- `src/main/java/com/jobtracker/config/SecurityConfig.java`
+- `src/main/java/com/jobtracker/service/AuthService.java`
+- `src/main/resources/db/migration/V11__add_roles_and_user_authorization.sql`
+- `src/test/java/com/jobtracker/unit/ApplicationConfigTest.java`
+- `src/test/java/com/jobtracker/unit/JwtServiceTest.java`
+- `src/test/java/com/jobtracker/unit/AuthServiceTest.java`
+- `src/test/java/com/jobtracker/integration/AuthControllerIT.java`
+- `README.md`
+- `docs/stories/role-based-authorization.md`

src/main/java/com/jobtracker/config/ApplicationConfig.java

@@ -6,11 +6,11 @@
 import org.springframework.security.authentication.AuthenticationManager;
 import org.springframework.security.authentication.dao.DaoAuthenticationProvider;
 import org.springframework.security.config.annotation.authentication.configuration.AuthenticationConfiguration;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
 import org.springframework.security.core.userdetails.UserDetailsService;
 import org.springframework.security.core.userdetails.UsernameNotFoundException;
 import org.springframework.security.crypto.password.PasswordEncoder;
-
-import java.util.Collections;
+import java.util.stream.Collectors;
 
 @Configuration
 public class ApplicationConfig {
@@ -27,7 +27,9 @@ public UserDetailsService userDetailsService() {
                 .map(user -> new org.springframework.security.core.userdetails.User(
                         user.getEmail(),
                         user.getPasswordHash(),
-                        Collections.emptyList()))
+                        user.getRoles().stream()
+                                .map(role -> new SimpleGrantedAuthority("ROLE_" + role.getName().name()))
+                                .collect(Collectors.toSet())))
                 .orElseThrow(() -> new UsernameNotFoundException("User not found: " + username));
     }
 

src/main/java/com/jobtracker/config/JwtAuthenticationFilter.java

@@ -53,7 +53,7 @@ protected void doFilterInternal(HttpServletRequest request,
 
                 if (userDetails != null && jwtService.isTokenValid(jwt, userDetails)) {
                     UsernamePasswordAuthenticationToken authToken = new UsernamePasswordAuthenticationToken(
-                            userDetails, null, userDetails.getAuthorities());
+                            userDetails, null, jwtService.extractAuthorities(jwt));
                     authToken.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
                     SecurityContextHolder.getContext().setAuthentication(authToken);
                 }

src/main/java/com/jobtracker/config/JwtService.java

@@ -4,18 +4,24 @@
 import io.jsonwebtoken.Jwts;
 import io.jsonwebtoken.security.Keys;
 import org.springframework.beans.factory.annotation.Value;
+import org.springframework.security.core.GrantedAuthority;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
 import org.springframework.security.core.userdetails.UserDetails;
 import org.springframework.stereotype.Service;
 
 import javax.crypto.SecretKey;
 import java.nio.charset.StandardCharsets;
+import java.util.Collection;
 import java.util.Date;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.function.Function;
+import java.util.stream.Collectors;
 
 @Service
 public class JwtService {
+    private static final String ROLES_CLAIM = "roles";
 
     @Value("${jwt.secret}")
     private String secretKey;
@@ -33,7 +39,11 @@ public <T> T extractClaim(String token, Function<Claims, T> claimsResolver) {
     }
 
     public String generateToken(UserDetails userDetails) {
-        return generateToken(new HashMap<>(), userDetails);
+        Map<String, Object> claims = new HashMap<>();
+        claims.put(ROLES_CLAIM, userDetails.getAuthorities().stream()
+                .map(GrantedAuthority::getAuthority)
+                .toList());
+        return generateToken(claims, userDetails);
     }
 
     public String generateToken(Map<String, Object> extraClaims, UserDetails userDetails) {
@@ -51,6 +61,18 @@ public boolean isTokenValid(String token, UserDetails userDetails) {
         return username.equals(userDetails.getUsername()) && !isTokenExpired(token);
     }
 
+    public Collection<SimpleGrantedAuthority> extractAuthorities(String token) {
+        Object rolesClaim = extractAllClaims(token).get(ROLES_CLAIM);
+        if (!(rolesClaim instanceof List<?> roleValues)) {
+            return List.of();
+        }
+        return roleValues.stream()
+                .filter(String.class::isInstance)
+                .map(String.class::cast)
+                .map(SimpleGrantedAuthority::new)
+                .collect(Collectors.toSet());
+    }
+
     private boolean isTokenExpired(String token) {
         return extractExpiration(token).before(new Date());
     }

src/main/java/com/jobtracker/config/SecurityConfig.java

@@ -38,12 +38,18 @@ public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Excepti
                 .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                 .authorizeHttpRequests(auth -> auth
                         .requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()
-                        .requestMatchers("/api/v1/auth/**").permitAll()
+                        .requestMatchers(HttpMethod.POST,
+                                "/api/v1/auth/register",
+                                "/api/v1/auth/login",
+                                "/api/v1/auth/refresh",
+                                "/api/v1/auth/forgot-password",
+                                "/api/v1/auth/reset-password",
+                                "/api/v1/auth/logout").permitAll()
                         .requestMatchers("/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html").permitAll()
                         // Actuator is served on a dedicated management port (8081) that is never
                         // exposed to the host; security is enforced via Docker network isolation.
                         .requestMatchers("/actuator/**").permitAll()
-                        .anyRequest().authenticated())
+                        .anyRequest().hasRole("USER"))
                 .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class)
                 .addFilterBefore(requestLoggingFilter, JwtAuthenticationFilter.class);
 

src/main/java/com/jobtracker/entity/Role.java

@@ -0,0 +1,36 @@
+package com.jobtracker.entity;
+
+import com.jobtracker.entity.enums.RoleName;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+
+@Entity
+@Table(name = "roles")
+public class Role {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false, unique = true, length = 20)
+    private RoleName name;
+
+    public Long getId() {
+        return id;
+    }
+
+    public RoleName getName() {
+        return name;
+    }
+
+    public void setName(RoleName name) {
+        this.name = name;
+    }
+}

src/main/java/com/jobtracker/entity/User.java

@@ -3,6 +3,8 @@
 import jakarta.persistence.*;
 import java.time.LocalTime;
 import java.time.LocalDateTime;
+import java.util.HashSet;
+import java.util.Set;
 import java.util.UUID;
 
 import org.hibernate.annotations.UuidGenerator;
@@ -36,6 +38,10 @@ public class User {
     @Column(name = "updated_at", nullable = false)
     private LocalDateTime updatedAt;
 
+    @ManyToMany(fetch = FetchType.EAGER)
+    @JoinTable(name = "user_roles", joinColumns = @JoinColumn(name = "user_id"), inverseJoinColumns = @JoinColumn(name = "role_id"))
+    private Set<Role> roles = new HashSet<>();
+
     @PrePersist
     protected void onCreate() {
         if (reminderTime == null) {
@@ -70,4 +76,7 @@ protected void onUpdate() {
 
     public LocalDateTime getUpdatedAt() { return updatedAt; }
     public void setUpdatedAt(LocalDateTime updatedAt) { this.updatedAt = updatedAt; }
+
+    public Set<Role> getRoles() { return roles; }
+    public void setRoles(Set<Role> roles) { this.roles = roles; }
 }

src/main/java/com/jobtracker/entity/enums/RoleName.java

@@ -0,0 +1,7 @@
+package com.jobtracker.entity.enums;
+
+public enum RoleName {
+    USER,
+    BETA,
+    ADMIN
+}

src/main/java/com/jobtracker/repository/RoleRepository.java

@@ -0,0 +1,13 @@
+package com.jobtracker.repository;
+
+import com.jobtracker.entity.Role;
+import com.jobtracker.entity.enums.RoleName;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.stereotype.Repository;
+
+import java.util.Optional;
+
+@Repository
+public interface RoleRepository extends JpaRepository<Role, Long> {
+    Optional<Role> findByName(RoleName name);
+}