sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add authentication dependencies guide

Browse Source 
Add comprehensive guide explaining when to use each authentication
dependency:

- get_current_admin_from_cookie_or_header vs get_current_admin_api
- get_current_vendor_from_cookie_or_header vs get_current_vendor_api
- get_current_customer_from_cookie_or_header vs get_current_customer_api

Key distinctions:
- HTML pages (templates) → use _from_cookie_or_header (accepts cookies)
- API endpoints (JSON) → use _api (header-only, no cookies, CSRF-safe)
- Login pages → use _optional (returns None instead of exception)

Includes:
- Complete reference table
- When to use which dependency
- Migration guide from old names
- Code examples for each scenario
- Quick reference cheat sheet

This clarifies the naming change from get_current_admin_user to the
more specific variants and helps developers choose the right dependency.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Samir Boulahtit
2025-11-22 16:03:03 +01:00
parent c1ff0a00db
commit ac1017928c
2 changed files with 192 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

191
docs/development/AUTH_DEPENDENCIES_GUIDE.md Normal file
View File

@@ -0,0 +1,191 @@
# Authentication Dependencies Guide
## Overview
FastAPI routes use different authentication dependencies based on whether they serve **HTML pages** or **API endpoints**.
## Available Dependencies
### Admin Authentication
| Dependency | Use Case | Accepts | Description |
|------------|----------|---------|-------------|
| `get_current_admin_from_cookie_or_header` | HTML pages | Cookie OR Header | For admin HTML routes like `/admin/dashboard` |
| `get_current_admin_api` | API endpoints | Header ONLY | For admin API routes like `/api/v1/admin/vendors` |
| `get_current_admin_optional` | Login pages | Cookie OR Header | Returns `None` instead of raising exception |
### Vendor Authentication
| Dependency | Use Case | Accepts | Description |
|------------|----------|---------|-------------|
| `get_current_vendor_from_cookie_or_header` | HTML pages | Cookie OR Header | For vendor HTML routes like `/vendor/{code}/dashboard` |
| `get_current_vendor_api` | API endpoints | Header ONLY | For vendor API routes like `/api/v1/vendor/{code}/products` |
| `get_current_vendor_optional` | Login pages | Cookie OR Header | Returns `None` instead of raising exception |
### Customer Authentication
| Dependency | Use Case | Accepts | Description |
|------------|----------|---------|-------------|
| `get_current_customer_from_cookie_or_header` | HTML pages | Cookie OR Header | For shop account pages like `/shop/account/dashboard` |
| `get_current_customer_api` | API endpoints | Header ONLY | For shop API routes like `/api/v1/shop/cart` |
| `get_current_customer_optional` | Login pages | Cookie OR Header | Returns `None` instead of raising exception |
## When to Use Which?
### Use `_from_cookie_or_header` for HTML Pages
HTML pages that render templates and are accessed by browsers:
```python
# app/routes/admin_pages.py
from app.api.deps import get_current_admin_from_cookie_or_header
@router.get("/admin/dashboard", response_class=HTMLResponse)
async def admin_dashboard(
request: Request,
current_user: User = Depends(get_current_admin_from_cookie_or_header)
):
return templates.TemplateResponse("admin/dashboard.html", {...})
```
**Why?** Browsers automatically send cookies, making this seamless for page navigation.
### Use `_api` for API Endpoints
JSON API endpoints that are called by JavaScript:
```python
# app/api/v1/admin/vendors.py
from app.api.deps import get_current_admin_api
@router.get("/api/v1/admin/vendors")
async def list_vendors(
current_user: User = Depends(get_current_admin_api),
db: Session = Depends(get_db)
):
return {"vendors": [...]}
```
**Why?**
- **Security**: API endpoints should NOT accept cookies (prevents CSRF attacks)
- **Explicit**: JavaScript must explicitly set Authorization header
- **Stateless**: API calls are stateless and don't rely on browser cookies
### Use `_optional` for Login Pages
Login pages that redirect if already authenticated:
```python
# app/routes/admin_pages.py
from app.api.deps import get_current_admin_optional
@router.get("/admin/login", response_class=HTMLResponse)
async def admin_login_page(
request: Request,
current_user: Optional[User] = Depends(get_current_admin_optional)
):
if current_user:
return RedirectResponse("/admin/dashboard")
return templates.TemplateResponse("admin/login.html", {...})
```
**Why?** Avoids showing login page to already-authenticated users.
## Migration Guide
### Old vs New Names
The authentication dependencies were renamed for clarity:
| ❌ Old Name (REMOVED) | ✅ New Name | Type |
|----------------------|-------------|------|
| `get_current_admin_user` | `get_current_admin_from_cookie_or_header` | HTML pages |
| `get_current_admin_user` | `get_current_admin_api` | API endpoints |
| `get_current_vendor_user` | `get_current_vendor_from_cookie_or_header` | HTML pages |
| `get_current_vendor_user` | `get_current_vendor_api` | API endpoints |
### How to Update Your Code
1. **Identify route type**: Is it an HTML page or API endpoint?
2. **Choose correct dependency**:
- HTML page → `_from_cookie_or_header`
- API endpoint → `_api`
3. **Update import and usage**
#### Example 1: HTML Page Route
**Before:**
```python
from app.api.deps import get_current_admin_user # ❌ Doesn't exist
@router.get("/admin/settings")
def settings_page(current_user: User = Depends(get_current_admin_user)):
...
```
**After:**
```python
from app.api.deps import get_current_admin_from_cookie_or_header # ✅
@router.get("/admin/settings")
def settings_page(
current_user: User = Depends(get_current_admin_from_cookie_or_header)
):
...
```
#### Example 2: API Endpoint
**Before:**
```python
from app.api.deps import get_current_admin_user # ❌ Doesn't exist
@router.post("/api/v1/admin/vendors")
def create_vendor(current_user: User = Depends(get_current_admin_user)):
...
```
**After:**
```python
from app.api.deps import get_current_admin_api # ✅
@router.post("/api/v1/admin/vendors")
def create_vendor(current_user: User = Depends(get_current_admin_api)):
...
```
## Quick Reference
```python
# All available in app.api.deps
# ADMIN
from app.api.deps import (
get_current_admin_from_cookie_or_header, # HTML pages
get_current_admin_api, # API endpoints
get_current_admin_optional, # Login pages
)
# VENDOR
from app.api.deps import (
get_current_vendor_from_cookie_or_header, # HTML pages
get_current_vendor_api, # API endpoints
get_current_vendor_optional, # Login pages
)
# CUSTOMER
from app.api.deps import (
get_current_customer_from_cookie_or_header, # HTML pages
get_current_customer_api, # API endpoints
get_current_customer_optional, # Login pages
)
# GENERIC (any authenticated user)
from app.api.deps import get_current_user # Header-only, any role
```
## See Also
- [Authentication Documentation](../api/authentication.md) - Complete auth system docs
- [Authentication Flow Diagrams](../api/authentication-flow-diagrams.md) - Visual flows
- [API Dependencies](../app/api/deps.py) - Source code