Admin Dashboard

Admin Dashboard Documentation

Overview

The Conformo admin dashboard provides secure access to audit logs and platform management features. It implements role-based access control (RBAC) with mandatory two-factor authentication (2FA) for admin users, ensuring compliance with Italian and EU regulations (GDPR).

Features

1. Role-Based Access Control

Admin Role

• Stored in the database (users.role column)
• Can be set to 'admin' or 'user' (default)
• Admin role grants access to:
  • Audit log viewing and filtering
  • Log export functionality
  • Platform statistics
  • User management (future enhancement)

Access Control

• Implemented at both backend middleware and frontend component levels
• Non-admin users attempting to access admin routes receive a 403 Forbidden error
• Backend validates role on every API request to admin endpoints

2. Two-Factor Authentication (2FA)

Implementation

• Uses Time-based One-Time Password (TOTP) algorithm
• Compatible with standard authenticator apps (Google Authenticator, Authy, etc.)
• Provides 8 backup codes for account recovery

Setup Process

1. Admin user initiates 2FA setup via API
2. System generates secret and QR code
3. User scans QR code with authenticator app
4. User enters verification code to enable 2FA
5. System provides backup codes (store securely!)

Login Flow with 2FA

1. User enters email and password
2. If 2FA is enabled, system returns temporary token
3. User enters 6-digit TOTP code
4. System verifies code and issues full authentication tokens
5. User gains access to admin dashboard

API Endpoints

• POST /api/auth/2fa/setup - Initialize 2FA setup
• POST /api/auth/2fa/verify - Enable 2FA with verification code
• POST /api/auth/2fa/disable - Disable 2FA (requires current code)
• GET /api/auth/2fa/status - Check if 2FA is enabled
• POST /api/auth/2fa/verify-login - Complete login with 2FA code

3. Audit Log Management

Log Types

• Authentication Logs: Registration, login, logout, password resets, email verification
• Admin Actions: Dashboard access, log exports, configuration changes

Filtering Options

• Email: Filter by user email address
• Event Type: Filter by specific event (login, logout, etc.)
• IP Address: Filter by source IP address
• Outcome: Success or failure
• Date Range: From/To datetime filters
• Environment: Automatic filtering by current environment (production/staging/development)

Timestamp Format

• All timestamps displayed in Central European Time (CET/Europe/Rome)
• Format: dd/mm/yyyy HH:MM
• Complies with Italian date/time conventions

Export Functionality

• Export filtered logs as CSV file
• Max 10,000 rows per export
• Includes all log fields: ID, timestamp, event type, email, IP, user agent, etc.
• Filename format: audit_logs_YYYY-MM-DD.csv

4. Italian Localization

All admin dashboard text is in Italian:

• Navigation and menu items
• Form labels and placeholders
• Error messages
• Success notifications
• Table headers and content
• Event type translations

5. GDPR Compliance

Log Retention

• Auth logs: 13 months (1 year + 1 month buffer)
• Admin action logs: 25 months (2 years + 1 month buffer)
• Automated cleanup functions provided in database migrations
• Should be scheduled via cron job or similar

Data Privacy

• Personal data minimization in logs
• Secure storage with encrypted connections
• Access logging for all admin actions
• Right to access (users can request their logs)
• Right to erasure (logs older than retention period)

Audit Trail Every admin action is logged:

• Dashboard access
• Log viewing
• Log exports
• Configuration changes
• Includes: admin user ID, action type, timestamp, IP, user agent

Setup Instructions

1. Database Migration

Run the main schema to create required tables:

-- Run backend/db/schema.sql
psql -d your_database < backend/db/schema.sql

Optional: Set up log retention policy:

-- Run backend/db/migrations/log_retention_policy.sql
psql -d your_database < backend/db/migrations/log_retention_policy.sql

-- Schedule cleanup (example cron job, adjust as needed)
0 2 * * 0 psql -d your_database -c "SELECT cleanup_old_auth_logs(); SELECT cleanup_old_admin_action_logs();"

2. Create Admin User

Update an existing user to have admin role:

UPDATE users 
SET role = 'admin' 
WHERE email = 'admin@yourcompany.com';

3. Environment Configuration

Add to your .env file:

# Environment identifier (important for log filtering)
ENVIRONMENT=production  # or staging, development

# Optional: Fallback admin emails (for backward compatibility)
ADMIN_EMAILS=admin@yourcompany.com,admin2@yourcompany.com

4. Enable 2FA for Admin Users

Via API (recommended)

After logging in as admin:

1. Call POST /api/auth/2fa/setup:

   curl -X POST https://your-domain.com/api/auth/2fa/setup \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
   

2. Scan the QR code with authenticator app

3. Call POST /api/auth/2fa/verify with the code:

   curl -X POST https://your-domain.com/api/auth/2fa/verify \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"token": "123456"}'
   

4. Store backup codes securely!

Via Frontend (when UI is implemented)

Navigate to admin settings and follow the 2FA setup wizard.

Usage

Accessing the Dashboard

1. Navigate to /admin or /admin/dashboard
2. If not logged in, you’ll be redirected to login
3. After login (with 2FA if enabled), dashboard loads
4. Non-admin users see “Access Denied” message

Viewing Audit Logs

1. Navigate to “Log di Audit” tab
2. Logs from current environment are displayed automatically
3. Use filters to narrow results:
   • Enter email to find logs for specific user
   • Select event type from dropdown
   • Enter IP address
   • Select outcome (success/failure)
   • Set date range
4. Click “Applica Filtri” to apply
5. Click “Resetta” to clear all filters

Exporting Logs

1. Apply desired filters
2. Click “Esporta CSV” button
3. CSV file downloads automatically
4. Export action is logged for audit trail

Security Best Practices

1. Mandatory 2FA: All admin users should enable 2FA
2. Strong Passwords: Enforce password policy (min 12 characters)
3. Regular Reviews: Periodically review audit logs for suspicious activity
4. Access Limits: Only grant admin role to necessary personnel
5. Backup Codes: Store backup codes in secure password manager
6. Monitor Exports: Track who exports logs and when
7. Log Retention: Run cleanup tasks regularly to maintain compliance
8. Secure Access: Always use HTTPS in production
9. Session Management: Implement appropriate session timeouts
10. IP Whitelisting: Consider restricting admin access to known IPs (optional)

API Reference

Admin Dashboard Endpoints

All endpoints require authentication and admin role.

Get Audit Logs

GET /api/auth/logs

Query Parameters

• email (string): Filter by email
• event_type (string): Filter by event type
• ip_address (string): Filter by IP
• success (boolean): Filter by outcome
• from (ISO datetime): Start date
• to (ISO datetime): End date
• environment (string): Environment filter (auto-detected if not provided)
• limit (number): Results per page (default: 20, max: 100)
• cursor (string): Pagination cursor
• order (string): Sort order (‘asc’ or ‘desc’)

Response

{
  "data": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "email_attempted": "user@example.com",
      "event_type": "login_success",
      "success": true,
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "origin": "INTERNAL",
      "session_id": "uuid",
      "environment": "production",
      "metadata": {},
      "created_at": "2025-10-17T12:00:00Z"
    }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "cursor_string"
  },
  "count": 20
}

Export Audit Logs

GET /api/auth/logs/export

Same query parameters as above. Returns CSV file.

Get Audit Log Stats

GET /api/auth/logs/stats?days=30

Returns aggregated statistics.

Get Single Log Entry

GET /api/auth/logs/:id

Returns detailed log entry with user information.

Troubleshooting

Admin Access Issues

Problem: User has admin role but can’t access dashboard

Solutions:

1. Check database role: SELECT role FROM users WHERE email = 'user@example.com'
2. Verify authentication token is valid
3. Check browser console for error messages
4. Verify backend environment variable ENVIRONMENT is set

Problem: 2FA code not working

Solutions:

1. Check device time is synchronized (TOTP depends on accurate time)
2. Try backup code instead
3. Regenerate 2FA setup if needed
4. Verify 6-digit code is entered correctly

Log Viewing Issues

Problem: No logs appearing

Solutions:

1. Check environment filter matches your setup
2. Verify logs exist in database: SELECT COUNT(*) FROM auth_logs WHERE environment = 'production'
3. Clear all filters and try again
4. Check browser network tab for API errors

Problem: Export fails

Solutions:

1. Reduce date range (max 10,000 rows)
2. Check backend logs for errors
3. Verify user has admin role
4. Try with fewer filters applied

Admin Preferences

The Admin Preferences page provides comprehensive configuration management for all platform settings.

Accessing Preferences

1. Navigate to Admin Dashboard
2. Click on “Preferenze” tab
3. View and modify settings organized by category

Preference Categories

Available Settings:

1. Authentication & Security
   • 2FA enforcement for admins
   • Session timeout configuration
   • Password complexity requirements
   • Login attempt limits
   • Account lockout settings
2. Audit Logging & GDPR
   • Log retention periods
   • Audit logging toggles
   • Pseudonymization options
3. Environment Configuration
   • Environment selection (development/staging/production)
4. Email & Notifications
   • FROM_EMAIL configuration
   • Trusted domain allowlist
5. Feature Flags
   • Landing page visibility
   • User registration toggle
   • GDPR questionnaire
   • Risk scoring
   • Subscriptions
   • Other platform features
6. Localization & Timezone
   • Default locale (Italian/English)
   • Timezone (Europe/Rome default)
   • Timestamp format
7. Export/Reporting
   • Max export rows
   • Export filename prefix
   • CSV/PDF export toggles
8. Privacy/GDPR
   • Right to erasure
   • Retention enforcement
   • Auto cleanup scheduling
9. Advanced/Operational
   • Rate limiting settings
   • Webhook integrations

Using Admin Preferences

Modifying Settings:

1. Navigate to desired category
2. Update field values
3. Click “Salva Modifiche” (Save Changes)
4. Success message confirms save
5. All changes are logged in audit trail

Validation:

• All inputs are validated
• Error messages shown in Italian
• Numeric fields have min/max ranges
• Email and URL formats checked

Audit Trail:

• Every change is logged
• Includes admin user, timestamp, IP
• Changes viewable in Audit Logs

Business Value

The preferences system provides:

• GDPR Compliance: Configure retention, pseudonymization, right to erasure
• Localization: Italian-first configuration (CET timezone, it-IT locale)
• Security: Enforce 2FA, password policies, rate limiting
• Operational Efficiency: No developer needed for configuration changes
• Audit Trail: Full traceability for compliance requirements

Documentation

For detailed information:

• User Guide: ADMIN_PREFERENCES.md - Complete settings reference
• API Documentation: ADMIN_PREFERENCES_API.md - API contracts and usage

Future Enhancements

Planned improvements for the admin dashboard:

1. Statistics Dashboard: Visual charts and graphs for log data
2. Real-time Alerts: Notifications for suspicious activity
3. User Management: Create/edit/disable users
4. Role Management: Create custom roles with specific permissions
5. Advanced Filtering: Save filter presets, complex queries
6. Bulk Operations: Bulk user actions
7. API Keys Management: Generate and manage API keys
8. System Settings: Configure platform-wide settings ✅ IMPLEMENTED (Admin Preferences)
9. Backup Management: Scheduled backups and restore
10. Compliance Reports: Generate compliance reports for auditors

Support

For issues or questions:

• GitHub Issues: https://github.com/GrewingM/conformo/issues
• Documentation: /docs
• Admin Preferences: ADMIN_PREFERENCES.md
• Admin Preferences API: ADMIN_PREFERENCES_API.md
• Technical Architecture: TECHNICAL_ARCHITECTURE.md
• Authentication: AUTHENTICATION.md