Authentication Server

A comprehensive .NET 9 authentication server with JWT tokens, role-based authorization, audit logging, and PostgreSQL database.

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                          Client Layer                           │
├─────────────────┬─────────────────┬─────────────────┬───────────┤
│   Web Apps      │   Mobile Apps   │   Desktop Apps  │   APIs    │
└─────────────────┴─────────────────┴─────────────────┴───────────┘
                                │
                    ┌───────────▼───────────┐
                    │    Nginx (Port 80)    │
                    │   Reverse Proxy +     │
                    │   Load Balancer       │
                    └───────────┬───────────┘
                                │
                    ┌───────────▼───────────┐
                    │ Auth API (Port 5000)  │
                    │  ASP.NET Core 9 +     │
                    │  JWT + Identity       │
                    └───────────┬───────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        │                       │                       │
┌───────▼────────┐    ┌────────▼────────┐    ┌────────▼────────┐
│ PostgreSQL     │    │     Redis       │    │    Email        │
│ (Port 5432)    │    │  (Port 6379)    │    │   Service       │
│ Primary DB +   │    │ Caching +       │    │ (SMTP/SendGrid) │
│ User Data +    │    │ Sessions        │    │                 │
│ Audit Logs     │    │                 │    │                 │
└────────────────┘    └─────────────────┘    └─────────────────┘
        │
┌───────▼────────┐
│   pgAdmin      │
│ (Port 5050)    │
│ DB Management  │
└────────────────┘

🏛️ System Architecture

Clean Architecture Layers

┌─────────────────────────────────────────────────────────────┐
│                    Presentation Layer                       │
│  ┌─────────────────┐  ┌─────────────────┐                 │
│  │  Controllers    │  │   Middlewares   │                 │
│  │  - AuthController│  │  - JWT Auth     │                 │
│  │  - UserController│  │  - Error Handler│                 │
│  │  - RoleController│  │  - Audit Logger │                 │
│  │  - HealthController│ │  - CORS Policy │                 │
│  └─────────────────┘  └─────────────────┘                 │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│                   Application Layer                         │
│  ┌─────────────────┐  ┌─────────────────┐                 │
│  │    Services     │  │   Interfaces    │                 │
│  │  - AuthService  │  │  - IAuthService │                 │
│  │  - UserService  │  │  - IUserService │                 │
│  │  - RoleService  │  │  - IRoleService │                 │
│  │  - AuditService │  │  - IAuditService│                 │
│  │  - EmailService │  │  - IEmailService│                 │
│  └─────────────────┘  └─────────────────┘                 │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│                     Domain Layer                            │
│  ┌─────────────────┐  ┌─────────────────┐                 │
│  │    Entities     │  │      DTOs       │                 │
│  │  - User         │  │  - LoginDto     │                 │
│  │  - Role         │  │  - RegisterDto  │                 │
│  │  - Permission   │  │  - UserDto      │                 │
│  │  - AuditLog     │  │  - RoleDto      │                 │
│  │  - UserRole     │  │  - AuthResponseDto│               │
│  │  - UserPermission│ │  - ResetPasswordDto│              │
│  └─────────────────┘  └─────────────────┘                 │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│                 Infrastructure Layer                        │
│  ┌─────────────────┐  ┌─────────────────┐                 │
│  │ Data Access     │  │  External APIs  │                 │
│  │ - DbContext     │  │  - SMTP Client  │                 │
│  │ - Migrations    │  │  - HTTP Clients │                 │
│  │ - Seeding       │  │  - File Storage │                 │
│  │ - Connection    │  │  - Third-party  │                 │
│  │   Pooling       │  │    Services     │                 │
│  └─────────────────┘  └─────────────────┘                 │
└─────────────────────────────────────────────────────────────┘

🚀 Key Features

• 🔐 JWT Authentication - Secure token-based authentication with refresh tokens
• 👥 Role-Based Authorization - Hierarchical permission system with custom roles
• 📧 Email Integration - Password reset, welcome emails, and notifications
• � Comprehensive Audit Logging - Track all user actions and system changes
• 🗃️ PostgreSQL Database - ACID-compliant with automatic migrations
• 🐳 Full Docker Support - Complete containerization with orchestration
• 🏥 Health Monitoring - Application and database health endpoints
• � Interactive API Docs - Swagger/OpenAPI 3.0 with real-time testing
• � Soft Delete Pattern - Data preservation with logical deletion
• 🔒 Enterprise Security - HTTPS, CORS, rate limiting, security headers
• ⚡ Performance Optimized - Redis caching, connection pooling, async operations

💻 Technology Stack

• Framework: .NET 9.0 with ASP.NET Core
• Database: PostgreSQL 16 with Entity Framework Core 9
• Authentication: ASP.NET Core Identity + JWT Bearer tokens
• Containerization: Docker & Docker Compose
• Reverse Proxy: Nginx with rate limiting and security headers
• Caching: Redis for session management and performance
• Database UI: pgAdmin for database administration
• Documentation: Swagger/OpenAPI 3.0 with interactive UI
• Testing: xUnit with integration tests
• Logging: Serilog with structured logging

🏃‍♂️ Getting Started

Prerequisites

• Docker Desktop (Recommended approach)
• .NET 9 SDK (for local development)
• PostgreSQL 16+ (for local development)
• Git for version control

🐳 Docker Deployment (Recommended)

Quick Start

# 1. Clone repository
git clone <your-repo-url>
cd AuthenticationServer

# 2. Setup environment
cp .env.example .env
# Edit .env file with your configuration

# 3. Start all services (PostgreSQL, API, pgAdmin, Redis, Nginx)
docker compose up -d

# 4. Verify services are running
docker compose ps

# 5. Check API logs
docker compose logs -f authapi

Docker Commands Reference

Basic Operations

# Start all services in development mode
docker compose up -d

# Stop all services
docker compose down

# Restart specific service
docker compose restart authapi

# View real-time logs
docker compose logs -f authapi

# View all container status
docker compose ps

Production Deployment

# Start in production mode with all optimizations
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# Scale API instances (load balancing)
docker compose up -d --scale authapi=3

# Update and restart services
docker compose pull && docker compose up -d

Development & Debugging

# Rebuild API container
docker compose build authapi

# Force recreate containers (fresh start)
docker compose up -d --force-recreate

# Access container shell
docker compose exec authapi bash

# Access PostgreSQL directly
docker compose exec postgres psql -U postgres -d AuthenticationServerDb

Database Operations

# Create new migration (inside container)
docker compose exec authapi dotnet ef migrations add MigrationName --project ../AuthenticationServer.Data

# Update database with latest migrations
docker compose exec authapi dotnet ef database update --project ../AuthenticationServer.Data

# Generate SQL script for migrations
docker compose exec authapi dotnet ef migrations script --project ../AuthenticationServer.Data

🌐 Service Access Points

Service	URL	Purpose	Credentials
Authentication API	http://localhost:5000	Main API endpoints	-
Swagger Documentation	http://localhost:5000/swagger	Interactive API testing	-
Health Checks	http://localhost:5000/health	System health monitoring	-
Detailed Health	http://localhost:5000/health/detailed	Comprehensive health info	-
pgAdmin	http://localhost:5050	Database management UI	[email protected] / Admin@123456
Nginx Proxy	http://localhost:80	Production reverse proxy	-

👥 Default Test Accounts

After initial setup, these accounts are automatically created:

Role	Email	Password	Permissions
System Admin	[email protected]	Admin@123456	Full system access

Development

💻 Local Development Setup

Step-by-Step Setup

# 1. Clone repository
git clone <your-repo-url>
cd AuthenticationServer

# 2. Setup PostgreSQL database
createdb AuthenticationServerDb
# Alternative: Use Docker PostgreSQL
docker run --name postgres-dev -e POSTGRES_PASSWORD=password -p 5432:5432 -d postgres:16

# 3. Configure connection string
# Edit src/AuthenticationServer.Api/appsettings.Development.json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=AuthenticationServerDb;Username=postgres;Password=yourpassword;"
  },
  "Jwt": {
    "Key": "your-super-secret-key-that-is-at-least-32-characters-long",
    "Issuer": "AuthenticationServer",
    "Audience": "AuthenticationServer",
    "ExpireMinutes": 60
  }
}

# 4. Restore dependencies
dotnet restore

# 5. Run database migrations
cd src/AuthenticationServer.Api
dotnet ef database update --project ../AuthenticationServer.Data

# 6. Start the application
dotnet run
# API will be available at: https://localhost:7138 and http://localhost:5138

Local Development Commands

Build & Test

# Build entire solution
dotnet build

# Run all tests
dotnet test

# Run tests with coverage
dotnet test --collect:"XPlat Code Coverage"

# Restore packages
dotnet restore

Database Management

# Create new migration
dotnet ef migrations add MigrationName --project ../AuthenticationServer.Data

# Update database to latest migration
dotnet ef database update --project ../AuthenticationServer.Data

# Rollback to specific migration
dotnet ef database update PreviousMigrationName --project ../AuthenticationServer.Data

# Remove last migration (if not applied)
dotnet ef migrations remove --project ../AuthenticationServer.Data

# Drop entire database (CAUTION!)
dotnet ef database drop --project ../AuthenticationServer.Data

# Generate SQL script for migrations
dotnet ef migrations script --project ../AuthenticationServer.Data

# List all migrations
dotnet ef migrations list --project ../AuthenticationServer.Data

Development Tools

# Watch for changes and auto-reload
dotnet watch run

# Run in specific environment
dotnet run --environment Production

# Enable detailed logging
dotnet run --verbosity diagnostic

# Format code
dotnet format

# Analyze code for issues
dotnet analyze

📋 API Documentation

Authentication Endpoints

User Registration & Login

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

{
  "email": "[email protected]",
  "password": "SecurePassword123!",
  "firstName": "John",
  "lastName": "Doe"
}

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SecurePassword123!"
}

Password Management

POST /api/auth/forgot-password
Content-Type: application/json

{
  "email": "[email protected]"
}

POST /api/auth/reset-password
Content-Type: application/json

{
  "email": "[email protected]",
  "otpCode": "123456",
  "newPassword": "NewSecurePassword123!"
}

Token Management

POST /api/auth/refresh-token
Authorization: Bearer <refresh-token>

POST /api/auth/logout
Authorization: Bearer <access-token>

User Management Endpoints

GET /api/users
Authorization: Bearer <token>

GET /api/users/{id}
Authorization: Bearer <token>

PUT /api/users/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "firstName": "Updated Name",
  "lastName": "Updated Last",
  "email": "[email protected]"
}

DELETE /api/users/{id}
Authorization: Bearer <token>

Role Management Endpoints

GET /api/roles
Authorization: Bearer <token>

POST /api/roles
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "CustomRole",
  "description": "Custom role description"
}

PUT /api/roles/{id}
Authorization: Bearer <token>

DELETE /api/roles/{id}
Authorization: Bearer <token>

Health Check Endpoints

GET /health
# Returns: {"status":"Healthy","timestamp":"..."}

GET /health/detailed
Authorization: Bearer <token>
# Returns detailed system information

🔧 System Operation

How the Authentication System Works

1. User Registration Flow

User Input → Validation → Password Hashing → Database Storage → Email Verification → Account Activation

1. User submits registration form with email, password, and profile info
2. System validates input (email format, password strength, uniqueness)
3. Password is hashed using ASP.NET Core Identity (PBKDF2)
4. User record created in PostgreSQL with IsEmailConfirmed = false
5. Welcome email sent with confirmation link (optional)
6. Audit log entry created for registration event

2. Authentication Flow

Login Request → Credential Validation → JWT Generation → Token Response → Protected Resource Access

1. User submits email/password credentials
2. System validates credentials against hashed password in database
3. Upon success, JWT access token (short-lived) and refresh token (long-lived) are generated
4. Tokens returned to client with user profile information
5. Client includes access token in Authorization header for subsequent requests
6. Middleware validates JWT signature and extracts user claims
7. Audit log entry created for successful login

3. Authorization Flow

Request + JWT → Token Validation → Claims Extraction → Role/Permission Check → Access Decision

1. Client sends request with JWT token in Authorization header
2. JWT middleware validates token signature and expiration
3. User claims and roles extracted from token payload
4. Controller/Action authorization attributes check required permissions
5. Access granted or denied based on user's roles and permissions
6. Audit log entry created for authorization events

4. Role-Based Access Control (RBAC)

User → UserRoles → Roles → RolePermissions → Permissions → Resource Access

• Users can have multiple Roles
• Roles contain multiple Permissions
• Permissions define specific actions (Read, Write, Delete, etc.)
• System evaluates user's effective permissions for each request
• Hierarchical roles supported (Admin inherits User permissions)

5. Audit Logging System

User Action → Service Layer → Audit Service → Database → Queryable Logs

1. Every significant action triggers audit logging
2. Captures: User ID, Action, Entity Type, Old Values, New Values, Timestamp, IP Address
3. Stored in dedicated AuditLog table for compliance and security monitoring
4. Supports querying and filtering for security analysis
5. Automatic cleanup of old logs based on retention policies

6. Email Integration

Event Trigger → Email Template → SMTP Client → External Email Service → User Inbox

1. System events trigger email notifications (registration, password reset, etc.)
2. Templates used for consistent formatting and branding
3. SMTP client sends emails through configured provider (Gmail, SendGrid, etc.)
4. Supports both HTML and plain text formats
5. Email queue for high-volume scenarios (production)

7. Database Migration Strategy

Code Changes → EF Migration → Version Control → Deployment → Auto-Apply → Database Updated

1. Entity changes trigger new Entity Framework migrations
2. Migrations stored in version control with application code
3. On deployment, migrations automatically applied to target database
4. Supports rollback to previous migration if needed
5. Zero-downtime deployments with migration strategies

8. Containerized Deployment

Source Code → Docker Build → Container Registry → Orchestration → Health Checks → Live System

1. Application packaged into Docker containers with dependencies
2. Multi-stage builds optimize image size and security
3. Docker Compose orchestrates multiple services (API, DB, Cache, Proxy)
4. Health checks ensure service availability and automatic restarts
5. Environment-specific configurations through environment variables
6. Horizontal scaling through container replication

Performance & Security Features

Security Measures

• JWT Security: RSA/HMAC signatures, configurable expiration, secure refresh tokens
• Password Security: PBKDF2 hashing with salt, configurable complexity requirements
• API Security: HTTPS enforcement, CORS policies, rate limiting, input validation
• Database Security: Connection string encryption, SQL injection prevention, audit trails

Performance Optimizations

• Caching: Redis for session data, user profiles, and frequently accessed data
• Database: Connection pooling, optimized queries, proper indexing
• API: Async/await patterns, response compression, pagination
• Monitoring: Health checks, structured logging, performance counters

Monitoring & Observability

• Health Checks: API health, database connectivity, external service dependencies
• Logging: Structured logging with Serilog, log levels, correlation IDs
• Metrics: Performance counters, request duration, error rates
• Alerting: Failed login attempts, system errors, performance degradation

This authentication server provides enterprise-grade security, scalability, and maintainability for modern applications. The modular architecture allows for easy customization and extension based on specific requirements.

🤝 Contributing

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.

🆘 Support & Troubleshooting

Common Issues

Docker Issues

• Port conflicts: Change ports in docker-compose.yml
• Permission errors: Run Docker Desktop as administrator
• Build failures: Clear Docker cache with docker system prune -f

Database Issues

• Connection failures: Verify PostgreSQL is running and connection string is correct
• Migration errors: Check database permissions and run dotnet ef database drop to reset
• Seed data issues: Verify email constraints and password requirements

Authentication Issues

• JWT errors: Check JWT configuration and ensure keys are properly set
• Login failures: Verify user exists and password meets complexity requirements
• Permission denied: Check user roles and ensure proper authorization policies

Getting Help

• Check the Issues page for known problems
• Review Discussions for community support
• Contact maintainers for critical security issues

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - User login
• POST /api/auth/forgot-password - Request password reset
• POST /api/auth/reset-password - Reset password with OTP
• POST /api/auth/refresh-token - Refresh JWT token
• POST /api/auth/logout - User logout

User Management

• GET /api/user - Get all users
• GET /api/user/{id} - Get user by ID
• PUT /api/user/{id} - Update user
• DELETE /api/user/{id} - Soft delete user
• POST /api/user/{id}/assign-role - Assign role to user

Role Management

• GET /api/role - Get all roles
• POST /api/role - Create new role
• PUT /api/role/{id} - Update role
• DELETE /api/role/{id} - Delete role

System

• GET /health - Health check
• GET /health/detailed - Detailed health information

Features

• User Registration: Allows new users to register with the system.
• User Login: Authenticates users and provides access tokens.
• Forgot Password: Enables users to initiate a password reset process.
• OTP Email Verification: Sends a one-time password to verify user email addresses.
• Password Reset: Allows users to reset their passwords securely.
• User Roles and Permissions: Manages user roles and associated permissions.
• Audit Log: Maintains a log of changes and actions performed on entities.
• Soft Delete: Implements a soft delete mechanism for entities.
• Access and Refresh Tokens: Utilizes OpenIdDict for token management.

Project Structure

• src

  • AuthenticationServer.Api: Contains the API controllers and entry point.
  • AuthenticationServer.Core: Contains core business logic, entities, DTOs, and interfaces.
  • AuthenticationServer.Services: Implements services for user, authentication, role, and audit management.
  • AuthenticationServer.Data: Manages database context and repositories for data access.
  • AuthenticationServer.Infrastructure: Contains configuration and extension methods for dependency injection.

• tests

  • AuthenticationServer.Tests: Contains unit tests for controllers and services.
  • AuthenticationServer.IntegrationTests: Contains integration tests for the application.

Getting Started

1. Clone the repository.
2. Set up the PostgreSQL database and update the connection string in appsettings.json.
3. Run the migrations to create the database schema.
4. Start the application and access the API endpoints.

API Documentation

API documentation is available via Swagger. Once the application is running, navigate to /swagger to explore the available endpoints and their usage.

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any enhancements or bug fixes.

License

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