1054 lines
28 KiB
Markdown
1054 lines
28 KiB
Markdown
# Authentication System Documentation
|
|
|
|
**Version:** 1.0
|
|
**Last Updated:** November 2025
|
|
**Audience:** Development Team & API Consumers
|
|
|
|
---
|
|
|
|
## 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)
|
|
9. [Best Practices](#best-practices)
|
|
|
|
---
|
|
|
|
## System Overview
|
|
|
|
The Wizamart 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
|
|
```
|
|
|
|
**Example Request:**
|
|
```bash
|
|
curl -X POST http://localhost:8000/api/v1/admin/auth/login \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"username":"admin","password":"admin123"}'
|
|
```
|
|
|
|
**Example Response:**
|
|
```json
|
|
{
|
|
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
|
|
"token_type": "Bearer",
|
|
"expires_in": 3600,
|
|
"user": {
|
|
"id": 1,
|
|
"username": "admin",
|
|
"email": "admin@example.com",
|
|
"role": "admin",
|
|
"is_active": true
|
|
}
|
|
}
|
|
```
|
|
|
|
Additionally, sets cookie:
|
|
```
|
|
Set-Cookie: admin_token=<JWT>; Path=/admin; HttpOnly; Secure; SameSite=Lax
|
|
```
|
|
|
|
### 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
|
|
```
|
|
|
|
**Example Request:**
|
|
```bash
|
|
curl -X POST http://localhost:8000/api/v1/vendor/auth/login \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"username":"vendor_owner","password":"vendor123"}'
|
|
```
|
|
|
|
**Example Response:**
|
|
```json
|
|
{
|
|
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
|
|
"token_type": "Bearer",
|
|
"expires_in": 3600,
|
|
"user": {
|
|
"id": 2,
|
|
"username": "vendor_owner",
|
|
"email": "owner@vendorshop.com",
|
|
"role": "vendor",
|
|
"is_active": true
|
|
},
|
|
"vendor": {
|
|
"id": 1,
|
|
"vendor_code": "ACME",
|
|
"name": "ACME Store"
|
|
},
|
|
"vendor_role": "owner"
|
|
}
|
|
```
|
|
|
|
Additionally, sets cookie:
|
|
```
|
|
Set-Cookie: vendor_token=<JWT>; Path=/vendor; HttpOnly; Secure; SameSite=Lax
|
|
```
|
|
|
|
### 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
|
|
```
|
|
|
|
**Example Request:**
|
|
```bash
|
|
curl -X POST http://localhost:8000/api/v1/public/vendors/1/customers/login \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"username":"customer","password":"customer123"}'
|
|
```
|
|
|
|
**Example Response:**
|
|
```json
|
|
{
|
|
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
|
|
"token_type": "Bearer",
|
|
"expires_in": 3600,
|
|
"user": {
|
|
"id": 100,
|
|
"email": "customer@example.com",
|
|
"customer_number": "CUST-001",
|
|
"is_active": true
|
|
}
|
|
}
|
|
```
|
|
|
|
Additionally, sets cookie:
|
|
```
|
|
Set-Cookie: customer_token=<JWT>; Path=/shop; HttpOnly; Secure; SameSite=Lax
|
|
```
|
|
|
|
---
|
|
|
|
## 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:** `Customer` object
|
|
**Raises:**
|
|
- `InvalidTokenException` - No token or invalid token
|
|
- `InsufficientPermissionsException` - User is not customer (admin/vendor blocked)
|
|
|
|
**Usage:**
|
|
```python
|
|
current_customer: Customer = Depends(get_current_customer_from_cookie_or_header)
|
|
```
|
|
|
|
#### `get_current_customer_api()`
|
|
|
|
**Purpose:** Authenticate customer users for API endpoints
|
|
**Accepts:** Authorization header ONLY
|
|
**Returns:** `Customer` object
|
|
**Raises:**
|
|
- `InvalidTokenException` - No token or invalid token
|
|
- `InsufficientPermissionsException` - User is not customer (admin/vendor blocked)
|
|
|
|
**Usage:**
|
|
```python
|
|
current_customer: Customer = 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 Response Format
|
|
|
|
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
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## AuthManager Class Reference
|
|
|
|
The `AuthManager` class handles all authentication and authorization operations including password hashing, JWT token management, and role-based access control.
|
|
|
|
::: middleware.auth.AuthManager
|
|
options:
|
|
show_source: false
|
|
heading_level: 3
|
|
show_root_heading: true
|
|
show_root_toc_entry: false
|
|
members:
|
|
- __init__
|
|
- hash_password
|
|
- verify_password
|
|
- authenticate_user
|
|
- create_access_token
|
|
- verify_token
|
|
- get_current_user
|
|
- require_role
|
|
- require_admin
|
|
- require_vendor
|
|
- require_customer
|
|
- create_default_admin_user
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
For a condensed cheat sheet of authentication patterns, see [Authentication Quick Reference](authentication-quick-reference.md).
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- [RBAC System](RBAC.md) - Role-based access control and permissions
|
|
- [Architecture Overview](../architecture/auth-rbac.md) - System-wide authentication architecture
|
|
- [Backend Development](../backend/overview.md) - Backend development guide
|
|
- [API Reference](../backend/middleware-reference.md) - Auto-generated API documentation
|
|
|
|
---
|
|
|
|
**Document Version:** 1.0
|
|
**Last Updated:** November 2025
|
|
**Maintained By:** Backend Team
|