build-auth-system

---
name: build-auth-system
description: >
  Build comprehensive API authentication and authorization system
shortcut: auth
category: api
difficulty: intermediate
estimated_time: 5-10 minutes
version: 2.0.0
---
# Build API Authentication System

Implements a complete authentication and authorization system for your API, supporting JWT tokens, OAuth2 flows, API keys, session-based auth, and multi-factor authentication. Generates production-ready auth middleware, user management, and role-based access control.

## When to Use

Use this command when:

- Starting a new API that requires user authentication
- Adding authentication to an existing unprotected API
- Migrating from one auth method to another
- Implementing OAuth2 provider or consumer
- Adding multi-factor authentication (MFA/2FA)
- Setting up role-based or permission-based access control
- Building a SaaS application with tenant isolation

Do NOT use this command for:

- Static websites without user accounts
- Public APIs that don't require authentication
- Internal microservices using service mesh auth
- Simple basic auth for development environments

## Prerequisites

Before running this command, ensure:

- [ ] Database or user store is configured
- [ ] Framework/language for API is chosen
- [ ] Security requirements are defined
- [ ] Compliance requirements identified (GDPR, SOC2, etc.)
- [ ] Session storage decided (Redis, database, memory)

## Process

### Step 1: Analyze Authentication Requirements

Examines your application to determine the best auth strategy:

- Identifies user types and roles
- Determines session vs stateless requirements
- Evaluates security compliance needs
- Assesses scalability requirements
- Reviews existing auth infrastructure

### Step 2: Generate Authentication Components

Creates the core authentication system:

- User model with secure password storage
- Authentication middleware/filters
- Token generation and validation
- Session management if required
- Password reset and recovery flows

### Step 3: Implement Authorization Logic

Sets up access control mechanisms:

- Role-based access control (RBAC)
- Permission-based authorization
- Resource-level permissions
- API endpoint protection
- Tenant isolation for multi-tenant apps

### Step 4: Configure Security Features

Implements additional security measures:

- Rate limiting for auth endpoints
- Account lockout after failed attempts
- Password complexity requirements
- Token refresh mechanisms
- Audit logging for auth events

## Output Format

```
auth-system/
├── models/
│   ├── user.js              # User model with auth fields
│   ├── role.js              # Role definitions
│   └── permission.js        # Permission mappings
├── middleware/
│   ├── authenticate.js      # Auth verification middleware
│   ├── authorize.js         # Permission checking
│   └── rate-limit.js        # Rate limiting
├── services/
│   ├── auth.service.js      # Core auth logic
│   ├── token.service.js     # Token management
│   └── password.service.js  # Password utilities
├── routes/
│   ├── auth.routes.js       # Auth endpoints
│   └── user.routes.js       # User management
├── config/
│   ├── auth.config.js       # Auth configuration
│   └── jwt.config.js        # JWT settings
└── tests/
    └── auth.test.js         # Auth system tests
```

## Examples

### Example 1: JWT-based Authentication for REST API

**User Input:**

```
/auth --type jwt --framework express
```

**Generated Authentication Service:**

```javascript
// services/auth.service.js
const jwt = require('jsonwebtoken');
const bcrypt = require('bcrypt');
const crypto = require('crypto');

class AuthService {
  constructor() {
    this.saltRounds = 12;
    this.tokenExpiry = '1h';
    this.refreshTokenExpiry = '7d';
  }

  async register(userData) {
    // Validate input
    this.validateRegistration(userData);

    // Check if user exists
    const existing = await User.findOne({ email: userData.email });
    if (existing) {
      throw new ConflictError('User already exists');
    }

    // Hash password
    const hashedPassword = await bcrypt.hash(userData.password, this.saltRounds);

    // Create user
    const user = await User.create({
      ...userData,
      password: hashedPassword,
      emailVerificationToken: crypto.randomBytes(32).toString('hex'),
      emailVerified: false,
      createdAt: new Date()
    });

    // Send verification email
    await EmailService.sendVerification(user.email, user.emailVerificationToken);

    // Generate tokens
    const { accessToken, refreshToken } = await this.generateTokens(user);

    return {
      user: this.sanitizeUser(user),
      accessToken,
      refreshToken
    };
  }

  async login(email, password) {
    // Find user
    const user = await User.findOne({ email }).select('+password');
    if (!user) {
      throw new UnauthorizedError('Invalid credentials');
    }

    // Verify password
    const isValid = await bcrypt.compare(password, user.password);
    if (!isValid) {
      await this.recordFailedAttempt(user);
      throw new UnauthorizedError('Invalid credentials');
    }

    // Check if account is locked
    if (user.lockedUntil && user.lockedUntil > Date.now()) {
      throw new ForbiddenError('Account temporarily locked');
    }

    // Check email verification
    if (!user.emailVerified && process.env.REQUIRE_EMAIL_VERIFICATION === 'true') {
      throw new ForbiddenError('Email not verified');
    }

    // Reset failed attempts
    await this.resetFailedAttempts(user);

    // Generate tokens
    const { accessToken, refreshToken } = await this.generateTokens(user);

    // Update last login
    user.lastLogin = new Date();
    await user.save();

    return {
      user: this.sanitizeUser(user),
      accessToken,
      refreshToken
    };
  }

  async generateTokens(user) {
    const payload = {
      id: user.id,
      email: user.email,
      roles: user.roles
    };

    const accessToken = jwt.sign(
      payload,
      process.env.JWT_SECRET,
      { expiresIn: this.tokenExpiry }
    );

    const refreshToken = jwt.sign(
      { id: user.id, type: 'refresh' },
      process.env.JWT_REFRESH_SECRET,
      { expiresIn: this.refreshTokenExpiry }
    );

    // Store refresh token
    await RefreshToken.create({
      userId: user.id,
      token: refreshToken,
      expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
    });

    return { accessToken, refreshToken };
  }

  async refreshAccessToken(refreshToken) {
    // Verify refresh token
    const decoded = jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET);

    // Check if token exists and is valid
    const storedToken = await RefreshToken.findOne({
      token: refreshToken,
      userId: decoded.id,
      expiresAt: { $gt: new Date() }
    });

    if (!storedToken) {
      throw new UnauthorizedError('Invalid refresh token');
    }

    // Get user
    const user = await User.findById(decoded.id);
    if (!user) {
      throw new UnauthorizedError('User not found');
    }

    // Generate new access token
    const accessToken = jwt.sign(
      {
        id: user.id,
        email: user.email,
        roles: user.roles
      },
      process.env.JWT_SECRET,
      { expiresIn: this.tokenExpiry }
    );

    return { accessToken };
  }

  async logout(userId, refreshToken) {
    // Remove refresh token
    await RefreshToken.deleteOne({ userId, token: refreshToken });

    // Optional: Add token to blacklist for immediate invalidation
    await BlacklistedToken.create({
      token: refreshToken,
      expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
    });

    return { message: 'Logged out successfully' };
  }
}
```

**Generated Middleware:**

```javascript
// middleware/authenticate.js
const jwt = require('jsonwebtoken');

const authenticate = async (req, res, next) => {
  try {
    // Extract token
    const token = extractToken(req);
    if (!token) {
      return res.status(401).json({ error: 'No token provided' });
    }

    // Check blacklist
    const isBlacklisted = await BlacklistedToken.exists({ token });
    if (isBlacklisted) {
      return res.status(401).json({ error: 'Token revoked' });
    }

    // Verify token
    const decoded = jwt.verify(token, process.env.JWT_SECRET);

    // Get user
    const user = await User.findById(decoded.id).select('-password');
    if (!user) {
      return res.status(401).json({ error: 'User not found' });
    }

    // Attach to request
    req.user = user;
    req.userId = user.id;

    next();
  } catch (error) {
    if (error.name === 'TokenExpiredError') {
      return res.status(401).json({ error: 'Token expired' });
    }
    if (error.name === 'JsonWebTokenError') {
      return res.status(401).json({ error: 'Invalid token' });
    }
    return res.status(500).json({ error: 'Authentication failed' });
  }
};

const authorize = (...allowedRoles) => {
  return (req, res, next) => {
    if (!req.user) {
      return res.status(401).json({ error: 'Not authenticated' });
    }

    const hasRole = req.user.roles.some(role => allowedRoles.includes(role));
    if (!hasRole) {
      return res.status(403).json({ error: 'Insufficient permissions' });
    }

    next();
  };
};
```

### Example 2: OAuth2 Provider Implementation

**User Input:**

```
/auth --type oauth2-provider --framework fastapi
```

**Generated OAuth2 Provider:**

```python
# services/oauth2_provider.py
from datetime import datetime, timedelta
from typing import Optional
import secrets
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from jose import JWTError, jwt
from passlib.context import CryptContext
from sqlalchemy.orm import Session

class OAuth2Provider:
    def __init__(self):
        self.pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
        self.oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
        self.SECRET_KEY = os.getenv("SECRET_KEY")
        self.ALGORITHM = "HS256"
        self.ACCESS_TOKEN_EXPIRE_MINUTES = 30
        self.REFRESH_TOKEN_EXPIRE_DAYS = 7

    async def create_client(self, client_data: dict, db: Session):
        """Register OAuth2 client application"""
        client = OAuth2Client(
            client_id=secrets.token_urlsafe(32),
            client_secret=self.hash_secret(secrets.token_urlsafe(64)),
            name=client_data["name"],
            redirect_uris=client_data["redirect_uris"],
            grant_types=client_data["grant_types"],
            response_types=client_data["response_types"],
            scope=client_data["scope"],
            created_at=datetime.utcnow()
        )
        db.add(client)
        db.commit()
        return client

    async def authorization_code_grant(
        self,
        client_id: str,
        redirect_uri: str,
        scope: str,
        user: User,
        db: Session
    ):
        """Handle authorization code grant flow"""
        # Verify client
        client = db.query(OAuth2Client).filter(
            OAuth2Client.client_id == client_id
        ).first()

        if not client or redirect_uri not in client.redirect_uris:
            raise HTTPException(
                status_code=400,
                detail="Invalid client or redirect URI"
            )

        # Generate authorization code
        auth_code = AuthorizationCode(
            code=secrets.token_urlsafe(32),
            client_id=client_id,
            user_id=user.id,
            redirect_uri=redirect_uri,
            scope=scope,
            expires_at=datetime.utcnow() + timedelta(minutes=10)
        )
        db.add(auth_code)
        db.commit()

        return auth_code.code

    async def exchange_code_for_token(
        self,
        code: str,
        client_id: str,
        client_secret: str,
        redirect_uri: str,
        db: Session
    ):
        """Exchange authorization code for access token"""
        # Verify client credentials
        client = await self.verify_client(client_id, client_secret, db)

        # Verify authorization code
        auth_code = db.query(AuthorizationCode).filter(
            AuthorizationCode.code == code,
            AuthorizationCode.client_id == client_id,
            AuthorizationCode.redirect_uri == redirect_uri,
            AuthorizationCode.expires_at > datetime.utcnow()
        ).first()

        if not auth_code:
            raise HTTPException(
                status_code=400,
                detail="Invalid or expired authorization code"
            )

        # Generate tokens
        access_token = self.create_access_token(
            data={"sub": str(auth_code.user_id), "scope": auth_code.scope}
        )
        refresh_token = self.create_refresh_token(
            data={"sub": str(auth_code.user_id)}
        )

        # Delete used authorization code
        db.delete(auth_code)
        db.commit()

        return {
            "access_token": access_token,
            "refresh_token": refresh_token,
            "token_type": "bearer",
            "expires_in": self.ACCESS_TOKEN_EXPIRE_MINUTES * 60
        }
```

### Example 3: API Key Authentication

**User Input:**

```
/auth --type api-key --with-rate-limiting
```

**Generated API Key System:**

```javascript
// services/apikey.service.js
const crypto = require('crypto');
const { RateLimiter } = require('./rate-limiter');

class APIKeyService {
  constructor() {
    this.rateLimiter = new RateLimiter();
  }

  async generateAPIKey(userId, name, permissions = []) {
    // Generate secure API key
    const apiKey = `sk_${process.env.NODE_ENV}_${crypto.randomBytes(32).toString('hex')}`;
    const hashedKey = crypto
      .createHash('sha256')
      .update(apiKey)
      .digest('hex');

    // Store key metadata
    const keyRecord = await APIKey.create({
      userId,
      name,
      keyHash: hashedKey,
      prefix: apiKey.substring(0, 7),
      permissions,
      lastUsed: null,
      expiresAt: null, // Optional expiration
      createdAt: new Date()
    });

    // Return full key only once
    return {
      id: keyRecord.id,
      apiKey, // Only shown once
      name,
      permissions,
      createdAt: keyRecord.createdAt
    };
  }

  async validateAPIKey(apiKey) {
    // Hash the provided key
    const hashedKey = crypto
      .createHash('sha256')
      .update(apiKey)
      .digest('hex');

    // Find key record
    const keyRecord = await APIKey.findOne({
      keyHash: hashedKey,
      $or: [
        { expiresAt: null },
        { expiresAt: { $gt: new Date() } }
      ]
    });

    if (!keyRecord) {
      throw new UnauthorizedError('Invalid API key');
    }

    // Check rate limits
    const rateLimitOk = await this.rateLimiter.checkLimit(
      keyRecord.id,
      keyRecord.rateLimit || 1000
    );

    if (!rateLimitOk) {
      throw new TooManyRequestsError('Rate limit exceeded');
    }

    // Update last used
    keyRecord.lastUsed = new Date();
    keyRecord.usageCount += 1;
    await keyRecord.save();

    // Get user
    const user = await User.findById(keyRecord.userId);

    return {
      user,
      permissions: keyRecord.permissions,
      keyId: keyRecord.id
    };
  }
}
```

## Error Handling

### Error: Password Too Weak

**Symptoms:** Registration fails with password validation error
**Cause:** Password doesn't meet complexity requirements
**Solution:**

```javascript
// Implement password strength validation
const passwordStrength = {
  minLength: 8,
  requireUppercase: true,
  requireLowercase: true,
  requireNumbers: true,
  requireSymbols: true
};
```

### Error: Token Expired

**Symptoms:** 401 Unauthorized after token lifetime
**Cause:** Access token has expired
**Solution:**

```javascript
// Use refresh token to get new access token
const { accessToken } = await authService.refreshAccessToken(refreshToken);
```

### Error: Account Locked

**Symptoms:** 403 Forbidden after multiple failed attempts
**Cause:** Brute force protection triggered
**Solution:**

```javascript
// Implement exponential backoff
const lockoutDuration = Math.pow(2, failedAttempts) * 60 * 1000;
```

## Configuration Options

### Option: `--type`

- **Purpose:** Choose authentication method
- **Values:** `jwt`, `oauth2`, `api-key`, `session`, `basic`
- **Default:** `jwt`
- **Example:** `/auth --type oauth2`

### Option: `--with-mfa`

- **Purpose:** Add multi-factor authentication
- **Default:** false
- **Example:** `/auth --with-mfa`

### Option: `--with-social`

- **Purpose:** Add social login providers
- **Default:** false
- **Example:** `/auth --with-social google,github,facebook`

## Best Practices

✅ **DO:**

- Hash passwords with bcrypt or argon2
- Use secure random tokens
- Implement rate limiting
- Log authentication events
- Use HTTPS only
- Validate email addresses
- Implement password reset flow

❌ **DON'T:**

- Store plain text passwords
- Use MD5 or SHA1 for passwords
- Create predictable tokens
- Log sensitive information
- Allow unlimited login attempts
- Trust client-side validation only

💡 **TIPS:**

- Use refresh tokens for better UX
- Implement remember me functionality carefully
- Add CAPTCHA for public endpoints
- Monitor for suspicious activity
- Implement session invalidation

## Related Commands

- `/api-rate-limiter` - Add rate limiting to APIs
- `/api-security-scanner` - Scan for vulnerabilities
- `/user-management` - User CRUD operations
- `/session-manager` - Session handling utilities

## Performance Considerations

- **Token generation:** <50ms
- **Password hashing:** 100-300ms (intentionally slow)
- **Token validation:** <10ms
- **Session lookup:** <5ms with caching

## Security Notes

⚠️ **Security Considerations:**

- Always use HTTPS in production
- Store secrets in environment variables
- Rotate JWT secrets regularly
- Implement CSRF protection
- Use secure session cookies
- Enable CORS appropriately
- Audit authentication logs

## Troubleshooting

### Issue: JWT secret not set

**Solution:** Set JWT_SECRET environment variable with strong random value

### Issue: Sessions not persisting

**Solution:** Configure session store (Redis recommended for production)

### Issue: OAuth2 redirect not working

**Solution:** Verify redirect URI is whitelisted in OAuth2 provider

## Version History

- **v2.0.0** - Complete rewrite with multiple auth methods
- **v1.0.0** - Basic JWT implementation

---

*Last updated: 2025-10-11*
*Quality score: 9+/10*
*Tested with: Express, FastAPI, Django, Spring Boot*