Comprehensive Security API Documentation
Educational Demo Project - Complete implementation of enterprise-grade security patterns
Note: The base URL (http://dotnet.oxfordbadfriends.com) is automatically detected from your current host. All commands below use this URL.
Select an API link to interact with.
Authentication & Authorization APIs
1. User Registration
POST /api/auth/register
Register a new user with comprehensive validation and security checks.
Features Demonstrated:
- FluentValidation with business rules
- Password complexity requirements
- Email domain validation
- Banned words filtering
- Age validation (13-120)
- Input sanitization middleware
- Security event logging
cURL Command:
curl -X POST "http://dotnet.oxfordbadfriends.com/api/auth/register" -H "Content-Type: application/json" -d '{"name": "John Doe", "email": "john.doe@company.com", "age": 25, "password": "SecurePass123!"}'
Expected Response (Success):
{
"id": 2,
"name": "John Doe",
"email": "john.doe@company.com",
"createdAt": "2025-07-28T16:17:58.8589165Z"
}
2. User Login
POST /api/auth/login
Secure login with JWT tokens, rate limiting, and account lockout protection.
Features Demonstrated:
- JWT Bearer authentication
- Refresh token system
- Progressive delay on failed attempts
- Account lockout after multiple failures
- Secure password verification
- Security event logging
cURL Command:
curl -X POST "http://dotnet.oxfordbadfriends.com/api/auth/login" -H "Content-Type: application/json" -d '{"email": "testuser@example.com", "password": "testpassword123"}'
Expected Response (Success):
{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjEiLCJlbWFpbCI6InRlc3R1c2VyQGV4YW1wbGUuY29tIiwicm9sZSI6IlVzZXIiLCJqdGkiOiI3YmE4ODZkYS1hMjg2LTRhMjgtYTJhMy02MmQ3YWViNzYzZmIiLCJpYXQiOjE3NTM3MTc1MTEsInVuaXF1ZV9uYW1lIjoiVGVzdCBVc2VyIiwibmJmIjoxNzUzNzE3NTExLCJleHAiOjE3NTM3MTg0MTEsImlzcyI6IldlYkFwcFJhem9yIiwiYXVkIjoiV2ViQXBwUmF6b3JVc2VycyJ9.tNPQtnIBb2LAaGvvkMxUJMu0HzU4_OhKDhEf7NO5LXg","refreshToken":"MkZTsAGQzuwbdeEaAufBx3h9dSn+EtJlCQ1qTw1XeXX3MJ1/hS2pIm2xO+m4KaBCrbjEpIr2Ro7a82gVkPVW5g==","expires":"2025-07-28T16:33:23.652726Z","user":{"id":1,"name":"Test User","email":"testuser@example.com","role":"User"}}
3. Token Refresh
POST /api/auth/refresh
Refresh expired JWT tokens using refresh tokens.
cURL Command:
curl -X POST "http://dotnet.oxfordbadfriends.com/api/auth/refresh" -H "Content-Type: application/json" -d '{"refreshToken": "YOUR_REFRESH_TOKEN", "userId": 1}'
Expected Response (Success):
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "base64encodedrefreshtoken...",
"expires": "2025-07-28T16:15:11.1751774Z"
}
4. Secure Logout
POST /api/auth/logout
Logout with token revocation and security logging.
cURL Command:
curl -X POST "http://dotnet.oxfordbadfriends.com/api/auth/logout" -H "Authorization: Bearer YOUR_JWT_TOKEN"
Expected Response (Success):
{
"message": "Logged out successfully"
}
Secure Data Access APIs
5. Get Todo Items (Protected)
GET /api/TodoItems
Retrieve todo items with JWT authentication and authorization.
Note: This endpoint requires a valid JWT token. You must login first to obtain a token.
Features Demonstrated:
- JWT Bearer token validation
- User authorization policies
- Data access auditing
- Security headers middleware
cURL Command:
curl -X GET "http://dotnet.oxfordbadfriends.com/api/TodoItems" -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Accept: application/json"
Expected Response (Success):
{
"data": [
{
"id": 1,
"name": "Complete security implementation",
"isComplete": false,
"createdAt": "2025-07-28T10:30:00Z",
"updatedAt": null
}
],
"page": 1,
"pageSize": 10,
"totalCount": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPreviousPage": false
}
6. Create Todo Item (Protected)
POST /api/TodoItems
Create new todo item with input validation and sanitization.
Note: This endpoint requires a valid JWT token. You must login first to obtain a token.
cURL Command:
curl -X POST "http://dotnet.oxfordbadfriends.com/api/TodoItems" -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" -d '{"name": "Complete security implementation", "isComplete": false}'
Expected Response (Success):
{
"id": 2,
"name": "Complete security implementation",
"isComplete": false,
"createdAt": "2025-07-28T10:35:00Z",
"updatedAt": null
}
Security Testing & Validation
7. Test Input Sanitization
Test the input sanitization middleware with potentially malicious input.
XSS Attempt via Login (Will be sanitized):
curl -X POST "http://dotnet.oxfordbadfriends.com/api/auth/login" -H "Content-Type: application/json" -d '{"email": "<script>alert(\"XSS\");</script>@example.com", "password": "test123"}'
Expected Response (Validation Error):
{
"message": "Validation failed",
"errors": [
{
"field": "Email",
"message": "Invalid email format"
}
]
}
Alternative XSS Test via Registration (Note: Rate Limited):
curl -X POST "http://dotnet.oxfordbadfriends.com/api/auth/register" -H "Content-Type: application/json" -d '{"name": "<script>alert(\"XSS\");</script>", "email": "test-xss@example.com", "age": 25, "password": "SecurePass123!"}'
Note: Registration endpoint has rate limiting (10 attempts per hour per IP). Use the login XSS test above for unlimited testing, or wait/restart app to reset cache for registration tests.
8. Test Rate Limiting
Multiple rapid requests to trigger rate limiting protection.
Rapid Login Attempts:
for i in {1..10}; do
curl -X POST "http://dotnet.oxfordbadfriends.com/api/auth/login" -H "Content-Type: application/json" -d '{"email": "nonexistent@example.com", "password": "wrongpassword"}'
echo "Attempt $i completed"
done
9. Test Validation Rules
Test FluentValidation with various invalid inputs.
Invalid Age (Below minimum):
curl -X POST "http://dotnet.oxfordbadfriends.com/api/auth/register" -H "Content-Type: application/json" -d '{"name": "Young User", "email": "young@example.com", "age": 10, "password": "SecurePass123!"}'
Weak Password:
curl -X POST "http://dotnet.oxfordbadfriends.com/api/auth/register" -H "Content-Type: application/json" -d '{"name": "Test User", "email": "test@example.com", "age": 25, "password": "weak"}'
Banned Words in Name:
curl -X POST "http://dotnet.oxfordbadfriends.com/api/auth/register" -H "Content-Type: application/json" -d '{"name": "Admin User", "email": "admin@example.com", "age": 25, "password": "SecurePass123!"}'
Secure Error Handling
10. Test Secure Exception Handler
Trigger various errors to see secure error responses (no information leakage).
Unauthorized Access:
curl -X GET "http://dotnet.oxfordbadfriends.com/api/TodoItems" -H "Accept: application/json"
No Authorization header - should return secure error
Expected Response (Unauthorized):
{
"error": "Unauthorized access",
"correlationId": "uuid-here"
}
Invalid Token:
curl -X GET "http://dotnet.oxfordbadfriends.com/api/TodoItems" -H "Authorization: Bearer invalid-token" -H "Accept: application/json"
Expected Response (Invalid Token):
{
"error": "Invalid or expired token",
"correlationId": "uuid-here"
}
Security Headers & CORS
11. Check Security Headers
Verify that security headers are properly applied.
View Response Headers:
curl -I "http://dotnet.oxfordbadfriends.com/"
Look for headers like: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin
Expected Security Headers:
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'...
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=()
12. Test CORS Policy
Test CORS preflight requests.
CORS Preflight (Development Mode - Should Allow):
curl -X OPTIONS "http://dotnet.oxfordbadfriends.com/api/auth/login" -H "Origin: https://evil-site.com" -H "Access-Control-Request-Method: POST" -H "Access-Control-Request-Headers: Content-Type" -v
In development mode, this should return CORS headers allowing the request
Expected Response (Development - CORS Allowed):
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://evil-site.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 300
Production CORS Test:
curl -X OPTIONS "http://dotnet.oxfordbadfriends.com/api/auth/login" -H "Origin: https://unauthorized-domain.com" -H "Access-Control-Request-Method: POST" -H "Access-Control-Request-Headers: Content-Type" -v
In production mode, this should be blocked for unauthorized origins
Expected Response (Production - CORS Blocked):
HTTP/1.1 200 OK
(No CORS headers returned, indicating the request is blocked)
Security Monitoring & Logging
Features Automatically Logged:
- All failed login attempts with IP addresses
- Account lockouts and security violations
- Data access patterns and user activities
- Input sanitization events
- Token refresh and logout events
- Rate limiting triggers
- Suspicious activity patterns
Log Location: Check your application logs for structured security events with correlation IDs.
Security Implementation Summary
Implemented Security Features:
- Authentication: JWT Bearer with refresh tokens
- Authorization: Role-based access control
- Input Validation: FluentValidation with business rules
- Input Sanitization: XSS/injection prevention middleware
- Rate Limiting: Account lockout and progressive delays
- Security Headers: CSP, HSTS, X-Frame-Options
- CORS Protection: Strict origin and method policies
- Error Handling: Secure exception handler (no info leakage)
- Security Logging: Structured audit trail with correlation IDs
- Password Security: ASP.NET Core Identity hashing
- CSRF Protection: Antiforgery tokens
- Data Protection: Secure database contexts and models
Ready for Educational Demonstration and Production Deployment!