Authentication API

A modern, production-ready Go REST API for authentication and authorization, featuring social login, email verification, JWT, Two-Factor Authentication (2FA), and Redis integration.

🚀 Features

Secure user registration & login (JWT access/refresh tokens)
Two-Factor Authentication (2FA) with TOTP and recovery codes
User Activity Logs with pagination and filtering
Social login: Google, Facebook, GitHub
Email verification & password reset
Role-based access control (middleware)
Redis for token/session management
Dockerized for local development & deployment
Unit & integration tests
Interactive Swagger API documentation
Development and production Docker configurations

🗂️ Project Structure

cmd/api/main.go         # Entry point
internal/               # Core logic
├── auth/              # Authentication handlers
├── user/              # User management
├── social/            # Social authentication (OAuth2)
├── twofa/             # Two-Factor Authentication
├── log/               # Activity logging system
├── email/             # Email verification & password reset
├── middleware/        # JWT auth middleware
├── database/          # Database connection & migrations
├── redis/             # Redis connection & session management
├── config/            # Configuration management
└── util/              # Utility functions
pkg/                   # Shared packages
├── models/            # Database models
├── dto/               # Data Transfer Objects
├── errors/            # Custom error types
└── jwt/               # JWT utilities
docs/                  # API documentation
├── swagger.json       # Generated Swagger spec
├── swagger.yaml       # Generated Swagger spec
├── docs.go            # Generated Swagger docs
├── README.md          # Documentation overview
├── ARCHITECTURE.md    # System architecture
└── API.md             # API reference
.env                   # Environment variables
.github/               # GitHub templates and workflows
├── ISSUE_TEMPLATE/    # Issue templates
└── workflows/         # CI/CD workflows (if any)
Dockerfile             # Production Docker image
Dockerfile.dev         # Development Docker image
docker-compose.yml     # Production Docker Compose
docker-compose.dev.yml # Development Docker Compose
Makefile               # Build and development commands
test_api.sh            # API testing script
.air.toml              # Air configuration for hot reload
dev.sh, dev.bat        # Development startup scripts
CONTRIBUTING.md        # Contribution guidelines
CODE_OF_CONDUCT.md     # Code of conduct
SECURITY.md            # Security policy
LICENSE                # MIT License

📖 API Documentation (Swagger)

After starting the server, access the interactive API docs at:

http://localhost:8080/swagger/index.html

You can try out all endpoints, including social logins and 2FA operations, directly from the browser.

🔄 Regenerating Swagger Documentation

If you make changes to your API routes or annotations, regenerate the Swagger docs with:

make swag-init

swag init -g cmd/api/main.go -o docs

Requires the swag CLI (go install github.com/swaggo/swag/cmd/swag@latest)
This will update the docs/ folder with the latest API documentation

⚡ Quick Start (Docker)

Clone the repository
Copy .env and update with your credentials
Start development:
- Windows: dev.bat
- Linux/Mac: ./dev.sh
API available at http://localhost:8080
Swagger docs at http://localhost:8080/swagger/index.html

🛠️ Manual Setup

Create PostgreSQL DB & update .env
go mod tidy
Install Air for hot reload: go install github.com/air-verse/air@latest
Run: air or go run cmd/api/main.go

🛠️ Makefile Commands

The following make commands are available for development, testing, building, and Docker operations:

Command	Description
`make build`	Build the application binary (`bin/api.exe`).
`make run`	Run the application without hot reload.
`make dev`	Run with hot reload using Air.
`make test`	Run all Go tests with verbose output.
`make test-totp`	Run TOTP test (requires `TEST_TOTP_SECRET` environment variable).
`make clean`	Remove build artifacts and temporary files.
`make install-air`	Install Air for hot reloading.
`make setup`	Setup development environment (installs Air, tidy/download deps).
`make fmt`	Format code using `go fmt`.
`make lint`	Run linter (`golangci-lint`).
`make install-security-tools`	Install security scanning tools (`gosec` and `nancy`).
`make security-scan`	Run gosec security scanner.
`make vulnerability-scan`	Run nancy vulnerability scanner.
`make security`	Run all security checks (gosec + nancy).
`make build-prod`	Build for production (Linux, static binary).
`make docker-dev`	Run development environment with Docker (`./dev.sh`).
`make docker-compose-build`	Build Docker images using docker-compose.
`make docker-compose-down`	Stop and remove Docker containers, networks, images, volumes.
`make docker-compose-up`	Start Docker containers in detached mode with build.
`make docker-build`	Build Docker image (`auth-api`).
`make docker-run`	Run Docker container with environment from `.env`.
`make swag-init`	Generate Swagger documentation (`docs/`).
`make help`	Show all available make commands.

Tip: You can also run make help to see this list in your terminal.

🔑 API Endpoints

Authentication

POST /register — User registration
POST /login — User login (with 2FA support)
POST /logout — User logout and token revocation (protected)
POST /refresh-token — Refresh JWT tokens
GET /verify-email — Email verification
POST /forgot-password — Request password reset
POST /reset-password — Reset password with token

Two-Factor Authentication (2FA)

POST /2fa/generate — Generate 2FA secret and QR code (protected)
POST /2fa/verify-setup — Verify initial 2FA setup (protected)
POST /2fa/enable — Enable 2FA and get recovery codes (protected)
POST /2fa/disable — Disable 2FA (protected)
POST /2fa/login-verify — Verify 2FA code during login (public)
POST /2fa/recovery-codes — Generate new recovery codes (protected)

Social Authentication

GET /auth/google/login — Initiate Google OAuth2 login
GET /auth/google/callback — Google OAuth2 callback
GET /auth/facebook/login — Initiate Facebook OAuth2 login
GET /auth/facebook/callback — Facebook OAuth2 callback
GET /auth/github/login — Initiate GitHub OAuth2 login
GET /auth/github/callback — GitHub OAuth2 callback

User Management

GET /profile — Get user profile (protected)
GET /auth/validate — Validate JWT token for external services (protected)

Activity Logs

GET /activity-logs — Get authenticated user's activity logs with pagination and filtering (protected)
GET /activity-logs/:id — Get specific activity log by ID (protected)
GET /activity-logs/event-types — Get available event types for filtering (protected)
GET /admin/activity-logs — Get all users' activity logs for admin use (protected)

📦 API Response Format

Success:

{
  "success": true,
  "data": { "token": "..." }
}

Error:

{
  "success": false,
  "error": "Invalid credentials"
}

🔒 Authentication Flow

Standard Authentication

Register/login returns JWT access & refresh tokens
Access token in Authorization: Bearer <token> header
Refresh token endpoint issues new access/refresh tokens

Two-Factor Authentication Flow

User enables 2FA via /2fa/generate, /2fa/verify-setup, and /2fa/enable
During login, if 2FA is enabled, a temporary token is returned
User provides TOTP code or recovery code via /2fa/login-verify
Final JWT tokens are issued upon successful 2FA verification

Social Authentication Flow

Redirect to provider login endpoint (e.g., /auth/google/login)
User authorizes with social provider
Provider redirects back to callback endpoint
JWT tokens are issued for authenticated user

📋 Activity Logs

Overview

The Activity Logs system provides comprehensive tracking of user actions for security auditing, compliance, and debugging purposes. All user activities are automatically logged with detailed context information.

Tracked Events

The following events are automatically logged:

LOGIN — User successfully logged in
LOGOUT — User logged out
REGISTER — New user registration
PASSWORD_CHANGE — User changed their password
PASSWORD_RESET — User reset their password
EMAIL_VERIFY — User verified their email address
2FA_ENABLE — User enabled two-factor authentication
2FA_DISABLE — User disabled two-factor authentication
2FA_LOGIN — User logged in using 2FA
TOKEN_REFRESH — User refreshed their access token
SOCIAL_LOGIN — User logged in via social media (Google, Facebook, GitHub)
PROFILE_ACCESS — User accessed their profile
RECOVERY_CODE_USED — User used a 2FA recovery code
RECOVERY_CODE_GEN — User generated new 2FA recovery codes

Features

Pagination: Efficient handling of large datasets with configurable page sizes (1-100 items)
Filtering: Filter by event type, date ranges (YYYY-MM-DD format)
Security: Users can only access their own logs; admin endpoint for comprehensive access
Performance: Optimized database queries with proper indexing on UserID, EventType, and Timestamp
Audit Trail: IP addresses, user agents, and contextual details captured for forensic analysis

API Examples

Get User's Recent Login Activities

curl -X GET "http://localhost:8080/activity-logs?event_type=LOGIN&limit=5" \
     -H "Authorization: Bearer your-jwt-token"

Get Activities from Date Range

curl -X GET "http://localhost:8080/activity-logs?start_date=2024-01-01&end_date=2024-01-31&page=1&limit=20" \
     -H "Authorization: Bearer your-jwt-token"

Get Available Event Types

curl -X GET "http://localhost:8080/activity-logs/event-types" \
     -H "Authorization: Bearer your-jwt-token"

Response Format

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "user_id": "987fcdeb-51a2-43d8-a456-426614174001",
      "event_type": "LOGIN",
      "timestamp": "2024-01-15T10:30:00Z",
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
      "details": {
        "login_method": "password",
        "success": true
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total_records": 45,
    "total_pages": 3,
    "has_next": true,
    "has_previous": false
  }
}

🧪 Testing

Automated Testing

Run all tests: make test or go test ./...
Coverage: Unit & integration tests for core logic and endpoints

Manual API Testing

Use the provided test script: ./test_api.sh
Test basic authentication flows and error handling
Interactive testing via Swagger UI at /swagger/index.html

🐳 Docker Configuration

Development Environment

# Start development environment with hot reload
make docker-dev
# or
./dev.sh  # Linux/Mac
dev.bat   # Windows

Production Environment

# Build and start production containers
make docker-compose-up
# or
docker-compose up -d --build

⚙️ Environment Variables

Required Configuration

# Database Configuration
DB_HOST=localhost          # postgres (for Docker)
DB_PORT=5432
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_NAME=auth_db

# Redis Configuration  
REDIS_ADDR=localhost:6379  # redis:6379 (for Docker)

# JWT Configuration
JWT_SECRET=supersecretjwtkey
ACCESS_TOKEN_EXPIRATION_MINUTES=15
REFRESH_TOKEN_EXPIRATION_HOURS=720

# Email Configuration
EMAIL_HOST=smtp.example.com
EMAIL_PORT=587
EMAIL_USERNAME=your_email@example.com
EMAIL_PASSWORD=your_email_password

# Social Authentication (OAuth2)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
FACEBOOK_CLIENT_ID=your_facebook_client_id
FACEBOOK_CLIENT_SECRET=your_facebook_client_secret
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

# Server Configuration
PORT=8080

Docker vs Local Development

For Docker Compose, use service names:

DB_HOST=postgres
REDIS_ADDR=redis:6379

For local development, use localhost:

DB_HOST=localhost
REDIS_ADDR=localhost:6379

🧩 Key Dependencies

Web Framework: Gin
Database: GORM + PostgreSQL
Caching: Go-Redis + Redis
Authentication: JWT, OAuth2
Configuration: Viper, godotenv
Validation: go-playground/validator
Email: gopkg.in/mail.v2
2FA: pquerna/otp, skip2/go-qrcode
Documentation: Swaggo/Swag
Development: Air (hot reload)

🧪 Development Workflow

make setup — Install dependencies and tools
make dev — Start development server with hot reload
make test — Run tests during development
make fmt — Format code before committing
make lint — Check code quality
./test_api.sh — Test API endpoints manually

🤝 Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

🛡️ Security

Please read SECURITY.md for information about reporting security vulnerabilities.

📚 Documentation

📄 License

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

gjovanovicst/golang-auth-api