frontend error management enhancement
This commit is contained in:
285
docs/__REVAMPING/AUTHENTICATION/AUTHENTICATION_FLOW_DIAGRAMS.md
Normal file
285
docs/__REVAMPING/AUTHENTICATION/AUTHENTICATION_FLOW_DIAGRAMS.md
Normal file
@@ -0,0 +1,285 @@
|
||||
# Authentication Flow Diagrams
|
||||
|
||||
## Cookie Isolation Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Browser │
|
||||
│ │
|
||||
│ ┌─────────────────────┐ ┌─────────────────────┐ │
|
||||
│ │ Admin Area │ │ Vendor Area │ │
|
||||
│ │ /admin/* │ │ /vendor/* │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ 🍪 admin_token │ │ 🍪 vendor_token │ │
|
||||
│ │ Path: /admin │ │ Path: /vendor │ │
|
||||
│ └─────────────────────┘ └─────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ├───────────────────────────┤ │
|
||||
│ │ ❌ No Cookie Mixing │ │
|
||||
│ │ │ │
|
||||
└───────────┼───────────────────────────┼──────────────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌───────────────────────┐ ┌───────────────────────┐
|
||||
│ Admin Backend │ │ Vendor Backend │
|
||||
│ /admin/* │ │ /vendor/* │
|
||||
│ │ │ │
|
||||
│ ✅ admin_token │ │ ✅ vendor_token │
|
||||
│ ❌ vendor_token │ │ ❌ admin_token │
|
||||
└───────────────────────┘ └───────────────────────┘
|
||||
```
|
||||
|
||||
## Login Flow - Admin
|
||||
|
||||
```
|
||||
┌──────────┐
|
||||
│ Browser │
|
||||
└──────────┘
|
||||
│
|
||||
│ POST /api/v1/admin/auth/login
|
||||
│ { username, password }
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ Admin Auth Endpoint │
|
||||
│ │
|
||||
│ 1. Validate credentials│
|
||||
│ 2. Check role == admin │
|
||||
│ 3. Generate JWT │
|
||||
└─────────────────────────┘
|
||||
│
|
||||
│ Set-Cookie: admin_token=<JWT>; Path=/admin; HttpOnly; SameSite=Lax
|
||||
│ Response: { access_token, user }
|
||||
▼
|
||||
┌──────────┐
|
||||
│ Browser │──────────────────────────────────────┐
|
||||
│ │ │
|
||||
│ 🍪 admin_token (Path=/admin) │
|
||||
│ 💾 localStorage.access_token │
|
||||
└──────────┘ │
|
||||
│ │
|
||||
├── Navigate to /admin/dashboard ────────────┤
|
||||
│ (Cookie sent automatically) │
|
||||
│ │
|
||||
└── API call to /api/v1/admin/vendors ───────┤
|
||||
(Authorization: Bearer <token>) │
|
||||
│
|
||||
┌──────────────▼──────────────┐
|
||||
│ get_current_admin_user() │
|
||||
│ │
|
||||
│ 1. Check Auth header │
|
||||
│ 2. Check admin_token cookie │
|
||||
│ 3. Validate JWT │
|
||||
│ 4. Verify role == admin │
|
||||
│ ✅ Return User │
|
||||
└──────────────────────────────┘
|
||||
```
|
||||
|
||||
## Login Flow - Vendor
|
||||
|
||||
```
|
||||
┌──────────┐
|
||||
│ Browser │
|
||||
└──────────┘
|
||||
│
|
||||
│ POST /api/v1/vendor/auth/login
|
||||
│ { username, password }
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ Vendor Auth Endpoint │
|
||||
│ │
|
||||
│ 1. Validate credentials│
|
||||
│ 2. Block if admin │──────> ❌ "Admins cannot access vendor portal"
|
||||
│ 3. Check vendor access │
|
||||
│ 4. Generate JWT │
|
||||
└─────────────────────────┘
|
||||
│
|
||||
│ Set-Cookie: vendor_token=<JWT>; Path=/vendor; HttpOnly; SameSite=Lax
|
||||
│ Response: { access_token, user, vendor }
|
||||
▼
|
||||
┌──────────┐
|
||||
│ Browser │──────────────────────────────────────┐
|
||||
│ │ │
|
||||
│ 🍪 vendor_token (Path=/vendor) │
|
||||
│ 💾 localStorage.access_token │
|
||||
└──────────┘ │
|
||||
│ │
|
||||
├── Navigate to /vendor/ACME/dashboard ──────┤
|
||||
│ (Cookie sent automatically) │
|
||||
│ │
|
||||
└── API call to /api/v1/vendor/ACME/products ┤
|
||||
(Authorization: Bearer <token>) │
|
||||
│
|
||||
┌──────────────▼──────────────┐
|
||||
│ get_current_vendor_user() │
|
||||
│ │
|
||||
│ 1. Check Auth header │
|
||||
│ 2. Check vendor_token cookie│
|
||||
│ 3. Validate JWT │
|
||||
│ 4. Block if admin │──> ❌ Error
|
||||
│ 5. Verify vendor access │
|
||||
│ ✅ Return User │
|
||||
└──────────────────────────────┘
|
||||
```
|
||||
|
||||
## Security Boundary Enforcement
|
||||
|
||||
```
|
||||
┌─────────────────────┐
|
||||
│ Request Comes In │
|
||||
└──────────┬──────────┘
|
||||
│
|
||||
┌──────────▼──────────┐
|
||||
│ What's the path? │
|
||||
└──────────┬──────────┘
|
||||
│
|
||||
┌───────────────┼───────────────┐
|
||||
│ │ │
|
||||
Starts with Starts with Starts with
|
||||
/admin/* /vendor/* /api/*
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
|
||||
│ Check for: │ │ Check for: │ │ Check for: │
|
||||
│ - admin_token │ │ - vendor_token │ │ - Authorization │
|
||||
│ cookie │ │ cookie │ │ header │
|
||||
│ - OR Auth header │ │ - OR Auth header │ │ (required) │
|
||||
└────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
|
||||
│ Validate: │ │ Validate: │ │ Validate: │
|
||||
│ - JWT valid │ │ - JWT valid │ │ - JWT valid │
|
||||
│ - User active │ │ - User active │ │ - User active │
|
||||
│ - Role = admin │ │ - Role != admin │ │ - Any role │
|
||||
│ │ │ - Has vendor │ │ (depends on │
|
||||
│ │ │ access │ │ endpoint) │
|
||||
└────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
✅ Allowed ✅ Allowed ✅ Allowed
|
||||
```
|
||||
|
||||
## Cross-Context Prevention
|
||||
|
||||
### ❌ What's Blocked
|
||||
|
||||
```
|
||||
Admin trying to access vendor route:
|
||||
┌──────────────────────────────────────────┐
|
||||
│ User: admin@example.com (role: admin) │
|
||||
│ Token: Valid JWT with admin role │
|
||||
│ Request: GET /vendor/ACME/dashboard │
|
||||
└──────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────┐
|
||||
│ get_current_vendor_ │
|
||||
│ from_cookie_or_header │
|
||||
└───────────┬───────────┘
|
||||
│
|
||||
▼
|
||||
Check: role == "admin"?
|
||||
│
|
||||
▼ Yes
|
||||
❌ InsufficientPermissionsException
|
||||
"Vendor access only - admins cannot use vendor portal"
|
||||
```
|
||||
|
||||
```
|
||||
Vendor trying to access admin route:
|
||||
┌──────────────────────────────────────────┐
|
||||
│ User: vendor@acme.com (role: vendor) │
|
||||
│ Token: Valid JWT with vendor role │
|
||||
│ Request: GET /admin/dashboard │
|
||||
└──────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────┐
|
||||
│ get_current_admin_ │
|
||||
│ from_cookie_or_header │
|
||||
└───────────┬───────────┘
|
||||
│
|
||||
▼
|
||||
Check: role == "admin"?
|
||||
│
|
||||
▼ No
|
||||
❌ AdminRequiredException
|
||||
"Admin privileges required"
|
||||
```
|
||||
|
||||
```
|
||||
Admin cookie sent to vendor route:
|
||||
┌──────────────────────────────────────────┐
|
||||
│ Cookie: admin_token=<JWT> (Path=/admin) │
|
||||
│ Request: GET /vendor/ACME/dashboard │
|
||||
└──────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
Browser checks cookie path
|
||||
│
|
||||
▼
|
||||
Path /vendor does NOT match /admin
|
||||
│
|
||||
▼
|
||||
❌ Cookie NOT sent
|
||||
Request has no authentication
|
||||
│
|
||||
▼
|
||||
❌ InvalidTokenException
|
||||
"Vendor authentication required"
|
||||
```
|
||||
|
||||
## Cookie Lifecycle
|
||||
|
||||
```
|
||||
LOGIN
|
||||
│
|
||||
├── Server generates JWT
|
||||
├── Server sets cookie:
|
||||
│ • Name: admin_token or vendor_token
|
||||
│ • Value: JWT
|
||||
│ • Path: /admin or /vendor
|
||||
│ • HttpOnly: true
|
||||
│ • Secure: true (production)
|
||||
│ • SameSite: Lax
|
||||
│ • Max-Age: matches JWT expiry
|
||||
│
|
||||
└── Server returns JWT in response body
|
||||
└── Client stores in localStorage (optional)
|
||||
|
||||
PAGE NAVIGATION
|
||||
│
|
||||
├── Browser automatically includes cookie
|
||||
│ if path matches
|
||||
│
|
||||
├── Server reads cookie
|
||||
├── Server validates JWT
|
||||
└── Server returns page or 401
|
||||
|
||||
API CALL
|
||||
│
|
||||
├── Client reads token from localStorage
|
||||
├── Client adds Authorization header
|
||||
│ Authorization: Bearer <JWT>
|
||||
│
|
||||
├── Server reads header
|
||||
├── Server validates JWT
|
||||
└── Server returns data or 401
|
||||
|
||||
LOGOUT
|
||||
│
|
||||
├── Client calls logout endpoint
|
||||
├── Server clears cookie:
|
||||
│ response.delete_cookie(name, path)
|
||||
│
|
||||
└── Client clears localStorage
|
||||
localStorage.removeItem('access_token')
|
||||
```
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
1. **Cookie Path Isolation** = No cross-context cookies
|
||||
2. **Role Checking** = Admins blocked from vendor routes
|
||||
3. **Dual Auth Support** = Cookies for pages, headers for API
|
||||
4. **Security First** = HttpOnly, Secure, SameSite protection
|
||||
5. **Clear Boundaries** = Each context is completely isolated
|
||||
@@ -0,0 +1,271 @@
|
||||
# Authentication Quick Reference
|
||||
|
||||
**Version 1.0** | One-page reference for developers
|
||||
|
||||
---
|
||||
|
||||
## Function Cheat Sheet
|
||||
|
||||
### For HTML Pages (accept cookie OR header)
|
||||
|
||||
```python
|
||||
from app.api.deps import (
|
||||
get_current_admin_from_cookie_or_header,
|
||||
get_current_vendor_from_cookie_or_header,
|
||||
get_current_customer_from_cookie_or_header
|
||||
)
|
||||
|
||||
# Admin page
|
||||
@router.get("/admin/dashboard")
|
||||
def admin_page(user: User = Depends(get_current_admin_from_cookie_or_header)):
|
||||
pass
|
||||
|
||||
# Vendor page
|
||||
@router.get("/vendor/{code}/dashboard")
|
||||
def vendor_page(user: User = Depends(get_current_vendor_from_cookie_or_header)):
|
||||
pass
|
||||
|
||||
# Customer page
|
||||
@router.get("/shop/account/dashboard")
|
||||
def customer_page(user: User = Depends(get_current_customer_from_cookie_or_header)):
|
||||
pass
|
||||
```
|
||||
|
||||
### For API Endpoints (header only - better security)
|
||||
|
||||
```python
|
||||
from app.api.deps import (
|
||||
get_current_admin_api,
|
||||
get_current_vendor_api,
|
||||
get_current_customer_api
|
||||
)
|
||||
|
||||
# Admin API
|
||||
@router.post("/api/v1/admin/vendors")
|
||||
def admin_api(user: User = Depends(get_current_admin_api)):
|
||||
pass
|
||||
|
||||
# Vendor API
|
||||
@router.post("/api/v1/vendor/{code}/products")
|
||||
def vendor_api(user: User = Depends(get_current_vendor_api)):
|
||||
pass
|
||||
|
||||
# Customer API
|
||||
@router.post("/api/v1/shop/orders")
|
||||
def customer_api(user: User = Depends(get_current_customer_api)):
|
||||
pass
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Three Authentication Contexts
|
||||
|
||||
| Context | Cookie | Path | Role | Routes |
|
||||
|---------|--------|------|------|--------|
|
||||
| **Admin** | `admin_token` | `/admin` | `admin` | `/admin/*` |
|
||||
| **Vendor** | `vendor_token` | `/vendor` | `vendor` | `/vendor/*` |
|
||||
| **Customer** | `customer_token` | `/shop` | `customer` | `/shop/account/*` |
|
||||
|
||||
---
|
||||
|
||||
## Access Control Matrix
|
||||
|
||||
| User | Admin Portal | Vendor Portal | Shop Catalog | Customer Account |
|
||||
|------|--------------|---------------|--------------|------------------|
|
||||
| Admin | ✅ | ❌ | ✅ (view) | ❌ |
|
||||
| Vendor | ❌ | ✅ | ✅ (view) | ❌ |
|
||||
| Customer | ❌ | ❌ | ✅ (view) | ✅ |
|
||||
| Anonymous | ❌ | ❌ | ✅ (view) | ❌ |
|
||||
|
||||
---
|
||||
|
||||
## Login Endpoints
|
||||
|
||||
```bash
|
||||
# Admin
|
||||
POST /api/v1/admin/auth/login
|
||||
Body: {"username": "...", "password": "..."}
|
||||
|
||||
# Vendor
|
||||
POST /api/v1/vendor/auth/login
|
||||
Body: {"username": "...", "password": "..."}
|
||||
|
||||
# Customer
|
||||
POST /api/v1/public/vendors/{vendor_id}/customers/login
|
||||
Body: {"username": "...", "password": "..."}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJ0eXAi...",
|
||||
"token_type": "Bearer",
|
||||
"expires_in": 3600,
|
||||
"user": {...}
|
||||
}
|
||||
```
|
||||
|
||||
Plus HTTP-only cookie is set automatically.
|
||||
|
||||
---
|
||||
|
||||
## Frontend Patterns
|
||||
|
||||
### Login (Store Token)
|
||||
|
||||
```javascript
|
||||
const response = await fetch('/api/v1/admin/auth/login', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ username, password })
|
||||
});
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
// Cookie set automatically
|
||||
// Optionally store for API calls
|
||||
localStorage.setItem('token', data.access_token);
|
||||
|
||||
// Navigate (cookie automatic)
|
||||
window.location.href = '/admin/dashboard';
|
||||
```
|
||||
|
||||
### API Call (Use Token)
|
||||
|
||||
```javascript
|
||||
const token = localStorage.getItem('token');
|
||||
|
||||
const response = await fetch('/api/v1/admin/vendors', {
|
||||
headers: {
|
||||
'Authorization': `Bearer ${token}`
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Logout
|
||||
|
||||
```javascript
|
||||
await fetch('/api/v1/admin/auth/logout', { method: 'POST' });
|
||||
localStorage.removeItem('token');
|
||||
window.location.href = '/admin/login';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Commands
|
||||
|
||||
### curl Examples
|
||||
|
||||
```bash
|
||||
# Login
|
||||
TOKEN=$(curl -X POST http://localhost:8000/api/v1/admin/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"admin123"}' \
|
||||
| jq -r '.access_token')
|
||||
|
||||
# Authenticated request
|
||||
curl http://localhost:8000/api/v1/admin/vendors \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
### Check Cookie in Browser
|
||||
|
||||
```javascript
|
||||
// In DevTools console
|
||||
document.cookie.split(';').forEach(c => console.log(c.trim()));
|
||||
```
|
||||
|
||||
### Decode JWT
|
||||
|
||||
```javascript
|
||||
function parseJwt(token) {
|
||||
return JSON.parse(atob(token.split('.')[1]));
|
||||
}
|
||||
|
||||
console.log(parseJwt(localStorage.getItem('token')));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Errors
|
||||
|
||||
| Error | Meaning | Solution |
|
||||
|-------|---------|----------|
|
||||
| `INVALID_TOKEN` | No token or invalid | Re-login |
|
||||
| `TOKEN_EXPIRED` | Token expired | Re-login |
|
||||
| `ADMIN_REQUIRED` | Need admin role | Use correct account |
|
||||
| `INSUFFICIENT_PERMISSIONS` | Wrong role for route | Use correct portal |
|
||||
| `USER_NOT_ACTIVE` | Account disabled | Contact admin |
|
||||
|
||||
---
|
||||
|
||||
## Security Rules
|
||||
|
||||
1. ✅ **HTML pages** use `*_from_cookie_or_header` functions
|
||||
2. ✅ **API endpoints** use `*_api` functions
|
||||
3. ✅ **Admins** cannot access vendor/customer portals
|
||||
4. ✅ **Vendors** cannot access admin/customer portals
|
||||
5. ✅ **Customers** cannot access admin/vendor portals
|
||||
6. ✅ **Public shop** (`/shop/products`) needs no auth
|
||||
7. ✅ **Customer accounts** (`/shop/account/*`) need auth
|
||||
|
||||
---
|
||||
|
||||
## Cookie Security
|
||||
|
||||
All cookies have:
|
||||
- ✅ `HttpOnly=true` - JavaScript cannot read (XSS protection)
|
||||
- ✅ `Secure=true` - HTTPS only (production)
|
||||
- ✅ `SameSite=Lax` - CSRF protection
|
||||
- ✅ Path restriction - Context isolation
|
||||
|
||||
---
|
||||
|
||||
## Quick Debug
|
||||
|
||||
1. **Auth not working?**
|
||||
- Check DevTools → Application → Cookies
|
||||
- Verify cookie name and path match route
|
||||
- Check token not expired
|
||||
|
||||
2. **Cross-context access denied?**
|
||||
- This is intentional security
|
||||
- Use correct portal for your role
|
||||
|
||||
3. **API call fails but page loads?**
|
||||
- API needs `Authorization` header
|
||||
- Page uses cookie (automatic)
|
||||
- Add header to API calls
|
||||
|
||||
---
|
||||
|
||||
## File Locations
|
||||
|
||||
```
|
||||
app/api/
|
||||
├── deps.py # All auth functions here
|
||||
├── v1/
|
||||
├── admin/auth.py # Admin login
|
||||
├── vendor/auth.py # Vendor login
|
||||
└── public/vendors/auth.py # Customer login
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```bash
|
||||
JWT_SECRET_KEY=your-secret-key
|
||||
JWT_ALGORITHM=HS256
|
||||
JWT_EXPIRATION=3600 # 1 hour
|
||||
ENVIRONMENT=production
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Full Documentation:** See `AUTHENTICATION_SYSTEM_DOCS.md`
|
||||
**Questions?** Contact backend team
|
||||
|
||||
---
|
||||
|
||||
**Print this page for quick reference!**
|
||||
943
docs/__REVAMPING/AUTHENTICATION/AUTHENTICATION_SYSTEM_DOCS.md
Normal file
943
docs/__REVAMPING/AUTHENTICATION/AUTHENTICATION_SYSTEM_DOCS.md
Normal file
@@ -0,0 +1,943 @@
|
||||
# Authentication System Documentation
|
||||
|
||||
**Version:** 1.0
|
||||
**Last Updated:** November 2024
|
||||
**Audience:** Development Team
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [System Overview](#system-overview)
|
||||
2. [Architecture](#architecture)
|
||||
3. [Authentication Contexts](#authentication-contexts)
|
||||
4. [Implementation Guide](#implementation-guide)
|
||||
5. [API Reference](#api-reference)
|
||||
6. [Security Model](#security-model)
|
||||
7. [Testing Guidelines](#testing-guidelines)
|
||||
8. [Troubleshooting](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## System Overview
|
||||
|
||||
The LetzShop platform uses a **context-based authentication system** with three isolated security domains:
|
||||
|
||||
- **Admin Portal** - Platform administration and management
|
||||
- **Vendor Portal** - Multi-tenant shop management
|
||||
- **Customer Shop** - Public storefront and customer accounts
|
||||
|
||||
Each context uses **dual authentication** supporting both cookie-based (for HTML pages) and header-based (for API calls) authentication with complete isolation between contexts.
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Cookie Path Isolation** - Separate cookies per context prevent cross-context access
|
||||
- **Role-Based Access Control** - Strict enforcement of user roles
|
||||
- **JWT Token Authentication** - Stateless, secure token-based auth
|
||||
- **HTTP-Only Cookies** - XSS protection for browser sessions
|
||||
- **CSRF Protection** - SameSite cookie attribute
|
||||
- **Comprehensive Logging** - Full audit trail of authentication events
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Client Request │
|
||||
└─────────────────┬───────────────────────────────────┘
|
||||
│
|
||||
┌───────▼────────┐
|
||||
│ Route Handler │
|
||||
└───────┬────────┘
|
||||
│
|
||||
┌───────▼────────────────────────────────┐
|
||||
│ Authentication Dependency │
|
||||
│ (from app/api/deps.py) │
|
||||
└───────┬────────────────────────────────┘
|
||||
│
|
||||
┌─────────────┼─────────────┐
|
||||
│ │ │
|
||||
┌───▼───┐ ┌────▼────┐ ┌───▼────┐
|
||||
│Cookie │ │ Header │ │ None │
|
||||
└───┬───┘ └────┬────┘ └───┬────┘
|
||||
│ │ │
|
||||
└────────┬───┴────────────┘
|
||||
│
|
||||
┌──────▼───────┐
|
||||
│ Validate JWT │
|
||||
└──────┬───────┘
|
||||
│
|
||||
┌──────▼──────────┐
|
||||
│ Check User Role │
|
||||
└──────┬──────────┘
|
||||
│
|
||||
┌────────┴─────────┐
|
||||
│ │
|
||||
┌───▼────┐ ┌─────▼──────┐
|
||||
│Success │ │ Auth Error │
|
||||
│Return │ │ 401/403 │
|
||||
│User │ └────────────┘
|
||||
└────────┘
|
||||
```
|
||||
|
||||
### Cookie Isolation
|
||||
|
||||
Each authentication context uses a separate cookie with path restrictions:
|
||||
|
||||
| Context | Cookie Name | Cookie Path | Access Scope |
|
||||
|----------|------------------|-------------|--------------|
|
||||
| Admin | `admin_token` | `/admin` | Admin routes only |
|
||||
| Vendor | `vendor_token` | `/vendor` | Vendor routes only |
|
||||
| Customer | `customer_token` | `/shop` | Shop routes only |
|
||||
|
||||
**Browser Behavior:**
|
||||
- When requesting `/admin/*`, browser sends `admin_token` cookie only
|
||||
- When requesting `/vendor/*`, browser sends `vendor_token` cookie only
|
||||
- When requesting `/shop/*`, browser sends `customer_token` cookie only
|
||||
|
||||
This prevents cookie leakage between contexts.
|
||||
|
||||
---
|
||||
|
||||
## Authentication Contexts
|
||||
|
||||
### 1. Admin Context
|
||||
|
||||
**Routes:** `/admin/*`
|
||||
**Role:** `admin`
|
||||
**Cookie:** `admin_token` (path=/admin)
|
||||
|
||||
**Purpose:** Platform administration, vendor management, system configuration.
|
||||
|
||||
**Access Control:**
|
||||
- ✅ Admin users only
|
||||
- ❌ Vendor users blocked
|
||||
- ❌ Customer users blocked
|
||||
|
||||
**Login Endpoint:**
|
||||
```
|
||||
POST /api/v1/admin/auth/login
|
||||
```
|
||||
|
||||
### 2. Vendor Context
|
||||
|
||||
**Routes:** `/vendor/*`
|
||||
**Role:** `vendor`
|
||||
**Cookie:** `vendor_token` (path=/vendor)
|
||||
|
||||
**Purpose:** Vendor shop management, product catalog, orders, team management.
|
||||
|
||||
**Access Control:**
|
||||
- ❌ Admin users blocked (admins use admin portal for vendor management)
|
||||
- ✅ Vendor users (owners and team members)
|
||||
- ❌ Customer users blocked
|
||||
|
||||
**Login Endpoint:**
|
||||
```
|
||||
POST /api/v1/vendor/auth/login
|
||||
```
|
||||
|
||||
### 3. Customer Context
|
||||
|
||||
**Routes:** `/shop/account/*` (authenticated), `/shop/*` (public)
|
||||
**Role:** `customer`
|
||||
**Cookie:** `customer_token` (path=/shop)
|
||||
|
||||
**Purpose:** Product browsing (public), customer accounts, orders, profile management.
|
||||
|
||||
**Access Control:**
|
||||
- **Public Routes** (`/shop/products`, `/shop/cart`, etc.):
|
||||
- ✅ Anyone can access (no authentication)
|
||||
- **Account Routes** (`/shop/account/*`):
|
||||
- ❌ Admin users blocked
|
||||
- ❌ Vendor users blocked
|
||||
- ✅ Customer users only
|
||||
|
||||
**Login Endpoint:**
|
||||
```
|
||||
POST /api/v1/public/vendors/{vendor_id}/customers/login
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Guide
|
||||
|
||||
### Module Structure
|
||||
|
||||
```
|
||||
app/api/
|
||||
├── deps.py # Authentication dependencies
|
||||
├── v1/
|
||||
├── admin/
|
||||
│ └── auth.py # Admin authentication endpoints
|
||||
├── vendor/
|
||||
│ └── auth.py # Vendor authentication endpoints
|
||||
└── public/vendors/
|
||||
└── auth.py # Customer authentication endpoints
|
||||
```
|
||||
|
||||
### For HTML Pages (Server-Rendered)
|
||||
|
||||
Use the `*_from_cookie_or_header` functions for pages that users navigate to:
|
||||
|
||||
```python
|
||||
from fastapi import APIRouter, Request, Depends
|
||||
from fastapi.responses import HTMLResponse
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.api.deps import (
|
||||
get_current_admin_from_cookie_or_header,
|
||||
get_current_vendor_from_cookie_or_header,
|
||||
get_current_customer_from_cookie_or_header,
|
||||
get_db
|
||||
)
|
||||
from models.database.user import User
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
# Admin page
|
||||
@router.get("/admin/dashboard", response_class=HTMLResponse)
|
||||
async def admin_dashboard(
|
||||
request: Request,
|
||||
current_user: User = Depends(get_current_admin_from_cookie_or_header),
|
||||
db: Session = Depends(get_db)
|
||||
):
|
||||
return templates.TemplateResponse("admin/dashboard.html", {
|
||||
"request": request,
|
||||
"user": current_user
|
||||
})
|
||||
|
||||
# Vendor page
|
||||
@router.get("/vendor/{vendor_code}/dashboard", response_class=HTMLResponse)
|
||||
async def vendor_dashboard(
|
||||
request: Request,
|
||||
vendor_code: str,
|
||||
current_user: User = Depends(get_current_vendor_from_cookie_or_header),
|
||||
db: Session = Depends(get_db)
|
||||
):
|
||||
return templates.TemplateResponse("vendor/dashboard.html", {
|
||||
"request": request,
|
||||
"user": current_user,
|
||||
"vendor_code": vendor_code
|
||||
})
|
||||
|
||||
# Customer account page
|
||||
@router.get("/shop/account/dashboard", response_class=HTMLResponse)
|
||||
async def customer_dashboard(
|
||||
request: Request,
|
||||
current_user: User = Depends(get_current_customer_from_cookie_or_header),
|
||||
db: Session = Depends(get_db)
|
||||
):
|
||||
return templates.TemplateResponse("shop/account/dashboard.html", {
|
||||
"request": request,
|
||||
"user": current_user
|
||||
})
|
||||
```
|
||||
|
||||
### For API Endpoints (JSON Responses)
|
||||
|
||||
Use the `*_api` functions for API endpoints to enforce header-based authentication:
|
||||
|
||||
```python
|
||||
from fastapi import APIRouter, Depends
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.api.deps import (
|
||||
get_current_admin_api,
|
||||
get_current_vendor_api,
|
||||
get_current_customer_api,
|
||||
get_db
|
||||
)
|
||||
from models.database.user import User
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
# Admin API
|
||||
@router.post("/api/v1/admin/vendors")
|
||||
def create_vendor(
|
||||
vendor_data: VendorCreate,
|
||||
current_user: User = Depends(get_current_admin_api),
|
||||
db: Session = Depends(get_db)
|
||||
):
|
||||
# Only accepts Authorization header (no cookies)
|
||||
# Better security - prevents CSRF attacks
|
||||
return {"message": "Vendor created"}
|
||||
|
||||
# Vendor API
|
||||
@router.post("/api/v1/vendor/{vendor_code}/products")
|
||||
def create_product(
|
||||
vendor_code: str,
|
||||
product_data: ProductCreate,
|
||||
current_user: User = Depends(get_current_vendor_api),
|
||||
db: Session = Depends(get_db)
|
||||
):
|
||||
return {"message": "Product created"}
|
||||
|
||||
# Customer API
|
||||
@router.post("/api/v1/shop/orders")
|
||||
def create_order(
|
||||
order_data: OrderCreate,
|
||||
current_user: User = Depends(get_current_customer_api),
|
||||
db: Session = Depends(get_db)
|
||||
):
|
||||
return {"message": "Order created"}
|
||||
```
|
||||
|
||||
### For Public Routes (No Authentication)
|
||||
|
||||
Simply don't use any authentication dependency:
|
||||
|
||||
```python
|
||||
@router.get("/shop/products")
|
||||
async def public_products(request: Request):
|
||||
# No authentication required
|
||||
return templates.TemplateResponse("shop/products.html", {
|
||||
"request": request
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Reference
|
||||
|
||||
### Authentication Dependencies
|
||||
|
||||
All authentication functions are in `app/api/deps.py`:
|
||||
|
||||
#### `get_current_admin_from_cookie_or_header()`
|
||||
|
||||
**Purpose:** Authenticate admin users for HTML pages
|
||||
**Accepts:** Cookie (`admin_token`) OR Authorization header
|
||||
**Returns:** `User` object with `role="admin"`
|
||||
**Raises:**
|
||||
- `InvalidTokenException` - No token or invalid token
|
||||
- `AdminRequiredException` - User is not admin
|
||||
|
||||
**Usage:**
|
||||
```python
|
||||
current_user: User = Depends(get_current_admin_from_cookie_or_header)
|
||||
```
|
||||
|
||||
#### `get_current_admin_api()`
|
||||
|
||||
**Purpose:** Authenticate admin users for API endpoints
|
||||
**Accepts:** Authorization header ONLY
|
||||
**Returns:** `User` object with `role="admin"`
|
||||
**Raises:**
|
||||
- `InvalidTokenException` - No token or invalid token
|
||||
- `AdminRequiredException` - User is not admin
|
||||
|
||||
**Usage:**
|
||||
```python
|
||||
current_user: User = Depends(get_current_admin_api)
|
||||
```
|
||||
|
||||
#### `get_current_vendor_from_cookie_or_header()`
|
||||
|
||||
**Purpose:** Authenticate vendor users for HTML pages
|
||||
**Accepts:** Cookie (`vendor_token`) OR Authorization header
|
||||
**Returns:** `User` object with `role="vendor"`
|
||||
**Raises:**
|
||||
- `InvalidTokenException` - No token or invalid token
|
||||
- `InsufficientPermissionsException` - User is not vendor or is admin
|
||||
|
||||
**Usage:**
|
||||
```python
|
||||
current_user: User = Depends(get_current_vendor_from_cookie_or_header)
|
||||
```
|
||||
|
||||
#### `get_current_vendor_api()`
|
||||
|
||||
**Purpose:** Authenticate vendor users for API endpoints
|
||||
**Accepts:** Authorization header ONLY
|
||||
**Returns:** `User` object with `role="vendor"`
|
||||
**Raises:**
|
||||
- `InvalidTokenException` - No token or invalid token
|
||||
- `InsufficientPermissionsException` - User is not vendor or is admin
|
||||
|
||||
**Usage:**
|
||||
```python
|
||||
current_user: User = Depends(get_current_vendor_api)
|
||||
```
|
||||
|
||||
#### `get_current_customer_from_cookie_or_header()`
|
||||
|
||||
**Purpose:** Authenticate customer users for HTML pages
|
||||
**Accepts:** Cookie (`customer_token`) OR Authorization header
|
||||
**Returns:** `User` object with `role="customer"`
|
||||
**Raises:**
|
||||
- `InvalidTokenException` - No token or invalid token
|
||||
- `InsufficientPermissionsException` - User is not customer (admin/vendor blocked)
|
||||
|
||||
**Usage:**
|
||||
```python
|
||||
current_user: User = Depends(get_current_customer_from_cookie_or_header)
|
||||
```
|
||||
|
||||
#### `get_current_customer_api()`
|
||||
|
||||
**Purpose:** Authenticate customer users for API endpoints
|
||||
**Accepts:** Authorization header ONLY
|
||||
**Returns:** `User` object with `role="customer"`
|
||||
**Raises:**
|
||||
- `InvalidTokenException` - No token or invalid token
|
||||
- `InsufficientPermissionsException` - User is not customer (admin/vendor blocked)
|
||||
|
||||
**Usage:**
|
||||
```python
|
||||
current_user: User = Depends(get_current_customer_api)
|
||||
```
|
||||
|
||||
#### `get_current_user()`
|
||||
|
||||
**Purpose:** Authenticate any user (no role checking)
|
||||
**Accepts:** Authorization header ONLY
|
||||
**Returns:** `User` object (any role)
|
||||
**Raises:**
|
||||
- `InvalidTokenException` - No token or invalid token
|
||||
|
||||
**Usage:**
|
||||
```python
|
||||
current_user: User = Depends(get_current_user)
|
||||
```
|
||||
|
||||
### Login Responses
|
||||
|
||||
All login endpoints return:
|
||||
|
||||
```python
|
||||
{
|
||||
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
|
||||
"token_type": "Bearer",
|
||||
"expires_in": 3600,
|
||||
"user": {
|
||||
"id": 1,
|
||||
"username": "admin",
|
||||
"email": "admin@example.com",
|
||||
"role": "admin",
|
||||
"is_active": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Additionally, the response sets an HTTP-only cookie:
|
||||
- Admin: `admin_token` (path=/admin)
|
||||
- Vendor: `vendor_token` (path=/vendor)
|
||||
- Customer: `customer_token` (path=/shop)
|
||||
|
||||
---
|
||||
|
||||
## Security Model
|
||||
|
||||
### Role-Based Access Control Matrix
|
||||
|
||||
| User Role | Admin Portal | Vendor Portal | Shop Catalog | Customer Account |
|
||||
|-----------|--------------|---------------|--------------|------------------|
|
||||
| Admin | ✅ Full | ❌ Blocked | ✅ View | ❌ Blocked |
|
||||
| Vendor | ❌ Blocked | ✅ Full | ✅ View | ❌ Blocked |
|
||||
| Customer | ❌ Blocked | ❌ Blocked | ✅ View | ✅ Full |
|
||||
| Anonymous | ❌ Blocked | ❌ Blocked | ✅ View | ❌ Blocked |
|
||||
|
||||
### Cookie Security Settings
|
||||
|
||||
All authentication cookies use the following security attributes:
|
||||
|
||||
```python
|
||||
response.set_cookie(
|
||||
key="<context>_token",
|
||||
value=jwt_token,
|
||||
httponly=True, # JavaScript cannot access (XSS protection)
|
||||
secure=True, # HTTPS only in production
|
||||
samesite="lax", # CSRF protection
|
||||
max_age=3600, # Matches JWT expiry
|
||||
path="/<context>" # Path restriction for isolation
|
||||
)
|
||||
```
|
||||
|
||||
### Token Validation
|
||||
|
||||
JWT tokens include:
|
||||
- `sub` - User ID
|
||||
- `role` - User role (admin/vendor/customer)
|
||||
- `exp` - Expiration timestamp
|
||||
- `iat` - Issued at timestamp
|
||||
|
||||
Tokens are validated on every request:
|
||||
1. Extract token from cookie or header
|
||||
2. Verify JWT signature
|
||||
3. Check expiration
|
||||
4. Load user from database
|
||||
5. Verify user is active
|
||||
6. Check role matches route requirements
|
||||
|
||||
### HTTPS Requirement
|
||||
|
||||
**Production Environment:**
|
||||
- All cookies have `secure=True`
|
||||
- HTTPS required for all authenticated routes
|
||||
- HTTP requests automatically redirect to HTTPS
|
||||
|
||||
**Development Environment:**
|
||||
- Cookies have `secure=False` for local testing
|
||||
- HTTP allowed (http://localhost:8000)
|
||||
|
||||
---
|
||||
|
||||
## Testing Guidelines
|
||||
|
||||
### Manual Testing with Browser
|
||||
|
||||
#### Test Admin Authentication
|
||||
|
||||
1. **Navigate to admin login:**
|
||||
```
|
||||
http://localhost:8000/admin/login
|
||||
```
|
||||
|
||||
2. **Login with admin credentials:**
|
||||
- Username: `admin`
|
||||
- Password: `admin123` (or your configured admin password)
|
||||
|
||||
3. **Verify cookie in DevTools:**
|
||||
- Open DevTools → Application → Cookies
|
||||
- Look for `admin_token` cookie
|
||||
- Verify `Path` is `/admin`
|
||||
- Verify `HttpOnly` is checked
|
||||
- Verify `SameSite` is `Lax`
|
||||
|
||||
4. **Test navigation:**
|
||||
- Navigate to `/admin/dashboard` - Should work ✅
|
||||
- Navigate to `/vendor/TESTVENDOR/dashboard` - Should fail (cookie not sent) ❌
|
||||
- Navigate to `/shop/account/dashboard` - Should fail (cookie not sent) ❌
|
||||
|
||||
5. **Logout:**
|
||||
```
|
||||
POST /api/v1/admin/auth/logout
|
||||
```
|
||||
|
||||
#### Test Vendor Authentication
|
||||
|
||||
1. **Navigate to vendor login:**
|
||||
```
|
||||
http://localhost:8000/vendor/{VENDOR_CODE}/login
|
||||
```
|
||||
|
||||
2. **Login with vendor credentials**
|
||||
|
||||
3. **Verify cookie in DevTools:**
|
||||
- Look for `vendor_token` cookie
|
||||
- Verify `Path` is `/vendor`
|
||||
|
||||
4. **Test navigation:**
|
||||
- Navigate to `/vendor/{VENDOR_CODE}/dashboard` - Should work ✅
|
||||
- Navigate to `/admin/dashboard` - Should fail ❌
|
||||
- Navigate to `/shop/account/dashboard` - Should fail ❌
|
||||
|
||||
#### Test Customer Authentication
|
||||
|
||||
1. **Navigate to customer login:**
|
||||
```
|
||||
http://localhost:8000/shop/account/login
|
||||
```
|
||||
|
||||
2. **Login with customer credentials**
|
||||
|
||||
3. **Verify cookie in DevTools:**
|
||||
- Look for `customer_token` cookie
|
||||
- Verify `Path` is `/shop`
|
||||
|
||||
4. **Test navigation:**
|
||||
- Navigate to `/shop/account/dashboard` - Should work ✅
|
||||
- Navigate to `/admin/dashboard` - Should fail ❌
|
||||
- Navigate to `/vendor/{CODE}/dashboard` - Should fail ❌
|
||||
|
||||
### API Testing with curl
|
||||
|
||||
#### Test Admin API
|
||||
|
||||
```bash
|
||||
# Login
|
||||
curl -X POST http://localhost:8000/api/v1/admin/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"admin123"}'
|
||||
|
||||
# Save the access_token from response
|
||||
|
||||
# Test authenticated endpoint
|
||||
curl http://localhost:8000/api/v1/admin/vendors \
|
||||
-H "Authorization: Bearer <access_token>"
|
||||
|
||||
# Test cross-context blocking
|
||||
curl http://localhost:8000/api/v1/vendor/TESTVENDOR/products \
|
||||
-H "Authorization: Bearer <admin_access_token>"
|
||||
# Should return 403 Forbidden
|
||||
```
|
||||
|
||||
#### Test Vendor API
|
||||
|
||||
```bash
|
||||
# Login
|
||||
curl -X POST http://localhost:8000/api/v1/vendor/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"vendor","password":"vendor123"}'
|
||||
|
||||
# Test authenticated endpoint
|
||||
curl http://localhost:8000/api/v1/vendor/TESTVENDOR/products \
|
||||
-H "Authorization: Bearer <vendor_access_token>"
|
||||
|
||||
# Test cross-context blocking
|
||||
curl http://localhost:8000/api/v1/admin/vendors \
|
||||
-H "Authorization: Bearer <vendor_access_token>"
|
||||
# Should return 403 Forbidden
|
||||
```
|
||||
|
||||
#### Test Customer API
|
||||
|
||||
```bash
|
||||
# Login
|
||||
curl -X POST http://localhost:8000/api/v1/public/vendors/1/customers/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"customer","password":"customer123"}'
|
||||
|
||||
# Test authenticated endpoint with token
|
||||
curl http://localhost:8000/api/v1/shop/orders \
|
||||
-H "Authorization: Bearer <customer_access_token>"
|
||||
|
||||
# Test cross-context blocking
|
||||
curl http://localhost:8000/api/v1/admin/vendors \
|
||||
-H "Authorization: Bearer <customer_access_token>"
|
||||
# Should return 403 Forbidden
|
||||
```
|
||||
|
||||
### Frontend JavaScript Testing
|
||||
|
||||
#### Login and Store Token
|
||||
|
||||
```javascript
|
||||
// Admin login
|
||||
async function loginAdmin(username, password) {
|
||||
const response = await fetch('/api/v1/admin/auth/login', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ username, password })
|
||||
});
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
// Cookie is set automatically
|
||||
// Optionally store token for API calls
|
||||
localStorage.setItem('admin_token', data.access_token);
|
||||
|
||||
// Redirect to dashboard
|
||||
window.location.href = '/admin/dashboard';
|
||||
}
|
||||
```
|
||||
|
||||
#### Make API Call with Token
|
||||
|
||||
```javascript
|
||||
// API call with token
|
||||
async function fetchVendors() {
|
||||
const token = localStorage.getItem('admin_token');
|
||||
|
||||
const response = await fetch('/api/v1/admin/vendors', {
|
||||
headers: {
|
||||
'Authorization': `Bearer ${token}`
|
||||
}
|
||||
});
|
||||
|
||||
return response.json();
|
||||
}
|
||||
```
|
||||
|
||||
#### Page Navigation (Cookie Automatic)
|
||||
|
||||
```javascript
|
||||
// Just navigate - cookie sent automatically
|
||||
window.location.href = '/admin/dashboard';
|
||||
// Browser automatically includes admin_token cookie
|
||||
```
|
||||
|
||||
### Automated Testing
|
||||
|
||||
#### Test Cookie Isolation
|
||||
|
||||
```python
|
||||
import pytest
|
||||
from fastapi.testclient import TestClient
|
||||
|
||||
def test_admin_cookie_not_sent_to_vendor_routes(client: TestClient):
|
||||
# Login as admin
|
||||
response = client.post('/api/v1/admin/auth/login', json={
|
||||
'username': 'admin',
|
||||
'password': 'admin123'
|
||||
})
|
||||
|
||||
# Try to access vendor route (cookie should not be sent)
|
||||
response = client.get('/vendor/TESTVENDOR/dashboard')
|
||||
|
||||
# Should redirect to login or return 401
|
||||
assert response.status_code in [302, 401]
|
||||
|
||||
def test_vendor_token_blocked_from_admin_api(client: TestClient):
|
||||
# Login as vendor
|
||||
response = client.post('/api/v1/vendor/auth/login', json={
|
||||
'username': 'vendor',
|
||||
'password': 'vendor123'
|
||||
})
|
||||
vendor_token = response.json()['access_token']
|
||||
|
||||
# Try to access admin API with vendor token
|
||||
response = client.get(
|
||||
'/api/v1/admin/vendors',
|
||||
headers={'Authorization': f'Bearer {vendor_token}'}
|
||||
)
|
||||
|
||||
# Should return 403 Forbidden
|
||||
assert response.status_code == 403
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### "Invalid token" error when navigating to pages
|
||||
|
||||
**Symptom:** User is logged in but gets "Invalid token" error
|
||||
|
||||
**Causes:**
|
||||
- Token expired (default: 1 hour)
|
||||
- Cookie was deleted
|
||||
- Wrong cookie being sent
|
||||
|
||||
**Solution:**
|
||||
- Check cookie expiration in DevTools
|
||||
- Re-login to get fresh token
|
||||
- Verify correct cookie exists with correct path
|
||||
|
||||
#### Cookie not being sent to endpoints
|
||||
|
||||
**Symptom:** API calls work with Authorization header but pages don't load
|
||||
|
||||
**Causes:**
|
||||
- Cookie path mismatch
|
||||
- Cookie expired
|
||||
- Wrong domain
|
||||
|
||||
**Solution:**
|
||||
- Verify cookie path matches route (e.g., `/admin` cookie for `/admin/*` routes)
|
||||
- Check cookie expiration
|
||||
- Ensure cookie domain matches current domain
|
||||
|
||||
#### "Admin cannot access vendor portal" error
|
||||
|
||||
**Symptom:** Admin user cannot access vendor routes
|
||||
|
||||
**Explanation:** This is intentional security design. Admins have their own portal at `/admin`. To manage vendors, use admin routes:
|
||||
- View vendors: `/admin/vendors`
|
||||
- Edit vendor: `/admin/vendors/{code}/edit`
|
||||
|
||||
Admins should not log into vendor portal as this violates security boundaries.
|
||||
|
||||
#### "Customer cannot access admin/vendor routes" error
|
||||
|
||||
**Symptom:** Customer trying to access management interfaces
|
||||
|
||||
**Explanation:** Customers only have access to:
|
||||
- Public shop routes: `/shop/products`, etc.
|
||||
- Their account: `/shop/account/*`
|
||||
|
||||
Admin and vendor portals are not accessible to customers.
|
||||
|
||||
#### Token works in Postman but not in browser
|
||||
|
||||
**Cause:** Postman uses Authorization header, browser uses cookies
|
||||
|
||||
**Solution:**
|
||||
- For API testing: Use Authorization header
|
||||
- For browser testing: Rely on cookies (automatic)
|
||||
- For JavaScript API calls: Add Authorization header manually
|
||||
|
||||
### Debugging Tips
|
||||
|
||||
#### Check Cookie in Browser
|
||||
|
||||
```javascript
|
||||
// In browser console
|
||||
document.cookie.split(';').forEach(c => console.log(c.trim()));
|
||||
```
|
||||
|
||||
#### Decode JWT Token
|
||||
|
||||
```javascript
|
||||
// In browser console
|
||||
function parseJwt(token) {
|
||||
const base64Url = token.split('.')[1];
|
||||
const base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/');
|
||||
const jsonPayload = decodeURIComponent(atob(base64).split('').map(c => {
|
||||
return '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2);
|
||||
}).join(''));
|
||||
return JSON.parse(jsonPayload);
|
||||
}
|
||||
|
||||
const token = localStorage.getItem('admin_token');
|
||||
console.log(parseJwt(token));
|
||||
```
|
||||
|
||||
#### Check Server Logs
|
||||
|
||||
The authentication system logs all auth events:
|
||||
|
||||
```
|
||||
INFO: Admin login successful: admin
|
||||
INFO: Request: GET /admin/dashboard from 127.0.0.1
|
||||
INFO: Response: 200 for GET /admin/dashboard (0.045s)
|
||||
```
|
||||
|
||||
Look for:
|
||||
- Login attempts
|
||||
- Token validation errors
|
||||
- Permission denials
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### For Developers
|
||||
|
||||
1. **Use the right dependency for the job:**
|
||||
- HTML pages → `get_current_<context>_from_cookie_or_header`
|
||||
- API endpoints → `get_current_<context>_api`
|
||||
|
||||
2. **Don't mix authentication contexts:**
|
||||
- Admin users should use admin portal
|
||||
- Vendor users should use vendor portal
|
||||
- Customers should use shop
|
||||
|
||||
3. **Always check user.is_active:**
|
||||
```python
|
||||
if not current_user.is_active:
|
||||
raise UserNotActiveException()
|
||||
```
|
||||
|
||||
4. **Use type hints:**
|
||||
```python
|
||||
def my_route(current_user: User = Depends(get_current_admin_api)):
|
||||
# IDE will have autocomplete for current_user
|
||||
```
|
||||
|
||||
5. **Handle exceptions properly:**
|
||||
```python
|
||||
try:
|
||||
# Your logic
|
||||
except InvalidTokenException:
|
||||
# Handle auth failure
|
||||
except InsufficientPermissionsException:
|
||||
# Handle permission denial
|
||||
```
|
||||
|
||||
### For Frontend
|
||||
|
||||
1. **Store tokens securely:**
|
||||
- Tokens in localStorage/sessionStorage are vulnerable to XSS
|
||||
- Prefer using cookies for page navigation
|
||||
- Only use localStorage for explicit API calls
|
||||
|
||||
2. **Always send Authorization header for API calls:**
|
||||
```javascript
|
||||
const token = localStorage.getItem('token');
|
||||
fetch('/api/v1/admin/vendors', {
|
||||
headers: { 'Authorization': `Bearer ${token}` }
|
||||
});
|
||||
```
|
||||
|
||||
3. **Handle 401/403 responses:**
|
||||
```javascript
|
||||
if (response.status === 401) {
|
||||
// Redirect to login
|
||||
window.location.href = '/admin/login';
|
||||
}
|
||||
```
|
||||
|
||||
4. **Clear tokens on logout:**
|
||||
```javascript
|
||||
localStorage.removeItem('token');
|
||||
// Logout endpoint will clear cookie
|
||||
await fetch('/api/v1/admin/auth/logout', { method: 'POST' });
|
||||
```
|
||||
|
||||
### Security Considerations
|
||||
|
||||
1. **Never log tokens** - They're sensitive credentials
|
||||
2. **Use HTTPS in production** - Required for secure cookies
|
||||
3. **Set appropriate token expiration** - Balance security vs UX
|
||||
4. **Rotate secrets regularly** - JWT signing keys
|
||||
5. **Monitor failed auth attempts** - Detect brute force attacks
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# JWT Configuration
|
||||
JWT_SECRET_KEY=your-secret-key-here
|
||||
JWT_ALGORITHM=HS256
|
||||
JWT_EXPIRATION=3600 # 1 hour in seconds
|
||||
|
||||
# Environment
|
||||
ENVIRONMENT=production # or development
|
||||
|
||||
# When ENVIRONMENT=production:
|
||||
# - Cookies use secure=True (HTTPS only)
|
||||
# - Debug mode is disabled
|
||||
# - CORS is stricter
|
||||
```
|
||||
|
||||
### Cookie Expiration
|
||||
|
||||
Cookies expire when:
|
||||
1. JWT token expires (default: 1 hour)
|
||||
2. User logs out (cookie deleted)
|
||||
3. Browser session ends (for session cookies)
|
||||
|
||||
To change expiration:
|
||||
```python
|
||||
# In auth endpoint
|
||||
response.set_cookie(
|
||||
max_age=7200 # 2 hours
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For questions or issues:
|
||||
|
||||
1. Check this documentation first
|
||||
2. Review server logs for error messages
|
||||
3. Test with curl to isolate frontend issues
|
||||
4. Check browser DevTools for cookie issues
|
||||
5. Contact the backend team
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
### Version 1.0 (November 2024)
|
||||
- Initial authentication system implementation
|
||||
- Three-context isolation (admin, vendor, customer)
|
||||
- Dual authentication support (cookie + header)
|
||||
- Complete role-based access control
|
||||
- Comprehensive logging
|
||||
|
||||
---
|
||||
|
||||
**End of Documentation**
|
||||
Reference in New Issue
Block a user