Golang Authentication Service

A production-ready authentication service built with Go, featuring JWT authentication, RBAC, MongoDB/MySQL support, Redis caching, RabbitMQ messaging, and comprehensive security features.

Table of Contents

• Features
• Quick Start
• Configuration
• API Reference
• Authentication & RBAC
• Testing
• Production Deployment
• Development
• Troubleshooting

Features

Core Features

• JWT Authentication - Secure token-based authentication
• RBAC (Role-Based Access Control) - Granular permissions system with admin and user roles
• Password Management - Forgot password, reset password, change password flows
• Email Verification - Account activation via email with email change support
• Rate Limiting - Redis-based DDoS protection (login, registration, password reset)
• Account Security - Automatic lockout after failed login attempts
• Audit Logging - Complete security event tracking
• Multi-Database - MongoDB (primary) and MySQL support
• Redis Caching - Performance optimization and token management
• RabbitMQ Events - Event-driven architecture for user actions
• Observability - OpenTelemetry + Uptrace integration with structured logging
• Docker Support - Full containerization with Docker Compose

Security Features

• bcrypt password hashing
• Account lockout after 5 failed attempts (15-minute duration)
• JWT token validation and caching
• IP-based rate limiting
• Session management with logout
• Audit trail for all security events
• Email verification redirects to frontend

Quick Start

Prerequisites

• Go 1.23.0 or higher
• MongoDB
• Redis
• RabbitMQ
• SendGrid account (for emails)
• Docker and Docker Compose (optional)

Installation

1. Clone the repository

   git clone <repository-url>
   cd AuthenticationService
   

2. Set up environment variables

   cp .env.example .env
   # Edit .env with your credentials
   

3. Start services with Docker (recommended)

   make dev-up
   # Or manually:
   docker-compose up -d
   go run cmd/main.go
   

4. Seed RBAC data

   go run scripts/seed_roles.go
   

Available Services

When running in development mode:

• Application: http://localhost:8080
• MySQL: localhost:3306 (auth_user / auth_password)
• MongoDB: localhost:27017 (auth_user / auth_password)
• Redis: localhost:6379 (password: auth_password)
• RabbitMQ: localhost:5672 (auth_user / auth_password)
• RabbitMQ Management: http://localhost:15672

Configuration

Environment Variables

Create a .env file with the following variables:

# MongoDB
MONGO_URI=mongodb://127.0.0.1:27017
MONGO_PASSWORD=your_password

# Redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=your_password

# RabbitMQ
RMQ_HOST=127.0.0.1
RMQ_USER=auth_user
RMQ_PASSWORD=your_password

# JWT & Email
JWT_SECRET=your_very_secret_jwt_key
SENDGRID_API_KEY=your_sendgrid_key
SENDGRID_EMAIL=sender@example.com

Configuration Files

• internal/config/config.yml - Production configuration
• internal/config/config_local.yml - Development configuration (if exists)

Set APP_ENV environment variable:

• development, dev, local → Development mode
• production, prod → Production mode

API Reference

Base URL: http://localhost:8080

Public Endpoints

Method	Endpoint	Rate Limit	Description
POST	/api/v1/auth/register	3/hour	Register new user
POST	/api/v1/auth/login	5/15min	User login
GET	/api/v1/auth/verify	-	Activate account (redirects to /login)
POST	/api/v1/auth/forgot-password	3/hour	Request password reset
POST	/api/v1/auth/reset-password	-	Reset password with token
POST	/api/v1/auth/change-email/confirm	-	Confirm email change

Protected Endpoints (Require JWT)

Profile Management

Method	Endpoint	Description
GET	/api/v1/auth/profile	Get user profile
PUT	/api/v1/auth/profile	Update profile
GET	/api/v1/auth/profile/activity	Get account activity logs

Password Management

Method	Endpoint	Description
POST	/api/v1/auth/change-password	Change password (requires old password)

Email Management

Method	Endpoint	Description
POST	/api/v1/auth/change-email/request	Request email change

Account Management

Method	Endpoint	Description
POST	/api/v1/auth/deactivate	Deactivate account
DELETE	/api/v1/auth/delete	Permanently delete account
POST	/api/v1/auth/logout	Logout and invalidate token

Admin Endpoints (Require JWT + Admin Role)

Method	Endpoint	Description
GET	/api/v1/admin/stats	Dashboard statistics
GET	/api/v1/admin/users	List users (paginated)
GET	/api/v1/admin/users/{id}	Get user by ID
PUT	/api/v1/admin/users/{id}/status	Update user status
DELETE	/api/v1/admin/users/{id}	Delete user
POST	/api/v1/admin/users/{id}/reset-password	Reset user password
GET	/api/v1/admin/users/{id}/logs	Get user audit logs
GET	/api/v1/admin/roles	Get all roles
GET	/api/v1/admin/permissions	Get all permissions

Authentication & RBAC

Role-Based Access Control

The service implements a comprehensive RBAC system with roles and permissions.

Default Roles

Admin Role - Full system access

• user:read, user:write, user:delete
• role:read, role:write, role:delete
• permission:read, permission:write, permission:delete
• audit:read
• profile:read, profile:write

User Role - Limited access

• profile:read, profile:write

Permissions

Permission	Resource	Action	Description
user:read	user	read	Read user information
user:write	user	write	Create/update users
user:delete	user	delete	Delete users
role:read	role	read	Read roles
role:write	role	write	Create/update roles
role:delete	role	delete	Delete roles
permission:read	permission	read	Read permissions
permission:write	permission	write	Create/update permissions
permission:delete	permission	delete	Delete permissions
audit:read	audit	read	Read audit logs
profile:read	profile	read	Read own profile
profile:write	profile	write	Update own profile

Registration Flow

1. User submits registration with optional role field
2. Special admin email (abc@gmail.com) automatically gets admin role
3. Role is validated against database
4. User is created with role_name field
5. User-role mapping created in user_roles collection
6. Verification email sent
7. User clicks verification link → redirected to frontend /login page

Database Collections

• permissions - Stores all permissions
• roles - Stores roles with permission arrays
• user_roles - User-role mappings
• users - User accounts with role_name field

Seeding RBAC Data

go run scripts/seed_roles.go
go run scripts/verify_mongo.go  # Verify seeded data

Testing

Test Structure

tests/
├── unit/
│   ├── utils/          # Utility function tests
│   ├── services/       # Service layer tests
│   └── controllers/    # Controller tests
├── mocks/              # Mock implementations
└── config/             # Test configuration

Running Tests

# Run all unit tests
make test
go test -v ./...

# Run specific test suites
go test -v ./tests/unit/utils/...
go test -v ./tests/unit/services/...
go test -v ./tests/unit/controllers/...

# Run with coverage
make test-coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run benchmarks
go test -bench=. ./tests/unit/utils/...

# Run API/integration tests
./scripts/test_api.sh

API Integration Tests

The test_api.sh script provides comprehensive API testing:

# Run full test suite
./scripts/test_api.sh

# Tests include:
# - RBAC: Role assignment, user/admin registration
# - Authentication: Login success/failure, token validation
# - Security: Rate limiting, authentication checks
# - Validation: Email format, password strength

Test Coverage

• Utilities: ~95% coverage (JWT, hashing, validation)
• Services: Functional coverage of critical paths
• Controllers: HTTP handler testing

RBAC Testing

# Test complete RBAC flow
go run scripts/test_complete_rbac.go

Environment Setup

Production Environment Variables

APP_ENV=production
MONGO_URI=<production_mongodb_uri>
REDIS_HOST=<production_redis_host>
JWT_SECRET=<strong_secret_256_bit>
SENDGRID_API_KEY=<production_key>
FRONTEND_HOST=<production_frontend_url>
UPTRACE_DSN=<uptrace_dsn>

Health Checks

• Liveness: GET /health
• Readiness: Check MongoDB, Redis, RabbitMQ connections

Development

Project Structure

├── cmd/                    # Application entry points
│   └── main.go
├── internal/               # Private application code
│   ├── api/
│   │   ├── controllers/   # HTTP handlers
│   │   ├── middleware/    # Middleware (auth, logging, rate limiting)
│   │   └── router/        # Chi router setup
│   ├── config/            # Configuration management
│   ├── constants/         # Application constants
│   ├── dto/               # Data transfer objects
│   ├── errors/            # Custom errors
│   ├── handlers/          # Event handlers (RabbitMQ)
│   ├── models/            # Domain models
│   ├── queue/             # Message queue integration
│   ├── repository/        # Data access layer
│   ├── services/          # Business logic
│   └── utils/             # Utilities (JWT, hashing, validation)
├── services/              # External integrations
│   ├── external/          # Third-party services (SendGrid)
│   └── util/              # Service utilities
├── tests/                 # Test suites
├── scripts/               # Utility scripts
└── docker-compose.yml     # Local development services

License

This project is licensed under the MIT License.

---

Version: 1.0.0
Last Updated: 2025-11-23
Minimum Go Version: 1.23.0 This is a Generated README