Skip to content
BranchesTags

Repository files navigation

AuthFlow

A production-grade, event-driven microservices architecture implementing OTP-based authentication with JWT tokens for secure user identity management and session handling.

🎯 Key Features

Authentication & Security

  • OTP-Based Login: Secure 6-digit one-time passwords with 5-minute expiry
  • JWT Token Generation: Cryptographically signed tokens (HMAC SHA256) with 1-hour expiry
  • Role-Based Access Control: Support for multiple user roles (USER, ADMIN, etc.)
  • Stateless Authentication: JWT-based session management without server-side state
  • Distributed Security: Shared JWT utilities across all microservices

Event-Driven Architecture

  • Asynchronous Messaging: Kafka-based pub/sub for loose coupling between services
  • Real-time Email Notifications: Immediate OTP delivery via SMTP
  • Event Sourcing: Audit trail of OTP requests and generations
  • Service Decoupling: Services operate independently without direct dependencies

Microservices Design

  • Domain-Driven Services: Each service handles one responsibility
  • Independent Scaling: Services can scale based on their own load
  • Database per Service: Each microservice has dedicated PostgreSQL database
  • Service Discovery: Docker DNS-based service-to-service communication

API & Integration

  • GraphQL APIs: Type-safe, flexible query language for each service
  • GraphiQL Playground: Built-in API exploration tools
  • Inter-Service Communication: REST calls for OTP verification
  • Future OpenSearch Integration: Full-text search and analytics capability

🏗️ Architecture Overview

Service Topology

┌─────────────────────────────────────────────────────────┐
│              Docker Compose Network                     │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────────────┐    ┌──────────────────┐          │
│  │ Admin Auth Svc   │    │  OTP Generator   │          │
│  │    (8081)        │───▶│   Service(8082)  │          │
│  └──────────────────┘    └──────────────────┘          │
│         │                         │                     │
│         │   Kafka Topics          │                    │
│         ├─otp-requested──────────▶│                    │
│         │                otp-generated                  │
│         │        ◀────────┬───────┘                    │
│         │                 │                             │
│         ▼                 ▼                             │
│  ┌──────────────────────────────────┐                  │
│  │  Notification Service (8083)     │                  │
│  │  Kafka Consumer                  │                  │
│  │  (SMTP Email Sender)             │                  │
│  └──────────────────────────────────┘                  │
│                                                          │
│  ┌──────────────────────┐                              │
│  │   Kafka (9092)       │                              │
│  │   Message Broker     │                              │
│  └──────────────────────┘                              │
│                                                          │
│  ┌────────────────────────────────────────────┐       │
│  │  PostgreSQL (localhost:5432)                │       │
│  │  - auth_service_db                          │       │
│  │  - otp_generator_db                         │       │
│  │  - notification_service_db                  │       │
│  └────────────────────────────────────────────┘       │
│                                                          │
└─────────────────────────────────────────────────────────┘

Data Flow

1. AUTHENTICATION REQUEST
   CLIENT --GraphQL--> Admin Auth Service (8081)
                       └─ Publishes: "otp-requested" ---> Kafka

2. OTP GENERATION
   OTP Generator Svc (8082) <-- Consumes: "otp-requested"
   └─ Generates 6-digit OTP
   └─ Saves to DB (5-min expiry)
   └─ Publishes: "otp-generated" ---> Kafka

3. EMAIL NOTIFICATION
   Notification Service (8083) <-- Consumes: "otp-generated"
   └─ Extracts email & OTP
   └─ Sends SMTP email --> Gmail Server --> User Email

4. OTP VERIFICATION & LOGIN
   CLIENT --GraphQL--> Admin Auth Service (8081)
                       └─ Calls: OTP Service GraphQL
                          └─ verifyOtp(email, otp)
                       └─ Generates JWT Token
                       └─ Returns Token to Client

5. AUTHENTICATED REQUESTS
   CLIENT --Request + JWT Token--> Protected Services
                                    └─ JwtAuthFilter validates token
                                    └─ Sets user context
                                    └─ Processes authenticated request

📁 Project Structure

Java/Java/
├── admin-auth-service/
│   ├── src/
│   │   ├── main/java/com/example/
│   │   │   ├── AuthGraphQLResolver.java      # GraphQL mutations
│   │   │   ├── AuthService.java             # Business logic
│   │   │   └── User.java                    # Entity model
│   │   └── resources/
│   │       ├── application.properties        # Configuration
│   │       └── graphql/schema.graphqls       # GraphQL schema
│   ├── Dockerfile                           # Container image
│   ├── pom.xml                              # Maven dependencies
│   └── mvnw                                 # Maven wrapper
│
├── common-security-lib/
│   ├── src/main/java/com/example/
│   │   ├── JwtUtil.java                     # JWT utilities
│   │   ├── JwtAuthFilter.java              # JWT servlet filter
│   │   └── JwtContext.java                 # Thread-local context
│   ├── pom.xml                              # Maven POM
│   └── mvnw
│
├── otp-generator-service/
│   ├── src/
│   │   ├── main/java/com/example/
│   │   │   ├── OtpMutationResolver.java     # GraphQL mutations
│   │   │   ├── OtpService.java             # OTP logic
│   │   │   ├── OtpRequestListener.java     # Kafka consumer
│   │   │   └── UserOtp.java                # Entity model
│   │   └── resources/application.properties
│   ├── Dockerfile
│   ├── pom.xml
│   └── mvnw
│
├── notification-service/
│   ├── src/
│   │   ├── main/java/com/example/
│   │   │   ├── OtpGeneratedListener.java   # Kafka consumer
│   │   │   └── EmailService.java           # SMTP sender
│   │   └── resources/application.properties
│   ├── Dockerfile
│   ├── pom.xml
│   └── mvnw
│
├── OpenSearchJavaClientLocalDemo/
│   ├── src/main/java/com/example/
│   │   └── OpenSearchClient.java           # Search demo
│   └── pom.xml
│
└── docker-compose.yml                      # Orchestration config

🛠️ Technology Stack

Core Framework

  • Spring Boot: 3.5.4
  • Java: JDK 17
  • Build Tool: Maven 3.9.0

APIs & Messaging

  • GraphQL: Spring GraphQL 3.5.4
  • Apache Kafka: Message broker for async events
  • Servlet API: Jakarta 5.0.0

Security & Authentication

  • JWT (JJWT): 0.11.5 (HMAC SHA256 signing)
  • Spring Security: Integrated via common-security-lib
  • SMTP: Gmail-based email delivery

Data & Persistence

  • PostgreSQL: Primary database (3 instances)
  • Spring Data JPA: ORM and database abstraction
  • Jackson: JSON serialization/deserialization

Search & Analytics (Future)

  • OpenSearch: 2.11.0 (full-text search demo)

Containerization

  • Docker: Service containerization
  • Docker Compose: Multi-container orchestration
  • Docker Networking: Service-to-service communication

📋 Service Documentation

1. Admin Auth Service (Port 8081)

Purpose: Main authentication entry point for OTP-based user login

Responsibilities:

  • Accept OTP requests from clients
  • Publish OTP generation events to Kafka
  • Call OTP Service to verify OTP codes
  • Generate JWT tokens upon successful authentication
  • Maintain user registry with roles

GraphQL Schema:

type Query {
  getUser(email: String!): User
}

type Mutation {
  requestOtp(email: String!): Boolean
  loginWithOtp(email: String!, otp: String!): JwtResponse
}

type JwtResponse {
  token: String!
}

type User {
  id: Long!
  email: String!
  role: String!
  active: Boolean!
}

Technology:

  • Spring Boot 3.5.4
  • Spring Security with JWT
  • GraphQL API
  • Kafka Producer
  • PostgreSQL

Configuration (application.properties):

server.port=8081
spring.datasource.url=jdbc:postgresql://host.docker.internal:5432/auth_service_db
spring.graphql.graphiql.enabled=true
jwt.expiration=3600000
spring.kafka.bootstrap-servers=kafka:9092

2. OTP Generator Service (Port 8082)

Purpose: OTP generation and validation service

Responsibilities:

  • Generate cryptographically secure 6-digit OTPs
  • Persist OTPs with 5-minute expiry time
  • Validate OTP codes from login requests
  • Consume Kafka OTP request events
  • Publish OTP generation events

GraphQL Schema:

type Mutation {
  verifyOtp(email: String!, otp: String!): Boolean
}

Kafka Topics:

  • Consumer: otp-requested (from Admin Auth Service)

    {
  "email": "user@example.com",
  "timestamp": "2026-04-19T10:30:00Z"
}

  • Producer: otp-generated (to Notification Service)

    {
  "email": "user@example.com",
  "otp": "123456"
}

Technology:

  • Spring Boot 3.5.4
  • Spring Data JPA
  • GraphQL API
  • Kafka Consumer & Producer
  • PostgreSQL

Configuration (application.properties):

server.port=8082
spring.datasource.url=jdbc:postgresql://host.docker.internal:5432/otp_generator_db
spring.graphql.graphiql.enabled=true
spring.kafka.bootstrap-servers=kafka:9092
spring.kafka.consumer.group-id=otp-generator-group
otp.expiry.minutes=5

3. Notification Service (Port 8083)

Purpose: Email notifications for OTP delivery

Responsibilities:

  • Consume OTP generation events from Kafka
  • Extract OTP and recipient email
  • Send OTP via SMTP email
  • Provide email delivery confirmation

Kafka Consumer:

  • Topic: otp-generated
  • Group: notification-group
  • Message Format: 
    {
  "email": "user@example.com",
  "otp": "123456"
}

Email Template:

Subject: Your OTP for Login

Hello,

Your One-Time Password (OTP) is: 123456

This OTP is valid for 5 minutes only.

Do not share this OTP with anyone.

Regards,
AuthFlow Team

Technology:

  • Spring Boot 3.5.4
  • Spring Mail (JavaMailSender)
  • Kafka Consumer
  • SMTP (Gmail relay)

Configuration (application.properties):

server.port=8083
spring.kafka.bootstrap-servers=kafka:9092
spring.kafka.consumer.group-id=notification-group
spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.username=zenouchiha01@gmail.com
spring.mail.password=<app-password>
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=true

4. Common Security Library

Purpose: Shared JWT security utilities for all microservices

Key Components:

JwtUtil

  • Generates JWT tokens with email and role claims
  • Parses and validates JWT tokens
  • Handles signature verification (HMAC SHA256)
  • Extracts claims from tokens

JwtAuthFilter

  • Servlet filter for incoming request validation
  • Extracts Bearer token from Authorization header
  • Validates token signature and expiration
  • Sets authenticated user context

JwtContext

  • Thread-local storage for current user information
  • Provides thread-safe access to email and role
  • Maintains request-scoped authentication state

Token Structure:

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "sub": "user@example.com",
  "role": "USER",
  "iat": 1713590400,
  "exp": 1713594000
}

Maven Dependency (add to other services):

<dependency>
  <groupId>com.example</groupId>
  <artifactId>common-security-lib</artifactId>
  <version>1.0.0</version>
</dependency>

5. OpenSearch Java Client Demo

Purpose: Demonstration of OpenSearch integration for full-text search

Capabilities:

  • Index JSON documents to OpenSearch indices
  • Execute full-text search queries
  • Retrieve documents by ID
  • Real-time document indexing

Use Cases (Future):

  • User activity logs and auditability
  • Search across authentication records
  • Analytics and reporting

Technology:

  • OpenSearch REST High-Level Client 2.11.0
  • Log4j for logging

🚀 Getting Started

Prerequisites

  • Docker Desktop: Latest version (includes Docker and Docker Compose)
  • PostgreSQL: Running on localhost:5432
  • Maven: 3.9.0 or higher (or use mvnw wrapper)
  • Java: JDK 17 or higher

Installation & Setup

1. Clone and Navigate

cd Java/Java

2. Create PostgreSQL Databases

# Connect to PostgreSQL
psql -U postgres

# Create databases
CREATE DATABASE auth_service_db;
CREATE DATABASE otp_generator_db;
CREATE DATABASE notification_service_db;

# Exit
\q

3. Build All Services

# Build each service individually or use the wrapper script
cd admin-auth-service && mvn clean package -DskipTests
cd ../otp-generator-service && mvn clean package -DskipTests
cd ../notification-service && mvn clean package -DskipTests
cd ../common-security-lib && mvn clean package -DskipTests
cd ..

4. Start Docker Compose

docker-compose up -d

# Verify services are running
docker-compose ps

# View logs
docker-compose logs -f

5. Verify Services

# Check Admin Auth Service
curl http://localhost:8081/graphiql

# Check OTP Generator Service
curl http://localhost:8082/graphiql

# Check Notification Service
curl http://localhost:8083/health

📊 API Usage Examples

Request OTP

GraphQL Query (via http://localhost:8081/graphiql):

mutation {
  requestOtp(email: "john.doe@example.com")
}

Response:

{
  "data": {
    "requestOtp": true
  }
}

Verify OTP & Get JWT Token

GraphQL Mutation (via http://localhost:8081/graphiql):

mutation {
  loginWithOtp(email: "john.doe@example.com", otp: "123456") {
    token
  }
}

Response:

{
  "data": {
    "loginWithOtp": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJqb2huLmRvZUBleGFtcGxlLmNvbSIsInJvbGUiOiJVU0VSIiwiaWF0IjoxNzEzNTkwNDAwLCJleHAiOjE3MTM1OTQwMDB9.signature"
    }
  }
}

Use JWT Token for Authenticated Requests

HTTP Request with Bearer Token:

curl -X GET http://localhost:8081/api/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Verify OTP Directly (OTP Service)

GraphQL Mutation (via http://localhost:8082/graphiql):

mutation {
  verifyOtp(email: "john.doe@example.com", otp: "123456")
}

🔐 Security Features

Authentication Flow

  1. OTP Generation: 6-digit random code with 5-minute validity
  2. Email Delivery: SMTP-based secure OTP transmission
  3. Verification: Server-side OTP validation
  4. Token Generation: JWT issued upon successful OTP verification
  5. Request Authentication: JWT validated on every protected request

JWT Security

  • Algorithm: HMAC SHA256
  • Expiration: 1 hour (3600000 ms)
  • Claims: Email (sub), Role (role), Issue Time (iat), Expiration (exp)
  • Signature: Server-side secret key validation

Service-to-Service Security

  • Internal Network: All services on Docker private network
  • Service Discovery: DNS-based via service names
  • No External Exposure: Only specified ports exposed

📈 Scaling & Performance

Horizontal Scaling

# Scale OTP Generator Service (more OTP requests)
docker-compose up -d --scale otp-generator-service=3

# Scale Notification Service (more email sends)
docker-compose up -d --scale notification-service=2

Load Balancing

  • Kafka consumer groups handle automatic load distribution
  • Multiple service instances can consume from same Kafka topic
  • Kafka ensures each message is processed once across the group

Performance Tuning

  • Kafka Batch Size: Adjust batch.size for throughput
  • Pool Size: Configure spring.jdbc.hikari.maximum-pool-size
  • OTP Expiry: Adjust otp.expiry.minutes as needed
  • JWT Expiration: Modify jwt.expiration based on security requirements

🔧 Configuration Management

Environment Variables

# JWT Configuration
JWT_SECRET=your-secret-key
JWT_EXPIRATION=3600000

# Database Configuration
DB_URL=jdbc:postgresql://host.docker.internal:5432/auth_service_db
DB_USERNAME=postgres
DB_PASSWORD=password

# Kafka Configuration
KAFKA_BROKERS=kafka:9092

# Email Configuration
MAIL_USERNAME=zenouchiha01@gmail.com
MAIL_PASSWORD=app-specific-password

Per-Service Configuration

Edit src/main/resources/application.properties in each service:

  • Port configuration
  • Database URL and credentials
  • Kafka broker addresses
  • Email settings
  • JWT secrets

🐛 Troubleshooting

Services Not Starting

# Check logs
docker-compose logs admin-auth-service
docker-compose logs otp-generator-service
docker-compose logs notification-service

# Common issues:
# - PostgreSQL not running on localhost:5432
# - Kafka not starting (port 9092 in use)
# - Insufficient memory for JVM

Kafka Connection Issues

# Verify Kafka is running
docker-compose ps kafka

# Check Kafka logs
docker-compose logs kafka

# Restart Kafka
docker-compose restart kafka

OTP Not Received

  1. Verify Notification Service logs: docker-compose logs notification-service
  2. Check email configuration in notification-service/application.properties
  3. Ensure Gmail app password is set correctly
  4. Check Gmail "Allow less secure apps" if using Gmail account

JWT Token Issues

# Verify token expiration (should be 1 hour from issue time)
# Check token payload at https://jwt.io
# Ensure Authorization header format: "Bearer <token>"

📚 API Documentation

GraphQL Playgrounds

Kafka Topics

Topic Producer Consumer Schema
otp-requested Admin Auth Svc OTP Gen Svc {email, timestamp}
otp-generated OTP Gen Svc Notification Svc {email, otp}

Ports

Service Port Protocol Purpose
Admin Auth 8081 HTTP/GraphQL Authentication API
OTP Generator 8082 HTTP/GraphQL OTP verification API
Notification 8083 HTTP Email service
Kafka 9092 TCP Message broker
Zookeeper 2181 TCP Kafka coordination

🚀 Deployment

Docker Compose (Development)

docker-compose up -d

Kubernetes (Production)

  • Create Helm charts for each service
  • Deploy PostgreSQL as StatefulSet
  • Deploy Kafka as StatefulSet
  • Use ConfigMaps for configuration
  • Use Secrets for sensitive data (API keys, passwords)

Manual Deployment

  1. Build JAR files: mvn clean package
  2. Copy JARs to servers
  3. Install Java JDK 17
  4. Configure environment variables
  5. Run: java -jar service.jar

🔄 CI/CD Pipeline

Recommended Setup

  • Version Control: Git (GitHub/GitLab)
  • CI Tool: Jenkins/GitHub Actions
  • Build: Maven clean package
  • Test: Unit tests + integration tests
  • Artifact: Docker image push to registry
  • Deploy: Docker Compose or Kubernetes
  • Monitoring: ELK Stack or Prometheus/Grafana

GitHub Actions Example

name: Build and Deploy AuthFlow
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build with Maven
        run: mvn clean package -DskipTests
      - name: Build Docker images
        run: docker-compose build
      - name: Push to Registry
        run: docker push registry/authflow:latest

📝 Development Guidelines

Adding New Services

  1. Create new Maven module with Spring Boot starter
  2. Implement GraphQL resolvers for API
  3. Add Kafka producer/consumer as needed
  4. Create PostgreSQL schema
  5. Add to docker-compose.yml
  6. Include common-security-lib dependency

Extending OTP Functionality

// Custom OTP validation logic
public boolean validateOtp(String email, String otp, long maxAgeMinutes) {
    UserOtp userOtp = repository.findByEmail(email);
    return userOtp != null && 
           userOtp.getOtp().equals(otp) &&
           Duration.between(userOtp.getExpiryTime(), LocalDateTime.now()).toMinutes() <= maxAgeMinutes;
}

🎓 Learning Resources

📄 License

[Add your license here]

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

  1. Create a feature branch
  2. Make your changes with clear commit messages
  3. Add tests for new functionality
  4. Submit a pull request with documentation

📧 Support & Contact

For issues, questions, or suggestions:

  • Open an issue on the repository
  • Contact the development team
  • Check the Troubleshooting section

Version: 1.0.0
Status: ✅ Production-Ready
Last Updated: April 2026
Maintainers: Development Team

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages