auth/Documentaion/admin/ADMIN_DASHBOARD_SETUP.md

# Admin Security Dashboard - Setup Guide

## === ADMIN SECURITY VISUALIZER ===

This document explains how to configure and use the secure Authentication Admin Dashboard for monitoring security events.

---

## 📋 Prerequisites

1. **Admin User Account**: A user account with `role = 'security_admin'` in the database
2. **JWT Access Token**: Admin must authenticate and obtain a JWT token with admin role
3. **Environment Variables**: Required configuration (see below)

---

## 🔧 Configuration

### 1. Environment Variables

Add the following to your `.env` file:

```bash
# Enable admin dashboard
ENABLE_ADMIN_DASHBOARD=true

# Security alerting webhook (optional but recommended)
SECURITY_ALERT_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
SECURITY_ALERT_MIN_LEVEL=HIGH_RISK

# Admin rate limiting (optional, defaults provided)
ADMIN_RATE_LIMIT_MAX=100
ADMIN_RATE_LIMIT_WINDOW=900
```

### 2. Create Admin User

Update a user's role in the database:

```sql
UPDATE users 
SET role = 'security_admin' 
WHERE phone_number = '+919876543210';
```

**Note**: The `role` column must support the value `'security_admin'`. If your enum doesn't include this, you may need to update the enum type:

```sql
-- Check current enum values
SELECT unnest(enum_range(NULL::listing_role_enum));

-- If needed, add security_admin to the enum
ALTER TYPE listing_role_enum ADD VALUE 'security_admin';
```

### 3. CORS Configuration

**IMPORTANT**: Admin dashboard should NOT be accessible from public origins.

In production, ensure `CORS_ALLOWED_ORIGINS` only includes trusted domains:

```bash
# .env
CORS_ALLOWED_ORIGINS=https://admin.yourdomain.com,https://internal.yourdomain.com
```

**Never use `*` for CORS when admin endpoints are enabled.**

---

## 🚀 Usage

### 1. Obtain Admin Access Token

Admin must authenticate via the normal auth flow:

```bash
# Step 1: Request OTP
POST /auth/request-otp
{
  "phone_number": "+919876543210"
}

# Step 2: Verify OTP (returns access token)
POST /auth/verify-otp
{
  "phone_number": "+919876543210",
  "code": "123456"
}

# Response includes:
{
  "access_token": "eyJhbGc...",
  "refresh_token": "..."
}
```

### 2. Access Dashboard

**Option A: Browser (with token in localStorage)**

1. Open browser console
2. Set token: `localStorage.setItem('admin_token', 'YOUR_ACCESS_TOKEN')`
3. Navigate to: `https://yourdomain.com/admin/security-dashboard`

**Option B: API Direct Access**

```bash
GET /admin/security-events?risk_level=HIGH_RISK&limit=50
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### 3. Dashboard Features

- **Real-time Event Table**: View all authentication events
- **Risk Level Filtering**: Filter by INFO, SUSPICIOUS, HIGH_RISK
- **Search**: Search by User ID, Phone, or IP Address
- **Statistics**: 24-hour event counts by risk level
- **Auto-refresh**: Automatically updates every 15 seconds
- **Manual Refresh**: Click "Refresh" button anytime

---

## 🔒 Security Protections

### ✅ Implemented Security Measures

| Security Measure | Implementation |
|-----------------|----------------|
| **RBAC (Role-Based Access)** | `adminAuth` middleware checks `role === 'security_admin'` |
| **JWT Authentication** | All admin routes require valid Bearer token |
| **Rate Limiting** | 100 requests per 15 minutes per admin user |
| **Input Validation** | All query parameters sanitized and validated |
| **SQL Injection Prevention** | Parameterized queries only |
| **Output Sanitization** | All DB fields sanitized before JSON response |
| **XSS Prevention** | Dashboard uses `textContent` only (NO `innerHTML`) |
| **Clickjacking Protection** | `X-Frame-Options: DENY` header |
| **CORS Restrictions** | No public origins allowed |
| **Audit Logging** | All admin access logged to `auth_audit` |
| **HTTPS Enforcement** | HSTS header in production |
| **Feature Flag** | Dashboard only enabled when `ENABLE_ADMIN_DASHBOARD=true` |

### Security Headers

The dashboard and admin API endpoints include:

- `X-Frame-Options: DENY` - Prevents clickjacking
- `X-Content-Type-Options: nosniff` - Prevents MIME sniffing
- `X-XSS-Protection: 1; mode=block` - XSS protection
- `Strict-Transport-Security` - HTTPS enforcement (production)

---

## 📊 API Endpoints

### GET /admin/security-events

Retrieve security audit events with filtering and pagination.

**Query Parameters:**
- `risk_level` (optional): `INFO`, `SUSPICIOUS`, or `HIGH_RISK`
- `search` (optional): Search in user_id, phone, or ip_address
- `limit` (optional): Number of results (1-1000, default: 200)
- `offset` (optional): Pagination offset (default: 0)

**Response:**
```json
{
  "events": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "action": "otp_verify",
      "status": "failed",
      "risk_level": "HIGH_RISK",
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "device_id": "device-123",
      "phone": "***543210",
      "meta": {},
      "created_at": "2024-01-01T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 1000,
    "limit": 200,
    "offset": 0,
    "has_more": true
  },
  "stats": {
    "last_24h": {
      "total": 500,
      "high_risk": 10,
      "suspicious": 50,
      "info": 440
    }
  }
}
```

**Authentication:** Required (Bearer token with `security_admin` role)

---

## 🚨 Alerting Integration

The dashboard integrates with the existing `triggerSecurityAlert()` function in `auditLogger.js`.

### When Alerts Fire

Alerts are sent to `SECURITY_ALERT_WEBHOOK_URL` for:

1. **HIGH_RISK Events**: All events with `risk_level = 'HIGH_RISK'`
2. **Anomaly Detection**: Events flagged by `checkAnomalies()`:
   - 5+ failed OTP attempts in 1 hour
   - 3+ HIGH_RISK events from same IP in 15 minutes

### Webhook Payload Format

The webhook receives a Slack-compatible JSON payload:

```json
{
  "text": "🚨 Security Alert: HIGH_RISK",
  "attachments": [{
    "color": "danger",
    "fields": [
      {"title": "Event Type", "value": "login", "short": true},
      {"title": "Risk Level", "value": "HIGH_RISK (high)", "short": true},
      {"title": "IP Address", "value": "192.168.1.1", "short": true}
    ]
  }],
  "metadata": {
    "event_id": "uuid",
    "risk_level": "HIGH_RISK",
    "severity": "high",
    "event_type": "login",
    "ip_address": "192.168.1.1"
  }
}
```

### Setting Up Slack Webhook

1. Go to https://api.slack.com/apps
2. Create a new app or select existing
3. Enable "Incoming Webhooks"
4. Create webhook URL
5. Add to `.env`: `SECURITY_ALERT_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL`

---

## 🛡️ Security Best Practices

### 1. Access Control

- **Limit Admin Users**: Only grant `security_admin` role to trusted personnel
- **Rotate Tokens**: Admin tokens should be rotated regularly
- **Monitor Admin Access**: Review `auth_audit` logs for admin actions

### 2. Network Security

- **HTTPS Only**: Always use HTTPS in production
- **VPN/Private Network**: Consider restricting admin dashboard to internal networks
- **IP Whitelisting**: Optionally restrict admin endpoints by IP at reverse proxy level

### 3. Token Management

- **Short Token TTL**: Use shorter access token TTL for admin users (e.g., 5 minutes)
- **Token Storage**: Store admin tokens securely (never in localStorage for production)
- **Logout**: Implement proper logout to revoke tokens

### 4. Monitoring

- **Alert on Admin Access**: Set up alerts for admin dashboard access
- **Review Logs**: Regularly review `auth_audit` for admin actions
- **Anomaly Detection**: Monitor for unusual admin access patterns

---

## 🐛 Troubleshooting

### Dashboard Not Loading

1. **Check Feature Flag**: Ensure `ENABLE_ADMIN_DASHBOARD=true` in `.env`
2. **Check Token**: Verify admin token is valid and has `security_admin` role
3. **Check CORS**: Ensure your origin is in `CORS_ALLOWED_ORIGINS`
4. **Check Console**: Open browser console for error messages

### 403 Forbidden

- User role is not `security_admin`
- Token is invalid or expired
- CORS origin not whitelisted

### 401 Unauthorized

- Missing `Authorization` header
- Invalid JWT token
- Token expired

### No Events Showing

- Check database connection
- Verify `auth_audit` table exists
- Check filters (risk_level, search) aren't too restrictive

---

## 📝 Files Created/Modified

### New Files

- `src/middleware/adminAuth.js` - Admin role check middleware
- `src/middleware/adminRateLimit.js` - Rate limiting for admin routes
- `src/middleware/securityHeaders.js` - Security headers middleware
- `src/routes/adminRoutes.js` - Admin API endpoints
- `public/security-dashboard.html` - Admin dashboard UI

### Modified Files

- `src/index.js` - Added admin route mounting
- `src/services/auditLogger.js` - Already has `triggerSecurityAlert()` (from previous task)

---

## ✅ Verification Checklist

- [ ] `ENABLE_ADMIN_DASHBOARD=true` in `.env`
- [ ] Admin user has `role = 'security_admin'` in database
- [ ] Admin can obtain JWT token via normal auth flow
- [ ] Dashboard accessible at `/admin/security-dashboard`
- [ ] API endpoint `/admin/security-events` returns data
- [ ] Security headers present (check browser DevTools)
- [ ] Rate limiting works (test with >100 requests)
- [ ] Webhook alerts fire for HIGH_RISK events (if configured)
- [ ] CORS properly configured (no public origins)
- [ ] All admin access logged to `auth_audit` table

---

## 🔗 Related Documentation

- `SECURITY_SCENARIOS.md` - Security threat scenarios
- `DEVICE_MANAGEMENT.md` - Device management features
- `src/services/auditLogger.js` - Audit logging implementation

---

## 📞 Support

For issues or questions:
1. Check browser console for errors
2. Review server logs
3. Verify database connectivity
4. Check environment variables

---

**Last Updated**: 2024-01-01
**Version**: 1.0.0