SpringAuthStarter – Secure Your Spring Boot APIs in Minutes

SpringAuthStarter is a production-ready authentication starter kit for Spring Boot. It offers JWT-based authentication, Google & GitHub OAuth2 login, and role-based access control — all in one reusable package to secure your backend quickly.

Live Demo: https://spring-security-starter.onrender.com

---

📑 Table of Contents

1. Overview
2. Features
3. Architecture
4. Tech Stack
5. Installation & Setup
6. Usage
7. Environment Variables
8. API Documentation
9. Why Use This
10. Contributing
11. License

---

Overview

SpringAuthStarter eliminates the need to write repetitive Spring Security boilerplate. It’s ideal for:

• Securing REST APIs with JWT.
• Adding social login via Google & GitHub.
• Enforcing role-based endpoint protection.
• Providing ready-to-use Swagger API docs.

---

Features

Authentication:

• JWT issuance & validation for stateless auth.
• Password hashing with BCrypt.

Authorization:

• Role-based access control (ADMIN, USER).
• Secure admin-only and user-only routes.

OAuth2:

• Google & GitHub login.
• Direct OAuth login URLs in JSON responses.

Utilities:

• Rate limiting via Bucket4J.
• Default admin/user creation from environment variables.
• Swagger UI for interactive API testing.

---

Architecture

1. User sends login/registration request.
2. Backend validates credentials & issues JWT.
3. JWT is used for all subsequent protected requests.
4. OAuth2 flow handled by Spring Security client.

---

Tech Stack

• Language: Java 21
• Framework: Spring Boot 3.5
• Security: Spring Security, OAuth2 Client
• Database: MySQL/PostgreSQL
• Others: JJWT, Bucket4J, Spring Data JPA, Swagger
• Containerization: Docker
• Hosting: Render

---

Installation & Setup

git clone https://github.com/yourusername/SpringAuthStarter.git
cd SpringAuthStarter

Create .env (see .env.example) with DB, JWT, and OAuth credentials.

Run locally:

mvn spring-boot:run

Or build & run JAR:

mvn clean package
java -jar target/spring-auth-starter.jar

---

Usage

Register User

POST /register
{
  "email": "user@example.com",
  "username": "User",
  "password": "pass123",
  "role": "USER"
}

Login & Get JWT

POST /login
{
  "email": "user@example.com",
  "password": "pass123"
}

Use the returned JWT as Authorization: Bearer <token> for protected routes.

Default Users for Testing

To help you explore the features of this app, you can use the following test accounts:

Role	Email	Password
Admin	admin@example.com	Admin@123
User	user@example.com	User@123

Note: These accounts are for testing purposes only. You can also register your own account if you prefer.

How to Test:

1. Visit the app login page: https://spring-security-starter.onrender.com
2. Use one of the above credentials to log in.
3. Explore features according to your role (Admin or User).

---

Environment Variables

Variable	Description	Example
DB_HOST	Database host	localhost
DB_PORT	Database port	5432
JWT_SECRET	Secret key for JWT	change_me
GOOGLE_CLIENT_ID	Google OAuth client ID	abc.apps.googleusercontent.com
DEFAULT_ADMIN_EMAIL	Admin account email	admin@example.com

---

API Documentation

Swagger UI is available at: /swagger-ui.html or /swagger-ui/index.html or /docs.

---

Why Use This

• Saves days of setup work.
• Works out-of-the-box with OAuth2.
• Easily extendable for custom roles/permissions.
• Production-ready security configuration.

---

Contributing

Pull requests are welcome! For major changes, open an issue first to discuss.

---

License

MIT License – see LICENSE file for details.