Adolfo Delorenzo
b08574efe5
- Add flask-cors dependency and configure CORS with security best practices - Support configurable CORS origins via environment variables - Separate admin endpoint CORS configuration for enhanced security - Create comprehensive CORS configuration documentation - Add apiClient utility for CORS-aware frontend requests - Include CORS test page for validation - Update README with CORS configuration instructions 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
152 lines
4.4 KiB
Markdown
152 lines
4.4 KiB
Markdown
# CORS Configuration Guide
|
|
|
|
This document explains how to configure Cross-Origin Resource Sharing (CORS) for the Talk2Me application.
|
|
|
|
## Overview
|
|
|
|
CORS is configured using Flask-CORS to enable secure cross-origin usage of the API endpoints. This allows the Talk2Me application to be embedded in other websites or accessed from different domains while maintaining security.
|
|
|
|
## Environment Variables
|
|
|
|
### `CORS_ORIGINS`
|
|
|
|
Controls which domains are allowed to access the API endpoints.
|
|
|
|
- **Default**: `*` (allows all origins - use only for development)
|
|
- **Production Example**: `https://yourdomain.com,https://app.yourdomain.com`
|
|
- **Format**: Comma-separated list of allowed origins
|
|
|
|
```bash
|
|
# Development (allows all origins)
|
|
export CORS_ORIGINS="*"
|
|
|
|
# Production (restrict to specific domains)
|
|
export CORS_ORIGINS="https://talk2me.example.com,https://app.example.com"
|
|
```
|
|
|
|
### `ADMIN_CORS_ORIGINS`
|
|
|
|
Controls which domains can access admin endpoints (more restrictive).
|
|
|
|
- **Default**: `http://localhost:*` (allows all localhost ports)
|
|
- **Production Example**: `https://admin.yourdomain.com`
|
|
- **Format**: Comma-separated list of allowed admin origins
|
|
|
|
```bash
|
|
# Development
|
|
export ADMIN_CORS_ORIGINS="http://localhost:*"
|
|
|
|
# Production
|
|
export ADMIN_CORS_ORIGINS="https://admin.talk2me.example.com"
|
|
```
|
|
|
|
## Configuration Details
|
|
|
|
The CORS configuration includes:
|
|
|
|
- **Allowed Methods**: GET, POST, OPTIONS
|
|
- **Allowed Headers**: Content-Type, Authorization, X-Requested-With, X-Admin-Token
|
|
- **Exposed Headers**: Content-Range, X-Content-Range
|
|
- **Credentials Support**: Enabled (supports cookies and authorization headers)
|
|
- **Max Age**: 3600 seconds (preflight requests cached for 1 hour)
|
|
|
|
## Endpoints
|
|
|
|
All endpoints have CORS enabled with the following configuration:
|
|
|
|
### Regular API Endpoints
|
|
- `/api/*`
|
|
- `/transcribe`
|
|
- `/translate`
|
|
- `/translate/stream`
|
|
- `/speak`
|
|
- `/get_audio/*`
|
|
- `/check_tts_server`
|
|
- `/update_tts_config`
|
|
- `/health/*`
|
|
|
|
### Admin Endpoints (More Restrictive)
|
|
- `/admin/*` - Uses `ADMIN_CORS_ORIGINS` instead of general `CORS_ORIGINS`
|
|
|
|
## Security Best Practices
|
|
|
|
1. **Never use `*` in production** - Always specify exact allowed origins
|
|
2. **Use HTTPS** - Always use HTTPS URLs in production CORS origins
|
|
3. **Separate admin origins** - Keep admin endpoints on a separate, more restrictive origin list
|
|
4. **Review regularly** - Periodically review and update allowed origins
|
|
|
|
## Example Configurations
|
|
|
|
### Local Development
|
|
```bash
|
|
export CORS_ORIGINS="*"
|
|
export ADMIN_CORS_ORIGINS="http://localhost:*"
|
|
```
|
|
|
|
### Staging Environment
|
|
```bash
|
|
export CORS_ORIGINS="https://staging.talk2me.com,https://staging-app.talk2me.com"
|
|
export ADMIN_CORS_ORIGINS="https://staging-admin.talk2me.com"
|
|
```
|
|
|
|
### Production Environment
|
|
```bash
|
|
export CORS_ORIGINS="https://talk2me.com,https://app.talk2me.com"
|
|
export ADMIN_CORS_ORIGINS="https://admin.talk2me.com"
|
|
```
|
|
|
|
### Mobile App Integration
|
|
```bash
|
|
# Include mobile app schemes if needed
|
|
export CORS_ORIGINS="https://talk2me.com,https://app.talk2me.com,capacitor://localhost,ionic://localhost"
|
|
```
|
|
|
|
## Testing CORS Configuration
|
|
|
|
You can test CORS configuration using curl:
|
|
|
|
```bash
|
|
# Test preflight request
|
|
curl -X OPTIONS https://your-api.com/api/transcribe \
|
|
-H "Origin: https://allowed-origin.com" \
|
|
-H "Access-Control-Request-Method: POST" \
|
|
-H "Access-Control-Request-Headers: Content-Type" \
|
|
-v
|
|
|
|
# Test actual request
|
|
curl -X POST https://your-api.com/api/transcribe \
|
|
-H "Origin: https://allowed-origin.com" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"test": "data"}' \
|
|
-v
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### CORS Errors in Browser Console
|
|
|
|
If you see CORS errors:
|
|
|
|
1. Check that the origin is included in `CORS_ORIGINS`
|
|
2. Ensure the URL protocol matches (http vs https)
|
|
3. Check for trailing slashes in origins
|
|
4. Verify environment variables are set correctly
|
|
|
|
### Common Issues
|
|
|
|
1. **"No 'Access-Control-Allow-Origin' header"**
|
|
- Origin not in allowed list
|
|
- Check `CORS_ORIGINS` environment variable
|
|
|
|
2. **"CORS policy: The request client is not a secure context"**
|
|
- Using HTTP instead of HTTPS
|
|
- Update to use HTTPS in production
|
|
|
|
3. **"CORS policy: Credentials flag is true, but Access-Control-Allow-Credentials is not 'true'"**
|
|
- This should not occur with current configuration
|
|
- Check that `supports_credentials` is True in CORS config
|
|
|
|
## Additional Resources
|
|
|
|
- [MDN CORS Documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
|
|
- [Flask-CORS Documentation](https://flask-cors.readthedocs.io/) |