A complete, enterprise-grade auth backend — JWT, OAuth 2.0 Provider, MFA, RBAC, Social Login —
in a single deployable Go binary.

   

Explore the API →   ·   Report Bug   ·   Request Feature   ·   Contributing

---

💡 Why Auth Server?

Building authentication from scratch is tedious, error-prone, and takes weeks away from your actual product. Auth Server gives you a battle-tested, self-hosted auth backend that deploys in under 5 minutes.

Ship your product, not your auth layer.

For Developers Drop-in backend for any frontend stack Official TypeScript SDK with React & Next.js bindings Interactive Swagger docs — test every endpoint live Clean Architecture — easy to fork, extend, or contribute to Zero vendor lock-in — MIT licensed, self-hosted

For Teams & Startups Self-hosted — your data never leaves your infrastructure Full OAuth 2.0 Provider — let third-party apps auth against you RBAC, audit logs, and account lockout built-in Docker-ready with one-command deployment Built-in keep-alive pinger for free-tier hosting

---

🧬 Feature Matrix

🔐 Core Authentication	🛡 Security & Compliance
• JWT access & refresh token rotation • Email/password registration & login • Email verification & password reset • Social login — Google & GitHub • Multi-Factor Auth (TOTP) • Session management & multi-device logout	• BCrypt password hashing • Redis-backed rate limiting • Token blacklist & revocation • CSP, CORS & security headers • Account lockout on failed attempts • Audit trail logging
🌐 OAuth 2.0 Provider	🧩 Developer Experience
• Authorization Code flow (PKCE-ready) • Client registration & management • User consent screen • Per-client provider configuration • Token exchange & /userinfo endpoint • Client secret rotation & deletion	• TypeScript SDK on npm • React hooks — AuthProvider + useAuth • Next.js SSR adapter • Admin SDK for user management • Interactive Swagger docs • Docker Compose one-command setup

🗺 Roadmap

Status	Feature	Description
🔜	Webhooks	Notify external systems on auth events (login, register, lock)
🔜	SAML / SSO	Enterprise single sign-on for corporate identity providers
🔜	Passkeys / WebAuthn	Passwordless authentication with biometrics
🔜	Flutter SDK	Mobile-first auth client for iOS & Android
💭	Go SDK	Server-to-server auth client for microservice architectures
💭	Magic Links	Passwordless email-based login flow

Have an idea? Open a discussion →

---

🏛 Architecture

Auth Server follows Clean Architecture with strict separation of concerns:

auth-server/
├── cmd/server/main.go              # Entry point — Gin setup, GORM migration, graceful shutdown
├── internal/
│   ├── config/                     # Configuration loading, DB & Redis initialization
│   ├── routes/                     # Route definitions & middleware registration
│   ├── handler/                    # HTTP handlers — request parsing & response formatting
│   ├── service/                    # Business logic — auth flows, OAuth, MFA, email
│   ├── repository/                 # Data access layer — isolated GORM queries
│   ├── models/                     # GORM models — User, RefreshToken, OAuthClient, etc.
│   ├── middleware/                 # Auth, CORS, CSP, rate limiting, recovery
│   ├── dto/                        # Request/response data transfer objects
│   └── utils/                      # Helpers — validation, error types, JWT claims
├── clients/ts/                     # Official TypeScript SDK (published to npm)
├── templates/                      # Email templates (HTML)
├── docs/                           # Swagger UI & generated API spec
└── docker-compose.yml              # PostgreSQL + Redis orchestration

---

🛠 Tech Stack

Layer	Technology	Purpose
Language	Go 1.25+	High-performance compiled backend
Framework	Gin Gonic	Fast HTTP router with middleware pipeline
Database	PostgreSQL 15+	Relational data store via GORM ORM
Cache	Redis 7+	Rate limiting, token blacklist, sessions
Auth	JWT + OAuth 2.0 + TOTP	Industry-standard protocols
Hashing	BCrypt	Secure password storage
Email	SMTP (Gmail, SendGrid, etc.)	Transactional email delivery
Docs	Swagger / OpenAPI 3.0	Interactive API documentation
SDK	TypeScript	React, Next.js, & Node.js bindings
Deploy	Docker & Docker Compose	Containerized deployment

---

🚀 Quick Start

Prerequisites

• Go 1.25+  ·  Docker & Docker Compose  ·  PostgreSQL 15+  ·  Redis 7+

Option A — Docker (Recommended)

git clone https://github.com/roshankumar0036singh/auth-server.git
cd auth-server
cp .env.example .env        # ← configure your secrets
docker compose up --build -d

Server runs at http://localhost:8080  ·  Swagger UI at /swagger/

Option B — Local Development

git clone https://github.com/roshankumar0036singh/auth-server.git
cd auth-server

# Install dependencies
go mod download

# Configure environment
cp .env.example .env

# Start PostgreSQL & Redis
docker compose up -d db redis

# Run the server
go run cmd/server/main.go

Option C — Makefile

make run          # Start the server
make test         # Run all tests
make swagger      # Regenerate API docs
make build-prod   # Static production binary

---

📡 API Overview

Full interactive docs →

Authentication

Method	Endpoint	Description
POST	/api/auth/register	Create a new account
POST	/api/auth/login	Authenticate with credentials
POST	/api/auth/login/mfa	Complete MFA challenge
POST	/api/auth/refresh	Refresh access token
POST	/api/auth/logout	Revoke current session
POST	/api/auth/logout-all	Revoke all sessions

User Management

Method	Endpoint	Description
GET	/api/auth/me	Get current user profile
PUT	/api/auth/profile	Update profile
POST	/api/auth/password	Change password
DELETE	/api/auth/me	Delete account
GET	/api/auth/sessions	List active sessions
DELETE	/api/auth/sessions/:id	Revoke specific session
GET	/api/auth/audit-logs	View audit trail

Email & Verification

Method	Endpoint	Description
GET	/api/auth/verify-email	Verify email address
POST	/api/auth/resend-verification	Resend verification email
POST	/api/auth/forgot-password	Request password reset
POST	/api/auth/reset-password	Reset password with token

MFA (Multi-Factor Authentication)

Method	Endpoint	Description
POST	/api/auth/mfa/enable	Generate TOTP secret
POST	/api/auth/mfa/verify	Verify and activate MFA
POST	/api/auth/mfa/disable	Disable MFA

Social Login

Method	Endpoint	Description
GET	/api/auth/google/login	Initiate Google OAuth
GET	/api/auth/google/callback	Google OAuth callback
GET	/api/auth/github/login	Initiate GitHub OAuth
GET	/api/auth/github/callback	GitHub OAuth callback

OAuth 2.0 Provider

Method	Endpoint	Description
GET	/oauth/authorize	Authorization endpoint
POST	/oauth/token	Token exchange
GET	/oauth/userinfo	Get authorized user info
POST	/api/auth/oauth/clients	Register OAuth client
GET	/api/auth/oauth/clients	List your OAuth clients
DELETE	/api/auth/oauth/clients/:id	Delete OAuth client

Admin (Requires admin Role)

Method	Endpoint	Description
GET	/api/admin/users	List all users (paginated)
POST	/api/admin/users/:id/lock	Lock user account
POST	/api/admin/users/:id/unlock	Unlock user account
DELETE	/api/admin/users/:id	Delete user account

---

📦 TypeScript SDK

The official SDK is published on npm as @authserver/client.

npm install @authserver/client

Vanilla TypeScript

import { AuthClient } from '@authserver/client';

const auth = new AuthClient({
  serverUrl: 'https://your-auth-server.com',
  clientId: 'your-client-id',
  storage: 'localStorage',
  keepAlive: true,  // prevents server sleep on free-tier hosting
});

// Register & login
await auth.register('[email protected]', 'securePassword123', 'John');
const session = await auth.login('[email protected]', 'securePassword123');

// Automatic token refresh — just call methods
const user = await auth.getUser();

// Listen for auth events
auth.on('logout', () => console.log('User signed out'));

// Cleanup when done
auth.destroy();

React

import { AuthProvider, useAuth } from '@authserver/client/react';

function App() {
  return (
    <AuthProvider serverUrl="https://your-auth-server.com" clientId="your-client-id">
      <Dashboard />
    </AuthProvider>
  );
}

function Dashboard() {
  const { user, login, logout, isAuthenticated } = useAuth();

  if (!isAuthenticated) return <button onClick={() => login('[email protected]', 'pw')}>Login</button>;
  return <p>Welcome, {user?.name}! <button onClick={logout}>Logout</button></p>;
}

Next.js (SSR)

import { createNextAuthClient } from '@authserver/client/nextjs';

export const { withAuth, getSession, handlers } = createNextAuthClient({
  serverUrl: 'https://your-auth-server.com',
  clientId: 'your-client-id',
});

Admin SDK

import { AdminClient } from '@authserver/client/admin';

const admin = new AdminClient({
  serverUrl: 'https://your-auth-server.com',
  adminToken: 'your-admin-jwt',
});

const users = await admin.listUsers();
await admin.lockUser('user-uuid');

Full SDK documentation →

---

⚙ Environment Configuration

Copy .env.example to .env and configure:

Variable	Required	Description
APP_ENV	Yes	development or production
DATABASE_URL	Yes	PostgreSQL connection string
REDIS_URL	Yes	Redis connection string
JWT_SECRET	Yes	Access token signing key
JWT_REFRESH_SECRET	Yes	Refresh token signing key
SMTP_HOST	Yes	Email SMTP server
SMTP_USER / SMTP_PASSWORD	Yes	SMTP credentials
GOOGLE_CLIENT_ID / SECRET	No	Google OAuth (optional)
GITHUB_CLIENT_ID / SECRET	No	GitHub OAuth (optional)
PING_URL	No	Self-ping URL to prevent free-tier sleep
ENCRYPTION_KEY	Yes	32-byte key for sensitive data encryption
BCRYPT_ROUNDS	No	Password hashing cost (default: 12)

---

🧪 Testing

# Run all tests
go test ./...

# Run tests with verbose output
go test ./internal/service -v

# Run a specific test
go test ./internal/service -run TestTokenService_GenerateAccessToken -v

# Generate HTML coverage report
go test ./... -coverprofile=coverage.out && go tool cover -html=coverage.out

---

🐳 Deployment

Docker Compose (Full Stack)

docker compose up --build -d

This starts:

• Auth Server on port 8080
• PostgreSQL on port 5432
• Redis on port 6379

Production Build

# Static binary (no CGO dependencies)
make build-prod

# Or manually:
CGO_ENABLED=0 GOOS=linux go build -o auth-server cmd/server/main.go

Cloud Deployment

Platform	Guide
Render	Connect repo → set env vars → auto-deploy
Railway	One-click Go template → configure .env
Fly.io	fly launch → fly deploy
AWS / GCP / Azure	Docker image or binary deployment

Tip: Set PING_URL to your public URL's /health endpoint to prevent free-tier platforms from putting your server to sleep. Auth Server includes a built-in self-pinger that hits this URL every 14 minutes.

---

🤝 Contributing

We welcome contributions of all sizes — from typo fixes to new features.

# Fork → Clone → Branch
git checkout -b feature/your-feature

# Make changes → Test
go test ./...

# Commit (we use Conventional Commits)
git commit -m "feat: add amazing feature"

# Push → Open PR
git push origin feature/your-feature

Read the full Contributing Guide →  ·  Code of Conduct →

Ways to Contribute

• Bug reports — Open an issue
• Feature requests — Start a discussion
• Documentation — Improve guides, add examples
• Tests — Increase coverage, add edge cases
• Integrations — Build SDKs for other languages

---

📄 License

Distributed under the MIT License. See LICENSE for details.

Author

Roshan Kumar Singh

---

If Auth Server helped you, consider giving it a ⭐