Update README.md

G4brym · G4brym · commit 9ffe16c6882b · 2025-07-13T22:12:05.000+01:00
diff --git a/README.md b/README.md
@@ -15,8 +15,9 @@ This package provides integration with the following Cloudflare products:
 *   **Cloudflare Workers**: Run your Django application on Cloudflare's serverless compute platform.
 *   **Cloudflare D1**: Use Cloudflare's serverless SQL database as a backend for your Django application.
 *   **Cloudflare Durable Objects**: Leverage stateful objects for applications requiring persistent state within Cloudflare Workers.
+*   **Cloudflare Access Authentication**: Seamless authentication middleware for Cloudflare Access protected applications.
 
-### 1. Cloudflare Workers Integration
+## Cloudflare Workers Integration
 
 Run your Django application directly on Cloudflare Workers for edge performance and scalability.
 
@@ -174,7 +175,7 @@ root
     Access `https://your-worker-url.com/__run_migrations__/` to trigger migrations.
     Access `https://your-worker-url.com/__create_admin__/` to trigger admin creation.
 
-### 2. Cloudflare D1 Integration
+## Cloudflare D1 Integration
 
 Use Cloudflare D1, a serverless SQL database, as your Django application's database.
 
@@ -184,7 +185,7 @@ Use Cloudflare D1, a serverless SQL database, as your Django application's datab
 
 There are two ways to connect to D1:
 
-#### a) D1 Binding (Recommended for Workers)
+### a) D1 Binding (Recommended for Workers)
 
 When your Django application is running on Cloudflare Workers, use D1 Bindings for the fastest access. The D1 database is made available to your worker via an environment binding.
 
@@ -200,7 +201,7 @@ DATABASES = {
 ```
 Ensure your `wrangler.toml` includes the D1 database binding (as shown in the Cloudflare Workers section).
 
-#### b) D1 API (For Local Development or External Access)
+### b) D1 API (For Local Development or External Access)
 
 Connect to D1 via its HTTP API. This method is suitable for local development (e.g., running migrations) or when accessing D1 from outside Cloudflare Workers.
 
@@ -220,7 +221,7 @@ DATABASES = {
 
 A simple tutorial for getting started with Django and D1 is [available here](https://massadas.com/posts/django-meets-cloudflare-d1/).
 
-### 3. Cloudflare Durable Objects Integration
+## Cloudflare Durable Objects Integration
 
 Utilize Durable Objects for stateful data persistence directly within your Cloudflare Workers. This is useful for applications requiring low-latency access to state associated with specific objects or instances.
 
@@ -276,6 +277,278 @@ Utilize Durable Objects for stateful data persistence directly within your Cloud
     ```
     The `django_cf.do_binding` engine will automatically use the Durable Object binding specified in your `wrangler.toml` that is associated with the `DjangoCFDurableObject` class. Ensure your `wrangler.toml` correctly binds a name to your `DjangoCFDurableObject` subclass.
 
+## Cloudflare Access Authentication
+
+Seamless authentication middleware for Cloudflare Access protected applications. The middleware is implemented using only Python standard library modules - no external dependencies required!
+
+### Quick Start
+
+#### 1. Add to INSTALLED_APPS
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    # ... your other apps
+    'django_cf',
+]
+```
+
+#### 2. Configure Cloudflare Access Middleware
+
+Add the middleware to your Django settings:
+
+```python
+# settings.py
+MIDDLEWARE = [
+    'django.middleware.security.SecurityMiddleware',
+    'django.contrib.sessions.middleware.SessionMiddleware',  # Must be before CloudflareAccessMiddleware
+    'django.middleware.common.CommonMiddleware',
+    'django.middleware.csrf.CsrfViewMiddleware',
+    'django_cf.middleware.CloudflareAccessMiddleware',
+    # ... other middleware (should be placed appropriately in your middleware stack)
+]
+```
+
+#### 3. Configure Cloudflare Access Settings
+
+Add the required settings to your Django configuration:
+
+```python
+# settings.py
+
+# Required settings (at least one must be provided)
+CLOUDFLARE_ACCESS_AUD = 'your-application-audience-tag'  # Optional if team name is provided
+CLOUDFLARE_ACCESS_TEAM_NAME = 'yourteam'  # Optional if AUD is provided
+
+# Optional settings
+CLOUDFLARE_ACCESS_EXEMPT_PATHS = [
+    '/health/',
+    '/api/public/',
+    '/admin/login/',  # If you want to keep Django admin login
+]
+CLOUDFLARE_ACCESS_CACHE_TIMEOUT = 3600  # Cache timeout for public keys (seconds)
+```
+
+### Required Settings (At Least One)
+
+You must provide **at least one** of the following settings:
+
+#### `CLOUDFLARE_ACCESS_AUD`
+Your Cloudflare Access Application Audience (AUD) tag. You can find this in your Cloudflare Zero Trust dashboard:
+1. Go to Access → Applications
+2. Select your application
+3. Copy the "Application Audience (AUD) Tag"
+
+**When to use**: Provide this if you want strict audience validation or if you have multiple applications with the same team.
+
+#### `CLOUDFLARE_ACCESS_TEAM_NAME`
+Your Cloudflare team name (the subdomain part of your team domain). For example, if your team domain is `mycompany.cloudflareaccess.com`, then your team name is `mycompany`.
+
+**When to use**: Provide this if you want simpler configuration or if you only have one application per team.
+
+### Configuration Options
+
+You can configure the middleware in three ways:
+
+1. **Both AUD and Team Name** (Recommended for production):
+   ```python
+   CLOUDFLARE_ACCESS_AUD = 'your-application-audience-tag'
+   CLOUDFLARE_ACCESS_TEAM_NAME = 'yourteam'
+   ```
+
+2. **Only AUD** (Team name extracted from JWT):
+   ```python
+   CLOUDFLARE_ACCESS_AUD = 'your-application-audience-tag'
+   ```
+
+3. **Only Team Name** (AUD validated but not enforced):
+   ```python
+   CLOUDFLARE_ACCESS_TEAM_NAME = 'yourteam'
+   ```
+
+### Optional Settings
+
+#### `CLOUDFLARE_ACCESS_EXEMPT_PATHS`
+Default: `[]`
+
+List of URL paths that should be exempt from Cloudflare Access authentication. Useful for:
+- Health check endpoints
+- Public API endpoints
+- Webhooks
+- Static file serving (if not handled by your web server)
+
+Example:
+```python
+CLOUDFLARE_ACCESS_EXEMPT_PATHS = [
+    '/health/',
+    '/api/public/',
+    '/webhooks/',
+    '/static/',  # If serving static files through Django
+]
+```
+
+#### `CLOUDFLARE_ACCESS_CACHE_TIMEOUT`
+Default: `3600` (1 hour)
+
+How long to cache Cloudflare's public keys (in seconds). Cloudflare rotates these keys periodically, so caching reduces API calls while ensuring fresh keys are fetched when needed.
+
+### How It Works
+
+#### Authentication Flow
+
+1. **Request Processing**: For each incoming request, the middleware checks if the path is exempt from authentication
+2. **JWT Extraction**: Extracts the JWT token from:
+   - `CF-Access-Jwt-Assertion` header (preferred)
+   - `CF_Authorization` cookie (fallback)
+3. **Team Discovery**: If team name is not configured, extracts it from the JWT's issuer claim
+4. **Public Key Retrieval**: Fetches Cloudflare's public keys from the team's certs endpoint
+5. **Token Validation**: Validates the JWT against Cloudflare's public keys:
+   - Validates token signature and expiration
+   - Validates audience (AUD) if configured
+6. **User Management**: 
+   - Extracts email and name from JWT claims
+   - Creates new Django user if doesn't exist
+   - Updates existing user's name if changed
+   - Logs the user into Django session
+7. **Response**: Proceeds with the request if authentication succeeds, returns 401 if it fails
+
+#### User Creation
+
+When a user authenticates for the first time:
+- Username is set to the user's email address
+- Email is extracted from JWT `email` claim
+- Name is split into first_name and last_name from JWT `name` claim
+- User is created with `is_active=True`
+
+For existing users:
+- Name is updated if it has changed in Cloudflare
+- User is automatically logged in
+
+### Security Considerations
+
+#### Token Validation
+- All JWT tokens are validated against Cloudflare's public keys
+- Tokens are checked for expiration
+- Audience (AUD) is validated to ensure tokens are for your application
+
+#### Caching
+- Public keys are cached to reduce API calls to Cloudflare
+- Cache keys are scoped to your team name
+- Failed key fetches are logged but don't crash the application
+
+#### Error Handling
+- Authentication failures return 401 responses
+- Server errors return 500 responses
+- All errors are logged for debugging
+
+### Logging
+
+The middleware uses Django's logging system with logger name `django_cf.middleware`. To see debug information:
+
+```python
+# settings.py
+LOGGING = {
+    'version': 1,
+    'disable_existing_loggers': False,
+    'handlers': {
+        'console': {
+            'class': 'logging.StreamHandler',
+        },
+    },
+    'loggers': {
+        'django_cf.middleware': {
+            'handlers': ['console'],
+            'level': 'INFO',
+            'propagate': True,
+        },
+    },
+}
+```
+
+### Common Issues and Troubleshooting
+
+#### 401 Unauthorized Responses
+
+**Cause**: JWT token is missing, invalid, or expired.
+
+**Solutions**:
+1. Ensure your application is behind Cloudflare Access
+2. Check that users are properly authenticated with Cloudflare Access
+3. If using `CLOUDFLARE_ACCESS_AUD`, verify it matches your application's AUD tag
+4. If using `CLOUDFLARE_ACCESS_TEAM_NAME`, check that it's correct
+5. Review middleware logs for specific validation errors
+
+#### 500 Internal Server Error
+
+**Cause**: Unable to fetch Cloudflare public keys or other configuration issues.
+
+**Solutions**:
+1. Verify your team name is correct (if using `CLOUDFLARE_ACCESS_TEAM_NAME`)
+2. Check network connectivity to Cloudflare
+3. Review logs for specific error messages
+4. If using only AUD, ensure the JWT contains a valid issuer claim
+
+#### Users Not Being Created
+
+**Cause**: Missing email claim in JWT or database issues.
+
+**Solutions**:
+1. Check that your Cloudflare Access application is configured to include email in JWT
+2. Verify Django database migrations are up to date
+3. Check Django user model permissions
+
+### Advanced Usage
+
+#### Custom User Creation
+
+If you need custom user creation logic, you can subclass the middleware:
+
+```python
+from django_cf.middleware import CloudflareAccessMiddleware
+from django.contrib.auth import get_user_model
+
+User = get_user_model()
+
+class CustomCloudflareAccessMiddleware(CloudflareAccessMiddleware):
+    def _get_or_create_user(self, email, name):
+        # Your custom user creation logic here
+        user, created = User.objects.get_or_create(
+            email=email,
+            defaults={
+                'username': email,
+                'first_name': name.split(' ')[0] if name else '',
+                'last_name': ' '.join(name.split(' ')[1:]) if name else '',
+                'is_active': True,
+                'is_staff': email.endswith('@yourcompany.com'),  # Custom logic
+            }
+        )
+        return user
+```
+
+#### Multiple Applications
+
+If you have multiple Cloudflare Access applications, you can configure different middleware instances or use environment-specific settings.
+
+### Development
+
+#### Testing
+
+When developing applications with this middleware, you may want to disable it in certain environments:
+
+```python
+# settings.py
+if DEBUG and not os.getenv('ENABLE_CF_ACCESS'):
+    # Remove CloudflareAccessMiddleware from MIDDLEWARE list
+    MIDDLEWARE = [m for m in MIDDLEWARE if 'CloudflareAccessMiddleware' not in m]
+```
+
+#### Local Development
+
+For local development without Cloudflare Access:
+1. Set exempt paths to include your development URLs
+2. Use Django's built-in authentication for local testing
+3. Consider using environment variables to toggle the middleware
+
 ## Limitations
 
 *   **D1 Database:**
@@ -285,13 +558,23 @@ Utilize Durable Objects for stateful data persistence directly within your Cloud
     *   Always refer to the official [Django limitations for SQLite databases](https://docs.djangoproject.com/en/stable/ref/databases/#sqlite-notes), as D1 is SQLite-compatible but has its own serverless characteristics.
 *   **Durable Objects:** While powerful for stateful serverless applications, ensure you understand the consistency model and potential data storage costs associated with Durable Objects.
 
-## Development
+## Contributing
 
 See [DEVELOPMENT.md](DEVELOPMENT.md) for details on setting up a development environment and contributing to `django-cf`.
 
+We welcome contributions! Please see our contributing guidelines and feel free to submit issues and pull requests.
+
+## Support
+
+For issues and questions:
+1. Check the troubleshooting section above
+2. Review Cloudflare Access documentation
+3. Submit an issue on GitHub with detailed error logs and configuration (remove sensitive information)
+
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
 ---
 
 *For a more detailed example of a Django project structured for Cloudflare Workers with D1, check out relevant community projects or the `django-cf` examples if available.*
