Enterprise Authentication & Authorization System (Production Ready)

Build a production-ready authentication system similar to:

• Devfolio
• Unstop
• GitHub
• LinkedIn
• Google

This module is the foundation of the entire platform.

Every feature depends on authentication:

User Registration
Profile Creation
Event Registration
Organization Creation
Team Formation
Project Submission
Judging Portal
Admin Dashboard
Payments
Certificates
Community

---

Business Requirements

Goals

• Secure user authentication
• Protect platform resources
• Support millions of users
• Prevent account abuse
• Enable social login
• Support multiple organizations
• Enterprise-grade security

---

Authentication Flow

User
 ↓
Signup
 ↓
Email Verification
 ↓
Profile Creation
 ↓
Login
 ↓
Access Token
 ↓
Refresh Token
 ↓
Authenticated Session

---

Features

User Registration

Normal Signup

Fields:

Full Name
Email
Password
Confirm Password
Country
Terms Accepted

Validation:

Name: 3-100 chars

Email:
Valid format
Unique

Password:
Min 8 chars
Uppercase
Lowercase
Number
Special Character

---

Social Login

Google OAuth

Continue with Google

GitHub OAuth

Continue with GitHub

LinkedIn OAuth

Continue with LinkedIn

Future

Microsoft
Discord
Apple

---

Email Verification

After signup:

User Registers
↓
Email Sent
↓
Verification Link
↓
User Clicks Link
↓
Account Verified

Verification Link:

/auth/verify-email?token=xxxxx

---

Login System

Email Login

Email
Password

Social Login

Google
GitHub
LinkedIn

---

Forgot Password

Flow:

Forgot Password
↓
Email Link
↓
Token Validation
↓
Reset Password
↓
Success

Token Expiry:

15 Minutes

---

Password Reset Rules

Minimum 8 chars

Uppercase
Lowercase
Number
Special Character

Prevent:

Reuse Last 5 Passwords

---

Session Management

Every login creates a session.

User can view:

Current Device
Browser
IP Address
Country
Last Active

Example:

Chrome - Windows
Chrome - Linux
Mobile App

User actions:

Logout Device
Logout All Devices

---

JWT Architecture

Access Token

Purpose:

API Authorization

Expiry:

15 Minutes

Payload:

{
  userId: string;
  email: string;
  role: string;
}

---

Refresh Token

Purpose:

Generate New Access Token

Expiry:

30 Days

Stored:

HttpOnly Cookie

---

Security Layer

Password Hashing

Use:

Argon2

Fallback:

bcrypt

Never store:

Plain Password

---

Rate Limiting

Protect:

Login
Signup
Forgot Password
Verification

Example:

5 Attempts
Per Minute

---

Brute Force Protection

After:

10 Failed Logins

Account:

Locked for 30 Minutes

---

CAPTCHA

Enable when:

Multiple Failed Attempts

Use:

Cloudflare Turnstile
reCAPTCHA

---

Two Factor Authentication (2FA)

Support:

Google Authenticator
Authy
Microsoft Authenticator

Flow:

Login
↓
Password Valid
↓
OTP Required
↓
Verify OTP
↓
Success

---

Device Tracking

Store:

{
  id: string;
  userId: string;
  browser: string;
  os: string;
  ip: string;
  country: string;
  lastSeen: Date;
}

---

Authorization (RBAC)

Roles:

SUPER_ADMIN
ADMIN
ORGANIZATION_OWNER
ORGANIZATION_ADMIN
JUDGE
MENTOR
VOLUNTEER
USER

---

Permissions Matrix

USER

View Events
Register Events
Create Team
Submit Projects

---

JUDGE

Review Projects
Score Projects

---

ORGANIZATION_ADMIN

Manage Events
Manage Team
Manage Mentors

---

SUPER_ADMIN

Everything

---

Database Schema

User

{
  id: string;

  fullName: string;

  email: string;

  passwordHash: string;

  profileImage: string | null;

  role: string;

  emailVerified: boolean;

  twoFactorEnabled: boolean;

  status: string;

  createdAt: Date;

  updatedAt: Date;
}

---

Session

{
  id: string;

  userId: string;

  refreshTokenHash: string;

  ipAddress: string;

  userAgent: string;

  expiresAt: Date;

  createdAt: Date;
}

---

Email Verification

{
  id: string;

  userId: string;

  token: string;

  expiresAt: Date;
}

---

Password Reset

{
  id: string;

  userId: string;

  token: string;

  expiresAt: Date;
}

---

OAuth Account

{
  id: string;

  userId: string;

  provider: string;

  providerAccountId: string;
}

---

API Endpoints

Signup

POST /api/auth/signup

---

Verify Email

POST /api/auth/verify-email

---

Login

POST /api/auth/login

---

Logout

POST /api/auth/logout

---

Logout All Devices

POST /api/auth/logout-all

---

Refresh Token

POST /api/auth/refresh

---

Forgot Password

POST /api/auth/forgot-password

---

Reset Password

POST /api/auth/reset-password

---

Enable 2FA

POST /api/auth/2fa/enable

---

Verify 2FA

POST /api/auth/2fa/verify

---

Frontend Pages

Public

/login
/signup
/forgot-password
/reset-password
/verify-email

---

Protected

/dashboard
/settings/security
/settings/sessions

---

UI Components

LoginForm
SignupForm
OAuthButtons
ForgotPasswordForm
ResetPasswordForm
EmailVerificationBanner
SessionManager
TwoFactorSetup
SecuritySettings

---

Notifications

Email

Send:

Welcome Email
Verify Email
Password Reset
Password Changed
New Login Detected
2FA Enabled

---

In-App

Login Alerts
Security Alerts
Account Changes

---

Audit Logging

Track:

Signup
Login
Logout
Password Change
Password Reset
Role Change
Email Change
2FA Changes

Schema:

{
  actorId: string;
  action: string;
  metadata: object;
  createdAt: Date;
}

---

Performance Requirements

API Response

< 200ms

Authentication Success Rate

99.99%

Concurrent Users

100,000+

---

Security Requirements

OWASP Compliance

Protect against:

SQL Injection
XSS
CSRF
Session Hijacking
Brute Force
Credential Stuffing

---

Cookies

HttpOnly
Secure
SameSite=Strict

---

Infrastructure

Redis

Use for:

Session Cache
OTP Storage
Rate Limiting
Token Blacklist

---

PostgreSQL

Store:

Users
Sessions
Roles
Audit Logs

---

Tech Stack

Frontend

• Next.js 15
• TypeScript
• Tailwind CSS
• ShadCN UI
• React Hook Form
• Zod

Backend

• NestJS
• Prisma
• PostgreSQL
• Redis

Security

• Argon2
• JWT
• Passport.js
• OAuth 2.0

Email

• [Resend](https://resend.com?utm_source=chatgpt.com)
• [SendGrid](https://sendgrid.com?utm_source=chatgpt.com)

---

Acceptance Criteria

✅ User can signup with email/password
✅ Email verification works
✅ Social login works (Google/GitHub/LinkedIn)
✅ Login & logout work
✅ Refresh token rotation works
✅ Forgot password works
✅ Session management works
✅ RBAC implemented
✅ 2FA implemented
✅ Audit logging implemented
✅ Rate limiting enabled
✅ CAPTCHA protection enabled
✅ OWASP security checks passed
✅ Mobile responsive UI
✅ Production deployment ready