Skip to content

README.md

Latest commit

 

History

History
245 lines (193 loc) · 7.1 KB

README.md

File metadata and controls

245 lines (193 loc) · 7.1 KB

CodeJam Logo

AuthZen 🔐

A secure, extensible authentication and authorization backend for modern applications built with Spring Boot. Designed for scalability and real-world integration, this project includes JWT, OAuth2, role-based access, admin controls, and token lifecycle management.

✨ Features

  • User Registration & Login (JWT-based)
  • Refresh Token handling (per user, revocable)
  • GitHub OAuth2 login support
  • Role-based Access Control (User/Admin)
  • Audit Logging (for all sensitive actions)
  • Admin Delegation (promote/demote users)
  • Token Revocation on logout
  • Account Lock/Unlock Management

📆 Technologies

  • Java 21
  • Spring Boot 3
  • Spring Security
  • JWT (Access & Refresh)
  • OAuth2 (GitHub)
  • MySQL
  • Hibernate (JPA)
  • Lombok
  • MapStruct (optional)
  • Docker (optional for deployment)

🌐 API Endpoints

🔓 Public

Method Endpoint Description
POST /auth/register Register a new user
POST /auth/login Login with email & password
POST /auth/oauth GitHub OAuth login
POST /auth/reset-request Request password reset token
POST /auth/reset-password Reset password using token
POST /auth/refresh Revoke refresh token

🔐 Secured (Authenticated User)

Method Endpoint Description
GET /auth/me Get logged-in user profile
PUT /auth/update Update profile
POST /auth/logout Logout

🛠️ Admin Only

Method Endpoint Description
GET /admin/users View all users
PUT /admin/users/{id}/roles Update user roles to relevent user
GET /admin/audit-logs View audit logs
GET /admin/roles List all available roles
POST /admin/delegate Delegate admin role to another user
POST /admin/users/roles Update user roles

🎓 Project Structure

Authzen/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── yourorg/
│   │   │           └── authzen/
│   │   │               ├── AuthzenApplication.java
│   │   │               ├── configs/
│   │   │               ├── constants/
│   │   │               ├── controllers/
│   │   │               ├── dtos/
│   │   │               ├── endpoints/
│   │   │               ├── exceptions/
│   │   │               ├── models/
│   │   │               ├── repositories/
│   │   │               ├── responses/
│   │   │               ├── security/
│   │   │               ├── services/
│   │   │               └── utils/
│   │   └── resources/
│   │       ├── application.yml
│   │       ├── static/
│   │       │   ├── css/
│   │       │   ├── js/
│   │       │   └── reset-password/
│   │       └── templates/
├── .env
├── .env.docker
├── .env.example
├── .gitignore
├── docker-compose.yml
├── Dockerfile
├── HELP.md
├── LICENSE.md
├── mvnw
├── mvnw.cmd
├── pom.xml
└── README.md

⚙️ Getting Started

1. Clone the Repo

git clone https://github.com/kgchinthana/authzen.git
cd authzen

2. Setup Environment Variables

Create .env file in root directory:

  SPRING_APPLICATION_NAME=authzen
  SPRING_DATASOURCE_URL=jdbc:mysql://localhost:3306/authzen?createDatabaseIfNotExist=true
  SPRING_DATASOURCE_USERNAME=root
  SPRING_DATASOURCE_PASSWORD=yourpassword
  SERVER_PORT=8080
  
  JWT_SECRET=your_secret_key
  JWT_ACCESS_TOKEN_EXPIRY_MS=900000
  JWT_REFRESH_TOKEN_EXPIRY_MS=604800000
  
  MAIL_HOST=smtp.gmail.com
  MAIL_PORT=587
  MAIL_USERNAME=youremail@gmail.com
  MAIL_PASSWORD=yourapppassword
  EMAIL_FROM=noreply@yourdomain.com
  
  GITHUB_CLIENT_ID=your_client_id
  GITHUB_CLIENT_SECRET=your_client_secret
  GITHUB_REDIRECT_URI=http://localhost:8080/oauth/callback
  
  ADMIN_EMAIL=admin@yourdomain.com
  ADMIN_USERNAME=admin
  ADMIN_PASSWORD=Admin@123

3. GitHub OAuth Setup

Register a GitHub OAuth App:

  • Homepage: http://localhost:8080
  • Callback: http://localhost:8080/auth/oauth

Set in .env:

  GITHUB_CLIENT_ID=your_client_id
  GITHUB_CLIENT_SECRET=your_client_secret
  GITHUB_REDIRECT_URI=http://localhost:8080/oauth/callback

4. Run the Application

./mvnw spring-boot:run

Roles (ROLE_USER, ROLE_ADMIN) will be auto-initialized.

🌎 OAuth Flow

  • Frontend gets GitHub access token from GitHub
  • Sends it to /auth/oauth
  • Server verifies token with GitHub & links to user

🚀 Example Request: Register

POST /auth/register
Content-Type: application/json

{
  "username": "alice",
  "email": "alice@example.com",
  "password": "securepass"
}

📄 Environment Variables

Key Description
GITHUB_CLIENT_ID GitHub OAuth client ID
GITHUB_CLIENT_SECRET GitHub OAuth client secret
JWT_SECRET JWT signing key
JWT_EXPIRATION Access token duration
REFRESH_TOKEN_EXPIRATION Refresh token duration

📊 Database Schema

  • users: user credentials and metadata
  • roles: available roles
  • user_roles: user-role associations
  • refresh_tokens: long-lived refresh tokens
  • oauth_providers: linked GitHub accounts
  • audit_logs: admin actions tracking
  • email_tokens: password reset tokens
  • permissions: defines fine-grained permissions
  • role_permissions: role-permissions associations

🛡️ Security Highlights

  • BCrypt hashed passwords
  • JWT with separate refresh token DB
  • Role-checking via @PreAuthorize & SecurityContext
  • Admin-only endpoints protected with ROLE_ADMIN
  • GitHub token verification before linking

🔧 Contributing

  1. Fork the repo
  2. Fix a bug or implement a feature
  3. Submit a pull request

For the open-source competition, check the issues tab for bugs to solve!

📃 License

MIT © 2025 — CodeJam Codex Team