predictive_analysis/AUTHENTICATION.md

🔐 Authentication Guide

This guide explains how to use the authentication system in the Student Success Predictor application.

🚀 Quick Start

Default Credentials

The application comes with two pre-configured demo accounts:

Administrator Account:

• Username: admin
• Password: admin123
• Role: Admin (full access + user management)

Educator Account:

• Username: educator
• Password: hello123
• Role: Educator (prediction access + export features)

First Login

1. Run the application: streamlit run app.py
2. You'll see the login screen with demo credentials displayed
3. Use either account above to log in
4. Important: Change default passwords in production!

👥 User Roles & Permissions

🏷️ Role Hierarchy

1. Admin - Full access to everything

   • Use prediction features
   • Export prediction reports
   • Manage users (add/delete)
   • Access admin panel

2. Educator - Educational staff access

   • Use prediction features
   • Export prediction reports
   • Cannot manage users

3. User - Basic access (for future use)

   • Use prediction features only
   • No export capabilities
   • No admin functions

🛠️ User Management (Admin Only)

Adding New Users

1. Login as admin
2. In the sidebar, expand "👨‍💼 Admin Panel"
3. Fill out the "Add New User" form:
   • Username (unique identifier)
   • Password (secure password)
   • Full Name (display name)
   • Role (user/educator/admin)
4. Click "➕ Add User"

Managing Existing Users

• View all users in the "Existing Users" section
• Delete users with the 🗑️ button (except yourself)
• Users are stored in users.json file

🔒 Security Features

Password Hashing

• All passwords are hashed using SHA-256
• Plain text passwords are never stored
• Secure credential verification

Session Management

• Automatic session timeout (30 minutes of inactivity)
• Secure session state management
• Proper logout functionality

Role-Based Access Control

• Different features available based on user role
• Hierarchical permission system
• Secure admin-only functions

📁 Data Storage

User Data File

• Users stored in: users.json
• Contains hashed passwords only
• Includes user roles and names
• Automatically created on first run

Session Storage

• Uses Streamlit's built-in session state
• No persistent session storage
• Secure temporary authentication

🔧 Customization

Adding New Roles

Edit src/utils/auth.py and modify:

role_hierarchy = {
    "admin": 3,
    "educator": 2,
    "student": 1,  # Add new role here
    "user": 0
}

Changing Session Timeout

In app.py, modify the timeout value:

check_session_timeout(60)  # 60 minutes instead of 30

Custom Password Requirements

Add validation in src/utils/auth.py:

def validate_password(password: str) -> bool:
    # Add your password requirements here
    return len(password) >= 8 and any(c.isdigit() for c in password)

🚨 Production Security

Important Security Steps for Production:

1. Change Default Passwords

   # Delete users.json and create new admin account
   

2. Use Environment Variables

   import os
   ADMIN_PASSWORD = os.getenv('ADMIN_PASSWORD', 'secure_password')
   

3. Implement Database Storage

   • Replace JSON file with proper database
   • Use encrypted connection strings
   • Implement proper backup procedures

4. Add Password Complexity Requirements

   • Minimum length requirements
   • Special character requirements
   • Password expiration policies

5. Implement Rate Limiting

   • Prevent brute force attacks
   • Temporary account lockouts
   • Login attempt logging

6. Enable HTTPS

   • Secure data transmission
   • SSL/TLS certificates
   • Secure cookie settings

🐛 Troubleshooting

Login Issues

Problem: "Invalid username or password"

• Solution: Check credentials carefully, case-sensitive

Problem: Session expired message

• Solution: Normal after 30 minutes, just log in again

Problem: Cannot access admin features

• Solution: Ensure you're logged in with admin role

File Permission Issues

Problem: Cannot create users.json

• Solution: Check write permissions in app directory

Problem: Cannot save new users

• Solution: Ensure sufficient disk space and permissions

📝 Development Notes

File Structure

src/utils/auth.py          # Main authentication module
users.json                 # User credentials storage (auto-created)
app.py                     # Main app with auth integration

Key Functions

• require_auth() - Decorator for protected functions
• check_role_permission() - Role-based access control
• render_admin_panel() - User management interface
• check_session_timeout() - Session timeout handling

This authentication system provides a secure, user-friendly way to control access to your Student Success Predictor application!