PyAirtable Authentication Service

A high-performance authentication and authorization service built with Go, Fiber v3, and designed for microservices architecture.

🚀 Features

Authentication

• ✅ User registration with email verification
• ✅ JWT-based authentication (access + refresh tokens)
• ✅ Password reset with secure tokens
• ✅ OAuth2 support (Google, GitHub, Microsoft)
• 🔄 Two-factor authentication (TOTP) [Planned]
• ✅ Session management with Redis
• ✅ Secure password hashing (Argon2)

Authorization

• ✅ Role-based access control (RBAC)
• ✅ Fine-grained permissions system
• ✅ API key management
• ✅ Permission caching with Redis
• ✅ Tenant isolation support

Security

• ✅ Advanced password validation
• ✅ Rate limiting (IP & user-based)
• ✅ Brute force protection
• ✅ Comprehensive audit logging
• ✅ Token revocation
• ✅ CORS protection
• ✅ Security headers

Operations

• ✅ Prometheus metrics
• ✅ Structured logging (Zap)
• ✅ Graceful shutdown
• ✅ Health checks
• ✅ Docker support
• ✅ Kubernetes manifests
• ✅ Local development with Minikube

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   API Gateway   │────│   Auth Service  │────│   PostgreSQL    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                               │
                       ┌─────────────────┐
                       │      Redis      │
                       │   (Sessions)    │
                       └─────────────────┘

📦 Tech Stack

• Language: Go 1.22
• Web Framework: Fiber v3
• Database: PostgreSQL with GORM
• Cache/Sessions: Redis
• Authentication: JWT (golang-jwt/jwt)
• Password Hashing: Argon2
• Validation: go-playground/validator
• Logging: Zap
• Metrics: Prometheus
• Testing: Testify
• Deployment: Docker + Kubernetes

🚀 Quick Start

Prerequisites

• Go 1.22+
• Docker & Docker Compose
• Minikube (for K8s development)
• PostgreSQL 15+
• Redis 7+

1. Local Setup

# Clone the repository (if not already done)
git clone <repository-url>
cd pyairtable-auth-service-go

# Run the setup script
./scripts/local-setup.sh

# Start development environment
make dev-start

2. Using Docker Compose

# Start all services
docker-compose up -d

# Check logs
docker-compose logs -f auth-service

# Stop services
docker-compose down

3. Using Minikube

# Setup and deploy to Minikube
make local-full

# Or step by step:
make minikube-setup
make minikube-deploy
make minikube-port-forward

🔧 Development

Environment Configuration

Copy .env.example to .env and update the values:

cp .env.example .env

Key configurations:

• JWT_SECRET: Strong secret for JWT signing
• OAuth credentials for social login
• Database and Redis connection strings

Available Commands

# Development
make build          # Build the application
make test           # Run tests
make run            # Run locally
make dev-start      # Start full dev environment

# Docker
make docker-build   # Build Docker image
make docker-run     # Run in Docker

# Kubernetes
make k8s-deploy     # Deploy to K8s
make k8s-logs       # View logs
make k8s-status     # Check status

# Quality
make lint           # Run linter
make test-coverage  # Test with coverage
make security       # Security scan

# See all commands
make help

Testing

# Run all tests
make test

# Run with coverage
make test-coverage

# Run benchmarks
make benchmark

# Run with race detection
make test-race

📡 API Endpoints

Authentication

• POST /api/v1/auth/register - User registration
• POST /api/v1/auth/login - User login
• POST /api/v1/auth/logout - User logout
• POST /api/v1/auth/refresh - Refresh access token
• POST /api/v1/auth/verify-email - Verify email address
• POST /api/v1/auth/forgot-password - Request password reset
• POST /api/v1/auth/reset-password - Reset password

Two-Factor Authentication

• POST /api/v1/auth/2fa/setup - Setup 2FA
• POST /api/v1/auth/2fa/verify - Verify 2FA code
• POST /api/v1/auth/2fa/disable - Disable 2FA

OAuth

• GET /api/v1/oauth/google - Google OAuth login
• GET /api/v1/oauth/google/callback - Google OAuth callback
• GET /api/v1/oauth/github - GitHub OAuth login
• GET /api/v1/oauth/github/callback - GitHub OAuth callback
• GET /api/v1/oauth/microsoft - Microsoft OAuth login
• GET /api/v1/oauth/microsoft/callback - Microsoft OAuth callback

User Management

• GET /api/v1/auth/me - Get current user
• GET /api/v1/auth/permissions - Get user permissions

Admin (Requires admin role)

• GET /api/v1/admin/users - List users
• GET /api/v1/admin/users/:id - Get user by ID
• PUT /api/v1/admin/users/:id/roles - Update user roles
• DELETE /api/v1/admin/users/:id - Delete user
• GET /api/v1/admin/audit-logs - Get audit logs

Health & Metrics

• GET /health - Health check
• GET /metrics - Prometheus metrics

🔐 Security Features

Password Security

• Argon2 hashing with configurable parameters
• Strength requirements (length, character types)
• Common password detection
• Password history (planned)

Brute Force Protection

• Failed login attempt tracking
• Progressive delays
• Account lockout after threshold
• IP-based rate limiting

Token Security

• JWT with short expiration (15 minutes default)
• Refresh token rotation
• Token revocation support
• Secure token storage

Audit Logging

• All authentication events
• Admin actions
• Failed access attempts
• IP and user agent tracking

🏢 Integration with Infrastructure

This service integrates with the broader PyAirtable infrastructure:

Service Discovery

• Works with API Gateway for routing
• Registers with service mesh (Istio)
• Exposes health checks for load balancers

Shared Components

• Uses pyairtable-go-shared library
• Common models and utilities
• Shared middleware and configurations

Database

• PostgreSQL with connection pooling
• Automatic migrations
• Read replicas support (planned)

Caching

• Redis for session storage
• Permission caching
• Rate limit storage

📊 Monitoring

Metrics

• Request/response metrics
• Authentication success/failure rates
• JWT token generation/validation
• Database query performance

Logging

• Structured JSON logging
• Request tracing with correlation IDs
• Error logging with stack traces
• Audit trail for security events

Health Checks

• Database connectivity
• Redis connectivity
• Service readiness
• External service dependencies

🚢 Deployment

Docker

# Build image
docker build -t pyairtable/auth-service:latest .

# Run container
docker run -p 8080:8080 --env-file .env pyairtable/auth-service:latest

Kubernetes

# Deploy to namespace
kubectl apply -k deployments/k8s/

# Check status
kubectl get pods -n pyairtable-auth

Environment-Specific Deployments

• Local: Minikube with single replica
• Development: Multi-replica with debug logging
• Staging: Production-like with monitoring
• Production: High availability with security hardening

🧪 Testing Strategy

Unit Tests

• Repository layer tests
• Service layer tests
• Handler tests with mocked dependencies
• Utility function tests

Integration Tests

• Database integration
• Redis integration
• HTTP endpoint tests
• OAuth flow tests

Load Tests

• Authentication throughput
• Concurrent user sessions
• Rate limiting effectiveness
• Database connection pooling

🔗 Dependencies

Core Dependencies

• fiber/v3 - Web framework
• gorm - ORM for PostgreSQL
• redis/go-redis/v9 - Redis client
• golang-jwt/jwt/v5 - JWT implementation
• golang.org/x/crypto - Cryptographic functions

Development Dependencies

• testify - Testing framework
• golangci-lint - Code linting
• swaggo/swag - API documentation
• prometheus/client_golang - Metrics

🤝 Contributing

1. Follow Go best practices and project conventions
2. Write comprehensive tests for new features
3. Update API documentation for endpoint changes
4. Ensure security best practices are followed
5. Add monitoring and logging for new features

📄 License

This project is part of the PyAirtable ecosystem. See LICENSE file for details.

🆘 Support

For support and questions:

• Create an issue in the repository
• Check existing documentation
• Review the API documentation at /swagger/

---

Built with ❤️ for high-performance authentication at scale