README.md

Spring Security + JWT Test Project

A test Spring Boot application demonstrating authentication and authorization using Spring Security 6 with JWT (JSON Web Token) integration.

📋 Project Overview

This project is a complete example of implementing Spring Security in a modern Spring Boot 4 application with JWT-based authentication. It includes user management, secure endpoints, and token-based authorization.

🛠️ Technology Stack

• Java 21 — Latest LTS version
• Spring Boot 4.0.0 — Modern Spring framework
• Spring Security 6 — Authentication & authorization
• JWT (JJWT 0.12.6) — Token-based authentication
• MapStruct 1.5.5 — DTO-to-Entity mapping
• Lombok — Boilerplate code reduction
• PostgreSQL — Relational database
• Maven — Dependency management

📁 Project Structure

springsecurity-test/
├── src/
│   ├── main/java/com/project/testsecurity/
│   │   ├── entity/
│   │   │   └── User.java
│   │   ├── dto/
│   │   │   └── UserDto.java
│   │   ├── mapper/
│   │   │   └── UserMapper.java
│   │   ├── service/
│   │   │   └── impl/
│   │   │       └── UserServiceImpl.java
│   │   └── TestSecurityApplication.java
│   └── test/
├── pom.xml
└── README.md

Key Components

Entity Layer (entity/User.java)

@Entity
@Table(name = "users")
@Getter
@Setter
@RequiredArgsConstructor
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    @Column(name = "user_id")
    private UUID userId;
    
    @Column(name = "first_name")
    private String firstName;
    
    @Column(name = "last_name")
    private String lastName;
    
    @Column(name = "email")
    private String email;
    
    @Column(name = "password")
    private String password;
}

DTO Layer (dto/UserDto.java)

@Data
public class UserDto {
    String userId;
    String firstName;
    String lastName;
    String email;
    String password;
}

Mapper Interface (mapper/UserMapper.java)

MapStruct-based interface for converting between User entity and UserDto:

@Mapper(componentModel = MappingConstants.ComponentModel.SPRING,
        unmappedTargetPolicy = ReportingPolicy.IGNORE)
public interface UserMapper {
    UserDto toDto(User user);
    User toEntity(UserDto dto);
}

⚙️ Configuration

Dependencies (pom.xml)

Key dependencies included:

• spring-boot-starter-security — Spring Security framework
• spring-boot-starter-data-jpa — JPA/Hibernate ORM
• spring-boot-starter-webmvc — Web MVC support
• jjwt-* (api, impl, jackson) — JWT token creation and validation
• mapstruct + mapstruct-processor — DTO mapping
• lombok — Code generation
• postgresql — Database driver

Maven Compiler Configuration

Ensures proper annotation processing for Lombok and MapStruct:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.11.0</version>
    <configuration>
        <source>21</source>
        <target>21</target>
        <annotationProcessorPaths>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
            </path>
            <path>
                <groupId>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>1.5.5.Final</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

🚀 Getting Started

Prerequisites

• Java 21 or higher
• Maven 3.8+
• PostgreSQL 12+ (for production)
• Git

Installation

1. Clone the repository:

git clone https://github.com/nurassul/springsecurity-test.git
cd springsecurity-test

2. Configure database (application.properties or application.yml):

spring.datasource.url=jdbc:postgresql://localhost:5432/springsecurity_db
spring.datasource.username=postgres
spring.datasource.password=your_password
spring.jpa.hibernate.ddl-auto=update

3. Build the project:

mvn clean install

4. Run the application:

mvn spring-boot:run

The application will start on http://localhost:8080

🔐 Security Features

Authentication

• User registration with encrypted passwords
• Login endpoint returning JWT token
• Token validation for protected endpoints

Authorization

• Role-based access control (RBAC)
• JWT-based stateless authentication
• Secure password encryption

🔧 Common Issues & Solutions

Bean Not Found Error

Error: Parameter 1 of constructor required a bean of type 'UserMapper' that could not be found

Solution: Ensure MapStruct processor is configured correctly in pom.xml:

• Add mapstruct-processor dependency
• Include it in annotationProcessorPaths in maven-compiler-plugin
• Rebuild project: mvn clean rebuild

JWT Token Issues

• Verify JJWT version compatibility with Spring Boot 4.0.0
• Check JWT secret key configuration
• Validate token expiration settings

📚 API Endpoints (Example)

Method	Endpoint	Description
POST	/api/auth/register	Register new user
POST	/api/auth/login	Login & get JWT token
GET	/api/users/{id}	Get user by ID (requires auth)
PUT	/api/users/{id}	Update user (requires auth)
DELETE	/api/users/{id}	Delete user (requires auth)

🧪 Testing

Run tests with Maven:

mvn test

Tests include:

• Unit tests for services
• Integration tests with Spring Security
• JWT token validation tests

📝 Configuration Files

Application Properties

Create src/main/resources/application.properties:

# Server Configuration
server.port=8080

# Database
spring.datasource.url=jdbc:postgresql://localhost:5432/springsecurity_db
spring.datasource.username=postgres
spring.datasource.password=password
spring.datasource.driver-class-name=org.postgresql.Driver

# JPA/Hibernate
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=false
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

# JWT Configuration
jwt.secret.key=your-super-secret-key-change-in-production
jwt.expiration=86400000

# Security
spring.security.user.name=admin
spring.security.user.password=admin123

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

👤 Author

nurassul — GitHub: @nurassul

📞 Support

For issues and questions, please open an issue on the GitHub repository.

---

Happy Coding! 🎉