drf-spectacular-auth 1.3.0

Secure Authentication UI for DRF Spectacular with HttpOnly Cookie support, AWS Cognito integration, and XSS protection

DRF Spectacular Auth

🔐 Authentication UI for DRF Spectacular with AWS Cognito support

A Django package that adds a beautiful authentication panel to your DRF Spectacular (Swagger UI) documentation, with built-in support for AWS Cognito and extensible authentication providers.

🆕 What's New in v1.3.0

• 🔐 HttpOnly Cookie Security - Enhanced XSS protection with secure token storage
• 🛡️ 90%+ Security Improvement - CSRF protection with SameSite cookies
• 🔄 Backward Compatibility - Seamless upgrade with fallback to localStorage/sessionStorage
• 🧹 Code Optimization - Improved imports, cleaner structure, removed cache files
• 📚 Migration Guide - Complete HttpOnly Cookie migration documentation
• 🔧 Enhanced Middleware - Better cookie-based authentication handling

✨ Features

• 🔐 Enhanced Security: HttpOnly cookies with XSS and CSRF protection
• 🎨 Beautiful UI: Clean, modern authentication panel that integrates seamlessly with Swagger UI
• 🛡️ AWS Cognito Support: Built-in integration with AWS Cognito User Pools
• 📋 Smart Token Management: Secure cookie-based with localStorage fallback
• 🎯 Auto Authorization: Automatically populates Swagger UI authorization headers
• 🎨 Customizable: Flexible theming and positioning options
• 🌍 i18n Ready: Multi-language support (Korean, English, Japanese)
• 🔧 Extensible: Plugin system for additional authentication providers
• 📦 Easy Integration: Minimal setup with sensible defaults

🚀 Quick Start

Installation

pip install drf-spectacular-auth

Or get the latest version:

pip install --upgrade drf-spectacular-auth

Basic Setup

1. Add to your Django settings:

INSTALLED_APPS = [
    'drf_spectacular_auth',  # Add 'drf_spectacular_auth' before 'drf_spectacular'
    'drf_spectacular',
    # ... your other apps
]

# Optional: Add authentication backend for better integration
AUTHENTICATION_BACKENDS = [
    'drf_spectacular_auth.backend.SpectacularAuthBackend',
    'django.contrib.auth.backends.ModelBackend',  # Keep default backend
]

# Optional: Add middleware for automatic authentication
MIDDLEWARE = [
    # ... your existing middleware
    'drf_spectacular_auth.middleware.SpectacularAuthMiddleware',
    # ... rest of your middleware
]

DRF_SPECTACULAR_AUTH = {
    'COGNITO_REGION': 'your-aws-region',
    'COGNITO_CLIENT_ID': 'your-cognito-client-id',
    'COGNITO_CLIENT_SECRET': 'your-client-secret',  # Private client인 경우에만 필요
    
    # Optional: User management settings
    'AUTO_CREATE_USERS': True,  # Auto-create users from Cognito
    'REQUIRE_AUTHENTICATION': False,  # Require auth to access Swagger UI
}

2. Update your URLs:

from drf_spectacular_auth.views import SpectacularAuthSwaggerView

urlpatterns = [
    path('api/auth/', include('drf_spectacular_auth.urls')),  # Authentication endpoints
    path('api/docs/', SpectacularAuthSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    # ... your other urls
]

3. That's it! 🎉 Your Swagger UI now has an authentication panel.

📁 Examples

Please Example Check examples/.

• basic_usage/ - Basic Django + DRF + AWS Cognito integration example
• cognito_integration/ - AWS Cognito integration (Not yet)
• custom_theming/ - Custom thema example (Not yet)
• hooks_example/ - Login and Logout hook example (Not yet)

Test

cd examples/basic_usage
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver

Check browser http://localhost:8000/docs/

🏗️ Architecture

Integration Strategies

This package offers multiple integration strategies to suit different use cases:

1. Simple Auth Panel (Default)

• Adds authentication panel to Swagger UI
• Minimal configuration required
• Good for basic documentation with optional authentication

2. HttpOnly Cookie Integration (Recommended)

• Secure HttpOnly cookie-based token storage
• XSS attack protection
• Automatic authentication handling
• CSRF protection with SameSite cookies

3. Middleware Integration

• Session-based auth persistence
• Better integration with existing Django auth

4. Backend Integration (Advanced)

• Full Django user integration
• Auto-create users from Cognito
• Supports existing Django permission systems

Comparison with django-auth-adfs

Unlike django-auth-adfs which focuses on ADFS/Azure AD integration, this package:

• Specializes in AWS Cognito authentication
• Focuses on API documentation (Swagger UI) integration
• Offers lighter-weight integration options
• Supports both simple overlay and full Django auth integration

⚙️ Configuration

AWS Cognito Client Types

Public Client (Basic):

• Not Client Secret
• COGNITO_CLIENT_SECRET=None

Private Client (Enhanced):

• Need Client Secret
• Must have COGNITO_CLIENT_SECRET
• Automatic calculate SECRET_HASH

# Public Client (Basic)
DRF_SPECTACULAR_AUTH = {
    'COGNITO_REGION': 'ap-northeast-2',
    'COGNITO_CLIENT_ID': 'your-public-client-id',
}

# Private Client (Enhanced)
DRF_SPECTACULAR_AUTH = {
    'COGNITO_REGION': 'ap-northeast-2',
    'COGNITO_CLIENT_ID': 'your-private-client-id',
    'COGNITO_CLIENT_SECRET': os.getenv('COGNITO_CLIENT_SECRET'),
}

Full Configuration Options

DRF_SPECTACULAR_AUTH = {
    # AWS Cognito Settings
    'COGNITO_REGION': 'ap-northeast-2',
    'COGNITO_CLIENT_ID': 'your-client-id',
    'COGNITO_CLIENT_SECRET': None,
    
    # API Endpoints
    'LOGIN_ENDPOINT': '/api/auth/login/',
    'LOGOUT_ENDPOINT': '/api/auth/logout/',
    
    # UI Settings
    'PANEL_POSITION': 'top-right',  # top-left, top-right, bottom-left, bottom-right
    'PANEL_STYLE': 'floating',      # floating, embedded
    'AUTO_AUTHORIZE': True,         # Auto-fill authorization headers
    'SHOW_COPY_BUTTON': True,       # Show token copy button
    'SHOW_USER_INFO': True,         # Show user email in panel
    
    # Theming
    'THEME': {
        'PRIMARY_COLOR': '#61affe',
        'SUCCESS_COLOR': '#28a745',
        'ERROR_COLOR': '#dc3545',
        'BACKGROUND_COLOR': '#ffffff',
        'BORDER_RADIUS': '8px',
        'SHADOW': '0 2px 10px rgba(0,0,0,0.1)',
    },
    
    # Localization
    'DEFAULT_LANGUAGE': 'ko',
    'SUPPORTED_LANGUAGES': ['ko', 'en', 'ja'],
    
    # Security (Enhanced)
    'USE_HTTPONLY_COOKIE': True,      # HttpOnly cookie storage (Recommended)
    'TOKEN_STORAGE': 'sessionStorage', # localStorage, sessionStorage (Fallback)
    'COOKIE_MAX_AGE': 3600,           # Cookie expiry in seconds (1 hour)
    'COOKIE_SECURE': True,            # HTTPS only (set False for development)
    'COOKIE_SAMESITE': 'Strict',      # CSRF protection
    'CSRF_PROTECTION': True,
    
    # User Management
    'AUTO_CREATE_USERS': False,  # Auto-create users from successful authentication
    'CREATE_TEMP_USER': True,   # Create temporary users for documentation access
    'REQUIRE_AUTHENTICATION': False,  # Require auth to access Swagger UI
    
    # Extensibility
    'CUSTOM_AUTH_PROVIDERS': [],
    'HOOKS': {
        'PRE_LOGIN': None,
        'POST_LOGIN': None,
        'PRE_LOGOUT': None,
        'POST_LOGOUT': None,
    }
}

🎨 Customization

Custom Authentication Provider

from drf_spectacular_auth.providers.base import AuthProvider

class CustomAuthProvider(AuthProvider):
    def authenticate(self, credentials):
        # Your custom authentication logic
        return {
            'access_token': 'your-token',
            'user': {'email': '[e-mail]'}
        }
    
    def get_user_info(self, token):
        # Get user information from token
        return {'email': '[e-mail]'}

# Register your provider
DRF_SPECTACULAR_AUTH = {
    'CUSTOM_AUTH_PROVIDERS': [
        'path.to.your.CustomAuthProvider'
    ]
}

Custom Templates

DRF_SPECTACULAR_AUTH = {
    'CUSTOM_TEMPLATES': {
        'auth_panel': 'your_app/custom_auth_panel.html',
        'login_form': 'your_app/custom_login_form.html',
    }
}

🐛 Troubleshooting

Common Issues

Q: I see unwanted topbar in my Swagger UI
A: Update to v1.2.0+ which fixes the template inheritance issue.

Q: Authentication panel is not showing
A: Make sure you're using SpectacularAuthSwaggerView instead of the default Swagger view.

Q: Token not being auto-authorized in Swagger
A: Verify that AUTO_AUTHORIZE: True is set in your settings and check browser console for errors.

Q: AWS Cognito authentication fails
A: Check your Cognito configuration:

• Verify COGNITO_REGION, COGNITO_CLIENT_ID are correct
• For private clients, ensure COGNITO_CLIENT_SECRET is set
• Check AWS Cognito logs for detailed error messages

Q: Template loading errors
A: Ensure drf_spectacular_auth is added to INSTALLED_APPS before drf_spectacular.

Migration from Previous Versions

From v1.1.x to v1.2.0:

• No breaking changes - just update your package
• Topbar issues will be automatically resolved
• Remove any custom workarounds for template conflicts

🔧 Development

Local Development

git clone https://github.com/CodeMath/drf-spectacular-auth.git
cd drf-spectacular-auth
pip install -e ".[dev]"

Running Tests

pytest
pytest --cov=drf_spectacular_auth

Code Quality

black .
isort .
flake8

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• DRF Spectacular for the excellent API documentation framework
• AWS Cognito for authentication services
• Swagger UI for the beautiful API documentation interface

📚 Links

• Documentation
• PyPI
• GitHub
• Issues