degreelink

Advisor Portal Authentication System

Overview

This document describes the secure authentication system implemented for the advisor portal. The system uses email verification with time-limited codes to ensure that only authorized advisors can access administrative features.

Security Architecture

Why Email Verification?

The system uses email verification with time-limited codes instead of simple email whitelist checking because:

  1. Prevents Email Theft: Someone with access to the whitelist cannot simply enter a whitelisted email and gain access - they need access to the actual email inbox to receive the verification code.

  2. Time-Limited Access: Codes expire after 15 minutes, limiting the window of opportunity for potential attacks.

  3. Rate Limiting: After 5 failed verification attempts, accounts are temporarily locked for 30 minutes.

  4. Session Management: Authenticated sessions last 1 hour before requiring re-authentication.

  5. Audit Trail: All authentication attempts are logged with timestamps for security monitoring.

How It Works

For Advisors

  1. Click the Settings Icon in the top-right corner (or select Advisor during onboarding)
  2. Enter Email: Enter your university email address
  3. Request Code: Click “Send Access Code” - a 6-digit code will be sent to your email
  4. Verify Code: Enter the 6-digit code from your email (code expires in 15 minutes)
  5. Access Granted: You’re now in advisor mode with access to all advisor features for 1 hour

For Administrators

Administrators can manage the advisor whitelist through the App Management page (only visible in advisor mode):

  1. Add Single Email: Enter an email address manually
  2. Bulk Upload: Upload a CSV file with multiple email addresses
  3. Remove Advisors: Remove advisors from the whitelist
  4. Monitor Status: View active sessions and locked accounts

Technical Implementation

Backend Components

1. Database Model (models/advisor_auth.py)

The AdvisorAuth model stores:

2. API Routes (routes/advisor_auth.py)

Authentication Endpoints:

Admin Endpoints (require admin token):

3. Authentication Middleware (auth.py)

@require_advisor Decorator:

@require_advisor
def protected_route():
    # This route requires valid advisor authentication
    pass

The decorator:

Frontend Components

1. Advisor Auth Modal (components/AdvisorAuthModal.jsx)

A multi-step modal that handles:

2. App Management Page (pages/AppManagementPage.jsx)

Admin interface for managing advisor whitelist:

3. API Service Updates (services/api.js)

New methods:

Token management:

4. UI Changes

AppShell:

App.jsx:

useAppController.js:

Database Migration

A new migration file creates the advisor_auth table:

# Run migration (when backend is running)
flask db upgrade

Migration file: migrations/versions/a1b2c3d4e5f6_add_advisor_authentication_table.py

Email Configuration

The system includes a placeholder for email sending. To enable email:

  1. Choose an email service (SendGrid, AWS SES, etc.)
  2. Update send_access_code_email() in routes/advisor_auth.py:
def send_access_code_email(email, code):
    # Example with SendGrid
    import sendgrid
    from sendgrid.helpers.mail import Mail
    
    sg = sendgrid.SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
    
    message = Mail(
        from_email='noreply@university.edu',
        to_emails=email,
        subject='Your Advisor Portal Access Code',
        html_content=f'<p>Your access code is: <strong>{code}</strong></p><p>This code expires in 15 minutes.</p>'
    )
    
    sg.send(message)
    return True
  1. Add email service API key to .env:
SENDGRID_API_KEY=your_api_key_here

Security Features

1. Code Generation

2. Rate Limiting

3. Session Security

4. Token Management

5. Audit Trail

CSV Format for Bulk Upload

Create a CSV file with an email column:

email
advisor1@university.edu
advisor2@university.edu
advisor3@university.edu

Alternative (if no header):

advisor1@university.edu
advisor2@university.edu
advisor3@university.edu

The system will:

Testing the Implementation

1. Add Test Advisor

# Add yourself to whitelist (requires admin token)
curl -X POST http://localhost:5000/api/advisor-auth/whitelist \
  -H "Content-Type: application/json" \
  -H "X-Admin-Token: your_admin_token" \
  -d '{"email": "your@email.edu"}'

2. Request Code

curl -X POST http://localhost:5000/api/advisor-auth/request-code \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email.edu"}'

3. Verify Code (in development, check console for code)

curl -X POST http://localhost:5000/api/advisor-auth/verify-code \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email.edu", "code": "123456"}'

Future Enhancements

  1. Two-Factor Authentication: Add optional TOTP-based 2FA
  2. IP Whitelisting: Restrict access to specific IP ranges
  3. Audit Log UI: Dashboard for viewing authentication logs
  4. Role-Based Access: Different permission levels for advisors
  5. Password Reset: Add password recovery flow
  6. Email Templates: Rich HTML email templates
  7. SMS Codes: Alternative to email verification
  8. SSO Integration: Single sign-on with university systems

Troubleshooting

Codes Not Being Sent

Account Locked

Session Expired

Can’t Access Advisor Features

Files Changed/Created

Backend

Frontend

Admin Badge Removal

The admin mode badge can be removed from AdminBadge.jsx or wherever it was displayed, as the settings cog now serves as the access point for advisor features.

Implementation Date: November 20, 2025 Author: GitHub Copilot Status: Complete - Ready for Testing

This site is open source. Improve this page.