377 lines
9.8 KiB
Markdown
377 lines
9.8 KiB
Markdown
# Authentication Usage Examples
|
|
|
|
This document provides practical examples of how to use the authentication system in the Ecommerce Backend API.
|
|
|
|
## Overview
|
|
|
|
The API uses JWT (JSON Web Token) authentication with the following workflow:
|
|
1. Register a new user account
|
|
2. Login to receive a JWT token
|
|
3. Include the token in the `Authorization` header for protected endpoints
|
|
4. Token expires after 30 minutes (configurable)
|
|
|
|
## Python Examples
|
|
|
|
### Basic Authentication Functions
|
|
|
|
```python
|
|
import requests
|
|
|
|
# API Base URL
|
|
BASE_URL = "http://localhost:8000"
|
|
|
|
def register_user(email, username, password):
|
|
"""Register a new user"""
|
|
response = requests.post(
|
|
f"{BASE_URL}/register",
|
|
json={"email": email, "username": username, "password": password},
|
|
)
|
|
return response.json()
|
|
|
|
def login_user(username, password):
|
|
"""Login and get JWT token"""
|
|
response = requests.post(
|
|
f"{BASE_URL}/login", json={"username": username, "password": password}
|
|
)
|
|
if response.status_code == 200:
|
|
data = response.json()
|
|
return data["access_token"]
|
|
else:
|
|
print(f"Login failed: {response.json()}")
|
|
return None
|
|
|
|
def get_user_info(token):
|
|
"""Get current user info"""
|
|
headers = {"Authorization": f"Bearer {token}"}
|
|
response = requests.get(f"{BASE_URL}/me", headers=headers)
|
|
return response.json()
|
|
```
|
|
|
|
### Using Protected Endpoints
|
|
|
|
```python
|
|
def get_products(token, skip=0, limit=10):
|
|
"""Get products (requires authentication)"""
|
|
headers = {"Authorization": f"Bearer {token}"}
|
|
response = requests.get(
|
|
f"{BASE_URL}/products?skip={skip}&limit={limit}", headers=headers
|
|
)
|
|
return response.json()
|
|
|
|
def create_product(token, product_data):
|
|
"""Create a new product (requires authentication)"""
|
|
headers = {"Authorization": f"Bearer {token}"}
|
|
response = requests.post(f"{BASE_URL}/products", json=product_data, headers=headers)
|
|
return response.json()
|
|
```
|
|
|
|
### Complete Workflow Example
|
|
|
|
```python
|
|
# Example usage workflow
|
|
if __name__ == "__main__":
|
|
# 1. Register a new user
|
|
print("1. Registering new user...")
|
|
try:
|
|
user_result = register_user("test@example.com", "testuser", "password123")
|
|
print(f"User registered: {user_result}")
|
|
except Exception as e:
|
|
print(f"Registration failed: {e}")
|
|
|
|
# 2. Login with default admin user
|
|
print("\n2. Logging in as admin...")
|
|
admin_token = login_user("admin", "admin123")
|
|
if admin_token:
|
|
print(f"Admin login successful! Token: {admin_token[:50]}...")
|
|
|
|
# 3. Get user info
|
|
print("\n3. Getting admin user info...")
|
|
user_info = get_user_info(admin_token)
|
|
print(f"User info: {user_info}")
|
|
|
|
# 4. Create a sample product
|
|
print("\n4. Creating a sample product...")
|
|
sample_product = {
|
|
"marketplace_product_id": "TEST001",
|
|
"title": "Test MarketplaceProduct",
|
|
"description": "A test product for demonstration",
|
|
"price": "19.99",
|
|
"brand": "Test Brand",
|
|
"availability": "in inventory",
|
|
}
|
|
|
|
product_result = create_product(admin_token, sample_product)
|
|
print(f"MarketplaceProduct created: {product_result}")
|
|
|
|
# 5. Get products list
|
|
print("\n5. Getting products list...")
|
|
products = get_products(admin_token)
|
|
print(f"Products: {products}")
|
|
|
|
# 6. Login with regular user
|
|
print("\n6. Logging in as regular user...")
|
|
user_token = login_user("testuser", "password123")
|
|
if user_token:
|
|
print(f"User login successful! Token: {user_token[:50]}...")
|
|
|
|
# Regular users can also access protected endpoints
|
|
user_info = get_user_info(user_token)
|
|
print(f"Regular user info: {user_info}")
|
|
|
|
products = get_products(user_token, limit=5)
|
|
print(
|
|
f"Products accessible to regular user: {len(products.get('products', []))} products"
|
|
)
|
|
|
|
print("\nAuthentication example completed!")
|
|
```
|
|
|
|
## cURL Examples
|
|
|
|
### Register a New User
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8000/register" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"email": "user@example.com",
|
|
"username": "newuser",
|
|
"password": "password123"
|
|
}'
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"id": 2,
|
|
"email": "user@example.com",
|
|
"username": "newuser",
|
|
"role": "user",
|
|
"is_active": true,
|
|
"created_at": "2024-01-15T10:30:00Z"
|
|
}
|
|
```
|
|
|
|
### Login (Get JWT Token)
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8000/login" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"username": "admin",
|
|
"password": "admin123"
|
|
}'
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|
"token_type": "bearer",
|
|
"expires_in": 1800,
|
|
"user": {
|
|
"id": 1,
|
|
"username": "admin",
|
|
"email": "admin@example.com",
|
|
"role": "admin",
|
|
"is_active": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### Use Token for Protected Endpoints
|
|
|
|
#### Get Current User Info
|
|
|
|
```bash
|
|
curl -X GET "http://localhost:8000/me" \
|
|
-H "Authorization: Bearer YOUR_JWT_TOKEN_HERE"
|
|
```
|
|
|
|
#### Get Products List
|
|
|
|
```bash
|
|
curl -X GET "http://localhost:8000/products" \
|
|
-H "Authorization: Bearer YOUR_JWT_TOKEN_HERE"
|
|
```
|
|
|
|
#### Create a MarketplaceProduct
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8000/products" \
|
|
-H "Authorization: Bearer YOUR_JWT_TOKEN_HERE" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"marketplace_product_id": "TEST001",
|
|
"title": "Test MarketplaceProduct",
|
|
"description": "A test product for demonstration",
|
|
"price": "19.99",
|
|
"brand": "Test Brand",
|
|
"availability": "in inventory"
|
|
}'
|
|
```
|
|
|
|
## Default Accounts
|
|
|
|
### Admin Account
|
|
- **Username**: `admin`
|
|
- **Password**: `admin123`
|
|
- **Email**: `admin@example.com`
|
|
- **Role**: `admin`
|
|
|
|
**Security Note**: Change the admin password immediately in production environments!
|
|
|
|
## Authentication Headers
|
|
|
|
All protected endpoints require the JWT token in the Authorization header:
|
|
|
|
```
|
|
Authorization: Bearer <your_jwt_token>
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
### Common Authentication Errors
|
|
|
|
#### Invalid Credentials (Login)
|
|
```json
|
|
{
|
|
"detail": "Invalid credentials"
|
|
}
|
|
```
|
|
|
|
#### Missing or Invalid Token
|
|
```json
|
|
{
|
|
"detail": "Not authenticated"
|
|
}
|
|
```
|
|
|
|
#### Expired Token
|
|
```json
|
|
{
|
|
"detail": "Token has expired"
|
|
}
|
|
```
|
|
|
|
#### Insufficient Permissions
|
|
```json
|
|
{
|
|
"detail": "Not enough permissions"
|
|
}
|
|
```
|
|
|
|
### Error Handling in Python
|
|
|
|
```python
|
|
def safe_api_call(token, endpoint, method="GET", data=None):
|
|
"""Make API call with proper error handling"""
|
|
headers = {"Authorization": f"Bearer {token}"}
|
|
|
|
try:
|
|
if method == "GET":
|
|
response = requests.get(f"{BASE_URL}{endpoint}", headers=headers)
|
|
elif method == "POST":
|
|
response = requests.post(f"{BASE_URL}{endpoint}", json=data, headers=headers)
|
|
|
|
if response.status_code == 401:
|
|
print("Authentication failed - token may be expired")
|
|
return None
|
|
elif response.status_code == 403:
|
|
print("Access denied - insufficient permissions")
|
|
return None
|
|
elif response.status_code == 200:
|
|
return response.json()
|
|
else:
|
|
print(f"API call failed: {response.status_code} - {response.text}")
|
|
return None
|
|
|
|
except requests.exceptions.RequestException as e:
|
|
print(f"Request failed: {e}")
|
|
return None
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### Token Management
|
|
|
|
1. **Store tokens securely** - Don't expose tokens in logs or client-side code
|
|
2. **Handle token expiration** - Implement automatic token refresh or re-login
|
|
3. **Use HTTPS in production** - Never send tokens over unencrypted connections
|
|
|
|
### Password Security
|
|
|
|
1. **Use strong passwords** - Minimum 6 characters (configurable)
|
|
2. **Don't hardcode passwords** - Use environment variables or secure configuration
|
|
3. **Regular password updates** - Especially for admin accounts
|
|
|
|
### API Integration
|
|
|
|
1. **Include error handling** - Always check response status codes
|
|
2. **Implement retry logic** - Handle temporary network issues
|
|
3. **Rate limiting awareness** - Respect API rate limits
|
|
|
|
## Testing Authentication
|
|
|
|
You can test the authentication system using the provided Python script or with make commands:
|
|
|
|
```bash
|
|
# Run authentication tests
|
|
make test-auth
|
|
|
|
# Run all tests including authentication
|
|
make test
|
|
```
|
|
|
|
## Integration with Frontend
|
|
|
|
### JavaScript/TypeScript Example
|
|
|
|
```javascript
|
|
class APIClient {
|
|
constructor(baseURL = 'http://localhost:8000') {
|
|
this.baseURL = baseURL;
|
|
this.token = localStorage.getItem('jwt_token');
|
|
}
|
|
|
|
async login(username, password) {
|
|
const response = await fetch(`${this.baseURL}/login`, {
|
|
method: 'POST',
|
|
headers: {'Content-Type': 'application/json'},
|
|
body: JSON.stringify({username, password})
|
|
});
|
|
|
|
if (response.ok) {
|
|
const data = await response.json();
|
|
this.token = data.access_token;
|
|
localStorage.setItem('jwt_token', this.token);
|
|
return data;
|
|
} else {
|
|
throw new Error('Login failed');
|
|
}
|
|
}
|
|
|
|
async apiCall(endpoint, method = 'GET', data = null) {
|
|
const headers = {
|
|
'Authorization': `Bearer ${this.token}`,
|
|
'Content-Type': 'application/json'
|
|
};
|
|
|
|
const config = {method, headers};
|
|
if (data) config.body = JSON.stringify(data);
|
|
|
|
const response = await fetch(`${this.baseURL}${endpoint}`, config);
|
|
|
|
if (response.status === 401) {
|
|
// Token expired, redirect to login
|
|
localStorage.removeItem('jwt_token');
|
|
window.location.href = '/login';
|
|
return;
|
|
}
|
|
|
|
return response.json();
|
|
}
|
|
}
|
|
```
|
|
|
|
This authentication system provides secure access control for all API endpoints while maintaining ease of use for developers integrating with the system. |