CORS on Caddyserver version 1

Quick Start

To add CORS authorization to the header using Caddy 1, add the following line inside your Caddyfile:

cors

Configuration Examples

Development Only (Open CORS)

Use this only for development and testing. DO NOT use in production.

# DEVELOPMENT ONLY - Allows all origins
# DO NOT use in production
example.com {
  cors
  # Your other directives...
}

Production (Secure Configuration)

For production environments, always specify allowed origins explicitly and enable credentials if needed:

# PRODUCTION - Secure configuration
example.com {
  # Allow specific origins only
  cors / {
    origin            https://example.com
    origin            https://app.example.com
    methods           GET,POST,PUT,DELETE,OPTIONS
    allowed_headers   Content-Type,Authorization,X-Requested-With
    exposed_headers   Content-Length,X-Custom-Header
    allow_credentials true
    max_age           86400
  }

  # Your other directives...
  proxy / localhost:8080
}

Path-Specific CORS

Apply different CORS policies to different paths:

example.com {
  # Public endpoints - no CORS restrictions
  cors /public {
    origin *
  }

  # Authenticated API - strict CORS
  cors /api {
    origin            https://example.com
    allow_credentials true
    methods           GET,POST,PUT,DELETE
    allowed_headers   Content-Type,Authorization
    max_age           3600
  }

  # Your backend
  proxy / localhost:8080
}

Configuration Parameters

Choosing the Right Configuration

Use Simple cors When:

• Working in a development/testing environment only
• Building a completely public API with no sensitive data
• Resources are safe for any website to access

Use Full Configuration When:

• Running in production environment
• Building authenticated or sensitive APIs
• Need to control which sites can access your API
• Using cookies or authentication headers

Important Notes

• Credentials and Origins: When allow_credentials is true, you MUST specify exact origins (cannot use wildcard *)
• Automatic Features: Caddy's CORS middleware automatically handles:
  • OPTIONS preflight requests
  • Vary: Origin header for proper caching
  • Header validation and credentials checking
• HTTPS Best Practice: Always use HTTPS origins in production (https://) rather than HTTP (http://) for security

Troubleshooting

CORS errors despite configuration:

• Verify Caddyfile syntax has no errors on startup
• Check that the cors directive is in the correct block
• Ensure HTTPS is used for origins if your site uses HTTPS

Preflight failing:

• Verify all required methods are listed in methods
• Check that headers match exactly in allowed_headers
• Confirm origin exactly matches (including protocol)

Credentials not working:

• Set allow_credentials true
• Cannot use wildcard (*) origin with credentials
• Ensure frontend sends credentials: 'include' in fetch requests

Upgrading to Caddy v2

Caddy v2 offers better performance, improved configuration, and active security updates. Note that v2 uses different syntax (the header directive instead of cors middleware). See the Caddy v2 CORS Configuration page for current syntax, or consult the Caddy v1 to v2 Migration Guide.

Testing Your CORS Configuration

For comprehensive testing instructions including curl commands, browser DevTools usage, and troubleshooting common CORS errors, see the CORS Testing Guide.

Additional Resources

• Caddy v1 CORS Documentation (archived)
• Caddy v2 Documentation
• Caddy v1 to v2 Migration Guide
• MDN Web Docs: CORS