Security Docker - Spring Boot JWT Authentication Example

This project is a Spring Boot application demonstrating a secure REST API with JWT (JSON Web Token) based authentication and authorization. It provides endpoints for user registration, authentication, and a protected demo resource.

Table of Contents

• Features
• Technologies Used
• Prerequisites
• Getting Started
  • Clone the Repository
  • Build the Project
  • Run the Application
• API Endpoints
  • Authentication
  • Protected Resource
• Project Structure
• Contributing
• License

Features

• User Registration: Allows new users to sign up.
• User Authentication: Authenticates existing users and issues JWTs.
• JWT-based Authorization: Secures API endpoints using JWTs.
• Role-based Access Control: Demonstrates basic role management (e.g., USER role).
• H2 Database: In-memory database for development and testing.
• RESTful API: Clean and well-structured API endpoints.

Technologies Used

• Java 24+: The core programming language.
• Spring Boot 3.x: Framework for building the application.
• Spring Security: For authentication and authorization.
• JJWT (Java JWT): Library for handling JSON Web Tokens.
• Maven: Dependency management and build automation.
• H2 Database: In-memory relational database.

Prerequisites

Before you begin, ensure you have the following installed:

• Java Development Kit (JDK) 17 or higher
• Apache Maven 3.x

Getting Started

Clone the Repository

git clone https://github.com/Falasefemi2/security-docker.git
cd security-docker

Build the Project

Use Maven to build the project:

mvn clean install

Run the Application

You can run the Spring Boot application using Maven:

mvn spring-boot:run

The application will start on http://localhost:8080 by default.

API Endpoints

The application exposes the following REST endpoints:

Authentication

1. Register a New User

• URL: /api/v1/auth/register
• Method: POST
• Content-Type: application/json
• Request Body Example:

  {
    "firstname": "John",
    "lastname": "Doe",
    "email": "john.doe@example.com",
    "password": "password123",
    "role": "USER"
  }

• Success Response:

  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }

2. Authenticate User

• URL: /api/v1/auth/authenticate
• Method: POST
• Content-Type: application/json
• Request Body Example:

  {
    "email": "john.doe@example.com",
    "password": "password123"
  }

• Success Response:

  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }

Protected Resource

1. Access Demo Endpoint

• URL: /api/v1/demo
• Method: GET
• Headers:
  • Authorization: Bearer <YOUR_JWT_TOKEN>
• Success Response:

  "Hello from secured endpoint"

• Error Response (if token is missing or invalid):

  {
    "timestamp": "...",
    "status": 403,
    "error": "Forbidden",
    "message": "Access Denied",
    "path": "/api/v1/demo"
  }

You can use the .http files in the httprequests/ directory (e.g., authenticate.http, register.http, demo.http) with an IDE extension like "REST Client" (for VS Code) to easily test these endpoints.

Project Structure

security-docker/
├───.mvn/                     # Maven wrapper files
├───httprequests/             # Example HTTP request files for testing
├───src/
│   ├───main/
│   │   ├───java/
│   │   │   └───com/
│   │   │       └───femi/
│   │   │           └───securitydocker/
│   │   │               ├───SecurityDockerApplication.java # Main application class
│   │   │               ├───config/                  # Spring Security and JWT configuration
│   │   │               ├───controller/              # REST API controllers
│   │   │               ├───dto/                     # Data Transfer Objects for requests/responses
│   │   │               ├───enumfolder/              # Enum definitions (e.g., Role)
│   │   │               ├───model/                   # JPA Entities (e.g., User)
│   │   │               ├───Repository/              # Spring Data JPA repositories
│   │   │               └───service/                 # Business logic and JWT service
│   │   └───resources/
│   │       ├───application.yml      # Application configuration (e.g., server port, H2 console)
│   │       ├───static/              # Static web resources
│   │       └───templates/           # Thymeleaf templates (if any)
│   └───test/                     # Unit and integration tests
├───pom.xml                   # Maven Project Object Model
└───README.md                 # This file

Contributing

Contributions are welcome! Please feel free to fork the repository, create a new branch, and submit a pull request.

License

This project is open-source and available under the MIT License.