Auth Service

OAuth2/JWT authentication microservice. Supports multiple OAuth providers with PKCE for mobile and server-side flows for web apps.

Features

• OAuth2 Authentication: Google, Facebook, GitHub, Microsoft (PKCE flow for mobile)
• JWT Tokens: Access + refresh tokens with configurable expiry
• Web OAuth Flow: Generic server-side flow for web apps with redirect URI allowlist
• Account Linking: Automatic linking when same email exists across providers
• Security: CORS, rate limiting, security headers, constant-time comparisons
• Structured Logging: JSON logs with slog
• Health Checks: /health (with DB status) and /ready endpoints
• Graceful Shutdown: Clean connection handling with configurable timeout
• Database Migrations: Automated schema management on startup
• GDPR: Internal endpoint for user deletion (right to be forgotten)

Quick Start

cp .env.example .env    # Configure OAuth credentials + DB password
make build              # Build binary
make run                # Run locally

API Endpoints

Public

Method	Path	Description
GET	/health	Health check with database status
GET	/ready	Readiness probe
POST	/auth/token	Token exchange (mobile PKCE flow)
POST	/auth/refresh	Refresh access token
GET	/auth/{provider}	Initiate server-side OAuth
GET	/auth/{provider}/callback	OAuth provider callback
GET	/auth/web/{provider}	Web OAuth flow (redirect-based)
GET	/auth/web/{provider}/callback	Web OAuth callback

Protected (requires Bearer JWT)

Method	Path	Description
GET	/users/profile	Get current user profile
PUT	/users/profile	Update user profile
GET	/users/:id	Get user by ID

Internal (requires X-Internal-API-Key)

Method	Path	Description
POST	/validate/token	Validate JWT (service-to-service)
DELETE	/internal/users/:id	Delete user (GDPR)

Environment Variables

See .env.example for all configuration options.

Required:

• DB_PASSWORD — PostgreSQL password
• JWT_SECRET — Secret for signing JWTs (min 32 chars)
• GOOGLE_CLIENT_ID — Google OAuth client ID
• GOOGLE_CLIENT_SECRET — Google OAuth client secret

Testing

make test               # Unit tests
make test-verbose       # With race detector
make test-coverage      # Generate coverage report

Integration tests (require running PostgreSQL):

make test-integration

Project Structure

cmd/
  auth-service/       Application entry point
  migrate/            Standalone migration tool
internal/
  config/             Configuration from environment
  database/           Database connection + migration tests
  handlers/           HTTP request handlers
  logger/             Structured logging (slog)
  middleware/         Auth, CORS, rate limiting, security headers
  models/             Data structures
  services/           Business logic (JWT, OAuth, user management)
migrations/           PostgreSQL schema migrations
init-scripts/         Database initialization scripts

Deployment

Container image built by GitHub Actions and pushed to GHCR. Can be deployed via Docker Compose, Podman Quadlet, or any container orchestrator.

License

MIT