frontend error management enhancement
This commit is contained in:
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