Rustelo/info/quick_start_auth.md

# Quick Start Guide: Authentication & Authorization System

This guide will help you get the comprehensive authentication system up and running quickly.

## 🚀 What You Get

### ✅ Complete Authentication System
- **JWT Authentication** with access and refresh tokens
- **Password-based login** with Argon2 hashing
- **OAuth2 Integration** (Google, GitHub, Discord, Microsoft)
- **Role-Based Access Control (RBAC)** with permissions
- **Secure Session Management** with HTTP-only cookies
- **Password Reset** functionality
- **Audit Logging** for all user actions

### ✅ Frontend Components
- **AuthProvider** - React-style authentication context
- **LoginForm** - Complete login UI with OAuth buttons
- **RegisterForm** - Registration with password strength indicator
- **Route Protection** - Authentication guards for pages

### ✅ Backend Security
- **CSRF Protection** - Built-in token validation
- **Rate Limiting** - Prevent brute force attacks
- **Security Headers** - Comprehensive HTTP security
- **Token Blacklisting** - Invalidate compromised tokens
- **Password Validation** - Strength requirements and common password detection

## 🏃‍♂️ Quick Setup (5 minutes)

### 1. Database Setup
```bash
# Install PostgreSQL (if not already installed)
# macOS
brew install postgresql

# Ubuntu/Debian
sudo apt install postgresql postgresql-contrib

# Create database
createdb rustelo_dev

# Run migrations
psql rustelo_dev < migrations/001_create_auth_tables.sql
```

### 2. Environment Configuration
Create `.env` file in the project root:
```bash
# Required - Database
DATABASE_URL=postgres://localhost:5432/rustelo_dev

# Required - JWT Security
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production

# Optional - OAuth (configure as needed)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
```

### 3. Start the Server
```bash
cargo leptos watch
```

### 4. Test Default Admin Account
- **Email:** `admin@example.com`
- **Password:** `admin123`
- **⚠️ Change this password immediately in production!**

## 🔌 Using the System

### Frontend Authentication

```rust
use leptos::prelude::*;
use auth::{AuthProvider, use_auth, LoginForm};

#[component]
fn App() -> impl IntoView {
    view! {
        <AuthProvider>
            <Router>
                <Routes>
                    <Route path="/login" view=LoginPage />
                    <Route path="/dashboard" view=ProtectedDashboard />
                </Routes>
            </Router>
        </AuthProvider>
    }
}

#[component]
fn LoginPage() -> impl IntoView {
    view! {
        <div class="min-h-screen flex items-center justify-center">
            <LoginForm />
        </div>
    }
}

#[component]
fn ProtectedDashboard() -> impl IntoView {
    let auth = use_auth();
    
    view! {
        <Show 
            when=move || auth.0.is_authenticated()
            fallback=move || view! { <Redirect path="/login" /> }
        >
            <div>
                <h1>"Welcome, " {move || auth.0.user().map(|u| u.display_name_or_username().to_string()).unwrap_or_default()}</h1>
                <button on:click=move |_| (auth.0.actions.logout)()>
                    "Logout"
                </button>
            </div>
        </Show>
    }
}
```

### Backend Route Protection

```rust
use auth::middleware::{require_auth, require_admin, AuthContext};
use axum::{Router, routing::get};

fn create_protected_routes() -> Router {
    Router::new()
        // Public routes
        .route("/", get(home_handler))
        
        // Protected routes (require login)
        .route("/profile", get(profile_handler))
        .layer(axum::middleware::from_fn(require_auth))
        
        // Admin routes
        .route("/admin", get(admin_handler))
        .layer(axum::middleware::from_fn(require_admin))
}

async fn profile_handler(auth: AuthContext) -> String {
    format!("Hello, {}!", auth.user().unwrap().username)
}
```

## 📡 API Endpoints Ready to Use

### Authentication
- `POST /api/auth/register` - Register new user
- `POST /api/auth/login` - Login with email/password
- `POST /api/auth/logout` - Logout current user
- `GET /api/auth/profile` - Get user profile
- `PUT /api/auth/profile` - Update profile

### OAuth (if configured)
- `GET /api/auth/oauth/providers` - List available providers
- `GET /api/auth/oauth/google/authorize` - Google OAuth URL
- `GET /api/auth/oauth/github/authorize` - GitHub OAuth URL

### Password Reset
- `POST /api/auth/password-reset/request` - Request reset
- `POST /api/auth/password-reset/confirm` - Confirm reset

## 🛡️ Security Features Enabled

### ✅ Built-in Security
- **CSRF Protection** - Automatic token validation
- **Rate Limiting** - 100 requests per minute per IP
- **Security Headers** - HSTS, CSP, X-Frame-Options, etc.
- **Password Hashing** - Argon2 with secure defaults
- **JWT Security** - HS256 signing, 15-minute access tokens

### ✅ Data Protection
- **HTTP-Only Cookies** - XSS protection
- **Secure Cookies** - HTTPS-only transmission
- **SameSite Cookies** - CSRF prevention
- **Input Validation** - SQL injection prevention

## 🎯 Role-Based Access Control

### Default Roles
```rust
// Check user roles
if user.has_role(&Role::Admin) {
    // Admin actions
}

if user.has_permission(&Permission::WriteContent) {
    // Content creation allowed
}
```

### Available Roles
- **Admin** - Full system access
- **Moderator** - Content management
- **User** - Standard user access  
- **Guest** - Read-only access

### Available Permissions
- **ReadUsers, WriteUsers, DeleteUsers**
- **ReadContent, WriteContent, DeleteContent**
- **ManageRoles, ManageSystem**

## 🔧 Configuration Options

### JWT Configuration
```bash
JWT_ACCESS_TOKEN_EXPIRES_IN=15   # minutes
JWT_REFRESH_TOKEN_EXPIRES_IN=7   # days
```

### Password Security
```bash
# Argon2 uses secure defaults, no configuration needed
```

### OAuth Configuration
```bash
OAUTH_REDIRECT_BASE_URL=http://localhost:3030/api/auth/oauth/callback
```

## 🐛 Common Issues & Solutions

### Database Connection Failed
```bash
# Check if PostgreSQL is running
pg_ctl -D /usr/local/var/postgres status

# Start if not running
brew services start postgresql
```

### OAuth Not Working
1. Verify redirect URLs match exactly in provider settings
2. Check client ID/secret are correct
3. Ensure HTTPS in production

### JWT Token Issues
1. Ensure `JWT_SECRET` is consistent across restarts
2. Check token expiration times
3. Verify server time synchronization

## 📈 Production Checklist

### ⚠️ Security (Critical)
- [ ] Change default admin password
- [ ] Use strong `JWT_SECRET` (64+ random characters)
- [ ] Enable HTTPS in production
- [ ] Set secure environment variables
- [ ] Review and update CORS settings

### 🔧 Performance
- [ ] Configure connection pooling
- [ ] Set up Redis for session storage (optional)
- [ ] Enable database query logging
- [ ] Monitor authentication metrics

### 📊 Monitoring
- [ ] Set up logging aggregation
- [ ] Monitor failed login attempts
- [ ] Track token refresh rates
- [ ] Alert on suspicious activity

## 📚 Next Steps

### Extend the System
1. **Add Multi-Factor Authentication**
   - TOTP support with `totp-lite`
   - SMS verification with Twilio

2. **Email Integration**
   - Password reset emails
   - Welcome emails
   - Security notifications

3. **Advanced Features**
   - WebAuthn/Passkeys
   - Social login providers
   - API key authentication

### Custom OAuth Provider
```rust
// Add custom OAuth provider
let custom_provider = OAuthProvider::Custom("company".to_string());
oauth_service.configure_custom_provider(custom_provider, config).await?;
```

## 🆘 Support & Documentation

- **Full Documentation:** [AUTH_README.md](AUTH_README.md)
- **Environment Setup:** [ENV_CONFIG.md](ENV_CONFIG.md)
- **Database Schema:** [migrations/001_create_auth_tables.sql](migrations/001_create_auth_tables.sql)

## 🎉 You're Ready!

Your authentication system is now fully functional with:
- ✅ Secure user registration and login
- ✅ OAuth integration with major providers
- ✅ Role-based access control
- ✅ Session management
- ✅ Password reset functionality
- ✅ Comprehensive security features
- ✅ Production-ready architecture

Start building your application with confidence! 🚀