Reverse Proxy Authentication

Reverse Proxy Authentication Setup 🔐

Calibre-Web Automated supports reverse proxy authentication, enabling seamless integration with authentication gateways like Authelia, Authentik, Nginx Auth, Traefik ForwardAuth, and other reverse proxy authentication systems. This guide covers everything you need to know about configuring and using reverse proxy authentication in CWA.

---

🌟 Features Overview

CWA's reverse proxy authentication provides enterprise-grade SSO integration:

• ✅ Auto-User Creation: Automatically creates user accounts from trusted proxy headers (configurable)
• ✅ Header-Based Authentication: Supports standard authentication headers like Remote-User
• ✅ Default Permissions: New users inherit all default configuration settings
• ✅ SSO Integration: Works with popular authentication gateways
• ✅ Security Validation: Built-in configuration validation and security warnings
• ✅ Audit Logging: Comprehensive logging for authentication events
• ✅ Enterprise Ready: Designed for corporate SSO environments

---

⚠️ Security Warning

CRITICAL: Reverse proxy authentication should ONLY be used when:

1. CWA is not directly accessible from the internet or untrusted networks
2. All traffic goes through the authentication proxy - no bypass routes exist
3. The proxy validates users before setting authentication headers
4. Network traffic between proxy and CWA is secure and trusted
5. You understand the security implications of header-based authentication

Never enable this feature if CWA can be accessed directly, as it would allow anyone to impersonate users by setting HTTP headers.

---

🚀 Quick Setup Guide

Step 1: Configure Your Reverse Proxy

First, set up your reverse proxy to handle authentication and set the user header. Common examples:

Authelia + Nginx

server {
    server_name cwa.example.com;
    
    location / {
        # Authelia authentication
        auth_request /authelia;
        auth_request_set $user $upstream_http_remote_user;
        auth_request_set $groups $upstream_http_remote_groups;
        
        # Forward authentication header to CWA
        proxy_set_header Remote-User $user;
        proxy_pass http://cwa-backend;
    }
}

Traefik + Authelia

# docker-compose.yml
services:
  cwa:
    labels:
      - "traefik.http.routers.cwa.middlewares=authelia@docker"
      - "traefik.http.middlewares.authelia.forwardauth.authRequestHeaders=Remote-User"

Caddy + Authentication

cwa.example.com {
    forward_auth authelia:9091 {
        uri /api/verify?rd=https://auth.example.com/
        copy_headers Remote-User Remote-Groups
    }
    reverse_proxy cwa:8083 {
        header_up Remote-User {http.auth.user.id}
    }
}

Step 2: Access CWA Reverse Proxy Settings

1. Log in as an Admin user
2. Navigate to Admin Panel → Basic Configuration
3. Scroll down to Reverse Proxy Authentication section

Step 3: Configure CWA

☑️ Allow Reverse Proxy Authentication: Enabled
📝 Reverse Proxy Header Name: Remote-User
☑️ Auto-create users from reverse proxy: Enabled (recommended)

Step 4: Test and Validate

1. Save configuration and restart CWA
2. Test authentication through your reverse proxy
3. Verify user creation (if auto-create is enabled)
4. Check logs for authentication events

---

⚙️ Detailed Configuration

Reverse Proxy Authentication Settings

Setting	Description	Recommended Value
Allow Reverse Proxy Authentication	Enable header-based authentication	✅ Enabled
Reverse Proxy Header Name	HTTP header containing username	Remote-User (standard)
Auto-create users from reverse proxy	Automatically create user accounts	✅ Enabled

Header Name Options

Different authentication systems use different header names:

System	Common Header	Example Value
Authelia	Remote-User	john.doe
Authentik	X-authentik-username	john.doe
Nginx Auth	Remote-User	[email protected]
Traefik ForwardAuth	Remote-User	john.doe
Custom	X-Forwarded-User	user123

Configure the header name to match your reverse proxy setup.

---

🎯 Auto-User Creation

How Auto-Creation Works

When Auto-create users from reverse proxy is enabled:

1. Header Validation: CWA checks for the configured authentication header
2. User Lookup: Searches for existing user with header username
3. Auto-Creation: Creates new user if not found (when enabled)
4. Session Setup: Logs in user automatically
5. Audit Logging: Records authentication and creation events

Default Settings Applied to New Users

New reverse proxy users automatically inherit all default configuration settings:

• 📊 Default Role: Configured role permissions
• 📋 Sidebar View: Default sidebar visibility settings
• 🌍 Locale: Default interface language
• 📚 Default Language: Default book language filter
• 🏷️ Tag Restrictions: Default allowed/denied tags
• 📖 Content Restrictions: Default column restrictions
• 🎨 Theme: Default CWA theme setting
• 📱 Kobo Sync: Default Kobo integration settings

This ensures reverse proxy users get the same permissions and interface settings as manually created users.

When Auto-Creation is Disabled

If auto-creation is disabled:

• Existing users: Can log in normally via reverse proxy
• New users: Will see login failure - admin must create accounts manually
• Security: Provides more control over who gets accounts
• Enterprise: Suitable for pre-provisioned user environments

---

🔧 Reverse Proxy Examples

Authelia Integration

Authelia Configuration (configuration.yml):

authentication_backend:
  ldap:
    url: ldap://openldap
    base_dn: dc=example,dc=com
    
access_control:
  default_policy: deny
  rules:
    - domain: cwa.example.com
      policy: one_factor
      
session:
  domain: example.com

Nginx Configuration:

server {
    listen 443 ssl;
    server_name cwa.example.com;
    
    location /authelia {
        internal;
        proxy_pass http://authelia:9091/api/verify;
        proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
    }
    
    location / {
        auth_request /authelia;
        auth_request_set $user $upstream_http_remote_user;
        auth_request_set $groups $upstream_http_remote_groups;
        
        proxy_set_header Remote-User $user;
        proxy_set_header Remote-Groups $groups;
        proxy_pass http://cwa:8083;
    }
}

CWA Configuration:

☑️ Allow Reverse Proxy Authentication: Enabled
📝 Reverse Proxy Header Name: Remote-User  
☑️ Auto-create users from reverse proxy: Enabled

Authentik Integration

Authentik Outpost Configuration:

# Outpost configuration for CWA
authentik:
  host: https://auth.example.com
  
providers:
  - name: cwa-provider
    type: proxy
    external_host: https://cwa.example.com
    internal_host: http://cwa:8083
    
    # Forward authentication headers
    forward_auth_headers:
      - X-authentik-username
      - X-authentik-groups

CWA Configuration:

☑️ Allow Reverse Proxy Authentication: Enabled
📝 Reverse Proxy Header Name: X-authentik-username
☑️ Auto-create users from reverse proxy: Enabled

Traefik + ForwardAuth

Traefik Configuration (docker-compose.yml):

services:
  cwa:
    image: crocodilestick/calibre-web-automated
    labels:
      - "traefik.http.routers.cwa.rule=Host(`cwa.example.com`)"
      - "traefik.http.routers.cwa.middlewares=auth-headers"
      - "traefik.http.middlewares.auth-headers.forwardauth.address=http://auth-service:8080/verify"
      - "traefik.http.middlewares.auth-headers.forwardauth.authRequestHeaders=Remote-User,Remote-Groups"

CWA Configuration:

☑️ Allow Reverse Proxy Authentication: Enabled
📝 Reverse Proxy Header Name: Remote-User
☑️ Auto-create users from reverse proxy: Enabled

---

🧪 Testing & Troubleshooting

Testing Reverse Proxy Authentication

1. Verify proxy setup: Ensure authentication works at proxy level
2. Check headers: Confirm authentication headers are being sent to CWA
3. Test with curl:

   # Test authentication header forwarding
   curl -H "Remote-User: testuser" http://cwa.example.com/

4. Monitor logs: Check both proxy and CWA logs for authentication flow

Header Debugging

To debug header issues:

1. Enable CWA debug logging
2. Check proxy logs for header forwarding
3. Use browser developer tools to inspect request headers
4. Test with known working user

Common Issues & Solutions

❌ "Reverse proxy authentication failed"

Cause: Header not present or incorrect header name configured Solution:

• Verify Reverse Proxy Header Name matches your proxy configuration
• Check that proxy is forwarding the authentication header
• Test header forwarding with curl or browser developer tools
• Review proxy configuration for header forwarding rules

❌ "User not found after reverse proxy authentication"

Cause: Auto-creation disabled or failed, or user doesn't exist Solution:

• Enable Auto-create users from reverse proxy if desired
• Manually create user accounts for reverse proxy users if auto-creation disabled
• Check CWA logs for user creation errors
• Verify default user settings are properly configured

❌ Users can bypass authentication

Cause: CWA is accessible directly without going through proxy Solution:

• CRITICAL SECURITY ISSUE: Ensure CWA is only accessible through authenticated proxy
• Use firewall rules to block direct access to CWA
• Configure reverse proxy to be the only route to CWA
• Consider network segmentation to isolate CWA

❌ "Invalid or missing authentication header"

Cause: Proxy not configured to forward authentication headers Solution:

• Configure proxy to forward user identification headers
• Check proxy documentation for header forwarding syntax
• Verify authentication middleware is properly configured
• Test header forwarding independently of CWA

---

🔒 Security Best Practices

Network Security

Critical Security Requirements:

1. Isolate CWA: Ensure CWA is only accessible through the authentication proxy
2. No Direct Access: Block all direct network routes to CWA
3. Trusted Network: Secure the network segment between proxy and CWA
4. Firewall Rules: Use firewalls to enforce access restrictions

Network Architecture Example:

Internet → Reverse Proxy (Auth) → Internal Network → CWA
         ↑                                           ↑
      (Public)                                   (Private)

Header Security

• Validate Headers: CWA performs input validation on authentication headers
• Strip Dangerous Characters: Usernames are sanitized for security
• Prevent Header Injection: Proxy should strip/override user-supplied auth headers
• Use Standard Headers: Stick to well-known header names when possible

Audit and Monitoring

• Enable Authentication Logging: Monitor all reverse proxy authentication events
• Regular Security Reviews: Periodically audit proxy and CWA configurations
• Access Monitoring: Monitor for unusual authentication patterns
• Incident Response: Have procedures for handling authentication security incidents

---

🔄 Migration and Integration

Migrating to Reverse Proxy Authentication

From Standard Authentication

1. Set up reverse proxy with authentication
2. Test with pilot users to verify configuration
3. Enable reverse proxy auth in CWA with auto-creation
4. Migrate user authentication to proxy system
5. Disable standard login once fully migrated (optional)

From OAuth Authentication

1. Configure reverse proxy to work with existing OAuth provider
2. Enable both authentication methods during transition
3. Test user experience with both authentication paths
4. Gradually transition users to reverse proxy path
5. Consolidate to single authentication method when ready

Integration with Existing Systems

Compatible Authentication Systems:

• Authelia: Full-featured authentication gateway
• Authentik: Modern identity provider with proxy support
• Nginx Auth Module: Simple authentication integration
• Traefik ForwardAuth: Middleware-based authentication
• Apache mod_auth: Apache-based authentication modules
• Custom Solutions: Any system that can forward authentication headers

---

📊 Monitoring and Maintenance

Authentication Monitoring

Monitor these key metrics:

• Authentication Success Rate: Track successful vs failed authentications
• User Creation Rate: Monitor auto-created user accounts
• Header Validation Errors: Watch for malformed or missing headers
• Proxy Connectivity: Ensure consistent proxy-to-CWA communication

Log Analysis

Key log entries to monitor:

• Reverse proxy authentication successful for user: [username]
• Auto-created user from reverse proxy: [username]
• Reverse proxy authentication failed: missing header
• User creation from reverse proxy failed: [reason]

Maintenance Tasks

Regular maintenance activities:

• Review auto-created accounts: Audit new user accounts for appropriateness
• Clean up test accounts: Remove accounts created during testing
• Update proxy configuration: Keep authentication system configurations current
• Security audits: Regular reviews of proxy and CWA security configurations

---

📝 Changelog & Updates

Recent Enhancements (v3.2+)

• ✅ Auto-User Creation: Configurable automatic account creation from reverse proxy headers
• ✅ Enhanced Security Validation: Built-in configuration validation with security warnings
• ✅ Default Permissions Inheritance: New users inherit all default configuration settings
• ✅ Improved Error Handling: Better error messages and logging for troubleshooting
• ✅ Admin UI Integration: Streamlined configuration interface with help text
• ✅ Comprehensive Logging: Detailed authentication and user creation audit trail

Future Planned Features

• 🔄 Group Header Support: Role assignment based on reverse proxy group headers
• 🔄 Multiple Header Authentication: Support for multiple authentication headers
• 🔄 Session Management: Enhanced session timeout and security controls
• 🔄 Advanced User Mapping: Custom user attribute mapping from proxy headers

---

🆘 Support & Resources

Getting Help

1. Check Configuration: Verify both proxy and CWA settings are correct
2. Review Logs: Enable debug logging and check both proxy and CWA logs
3. Test Independently: Test proxy authentication separately from CWA integration
4. Community Support: Join our Discord for help
5. GitHub Issues: Report bugs or request features on GitHub

Useful Resources

• Authelia Documentation
• Authentik Documentation
• Traefik ForwardAuth Middleware
• Nginx Auth Request Module

Testing Tools

• curl: Command-line tool for testing HTTP headers
• Browser Developer Tools: Inspect request headers in real-time
• Proxy Logs: Monitor proxy access and authentication logs
• CWA Debug Logs: Enable debug logging for detailed authentication flow

---

This documentation covers CWA's reverse proxy authentication implementation. For additional help, please visit our Discord community or check the GitHub repository.