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:

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

### Changing Session Timeout

In `app.py`, modify the timeout value:

```python
check_session_timeout(60)  # 60 minutes instead of 30
```

### Custom Password Requirements

Add validation in `src/utils/auth.py`:

```python
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**
   ```python
   # Delete users.json and create new admin account
   ```

2. **Use Environment Variables**
   ```python
   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!