django-cors-headers Documentation

CORS and CSRF are separate mechanisms. django-cors-headers does not automatically exempt sites from Django's Referer checking on secure requests. To allow cross-site requests that include CSRF protection, you must also add the allowed origins to Django's CSRF_TRUSTED_ORIGINS setting.

Example configuration:

CORS_ALLOWED_ORIGINS = [
    "https://read-only.example.com",
    "https://read-and-write.example.com",
]

CSRF_TRUSTED_ORIGINS = [
    "https://read-and-write.example.com",
]

Install the package using pip:

python -m pip install django-cors-headers

To use django-cors-headers, you must add it to your INSTALLED_APPS and add CorsMiddleware to your MIDDLEWARE setting.

Important: CorsMiddleware should be placed as high as possible in the MIDDLEWARE list, specifically before any middleware that generates responses (like django.middleware.common.CommonMiddleware or WhiteNoiseMiddleware).

INSTALLED_APPS = [
    ...,
    "corsheaders",
    ...,
]

MIDDLEWARE = [
    ...,
    "corsheaders.middleware.CorsMiddleware",
    "django.middleware.common.CommonMiddleware",
    ...,
]

To ensure signal handlers are properly connected when Django starts, import your handlers within the ready() method of your AppConfig class.

# myapp/apps.py
from django.apps import AppConfig


class MyAppConfig(AppConfig):
    name = "myapp"

    def ready(self):
        # Makes sure all signal handlers are connected
        from myapp import handlers  # noqa

You must set at least one of the following three settings to control which origins are authorized to make cross-site HTTP requests:

1. CORS_ALLOWED_ORIGINS: A list of specific origins (URI scheme + hostname + port). Supports special values 'null' and 'file://'.
2. CORS_ALLOWED_ORIGIN_REGEXES: A list of regexes to match origins. Useful for large numbers of subdomains.
3. CORS_ALLOW_ALL_ORIGINS: A boolean. If True, all origins are allowed. Warning: This can be dangerous as it allows any website to make requests to your server.

# Using specific origins
CORS_ALLOWED_ORIGINS = [
    "https://example.com",
    "https://sub.example.com",
    "http://localhost:8080",
    "http://127.0.0.1:9000",
]

# Using regexes
CORS_ALLOWED_ORIGIN_REGEXES = [
    r"^https://\w+\.example\.com$",
]

# Allowing everything (dangerous)
CORS_ALLOW_ALL_ORIGINS = True

Settings for handling cookies and private network requests.

• CORS_ALLOW_CREDENTIALS: If True, cookies will be allowed in cross-site requests (sets Access-Control-Allow-Credentials). Defaults to False. Note: If using Django sessions, you may need to set SESSION_COOKIE_SAMESITE = 'None' in your Django settings.
• CORS_ALLOW_PRIVATE_NETWORK: If True, allows requests from sites on "public" IPs to this server on a "private" IP. This handles the access-control-request-private-network header.

To enable CORS support in your Django application, add corsheaders.middleware.CorsMiddleware to your MIDDLEWARE setting in settings.py.

Note: It is recommended to place CorsMiddleware as high as possible in the MIDDLEWARE list, specifically before CommonMiddleware.

You can use the check_request_enabled signal to allow all origins to access a specific subset of URLs (e.g., an API) while maintaining strict CORS_ALLOWED_ORIGINS for the rest of the application.

1. Define your trusted origins in CORS_ALLOWED_ORIGINS for general access.
2. Create a signal handler that returns True if the request.path matches your target subset.

# myapp/handlers.py
from corsheaders.signals import check_request_enabled


def cors_allow_api_to_everyone(sender, request, **kwargs):
    return request.path.startswith("/api/")


check_request_enabled.connect(cors_allow_api_to_everyone)

If standard configuration is insufficient, you can use the check_request_enabled Django signal to implement custom logic for allowing requests. If any handler connected to this signal returns a truthy value, the request is allowed.

Important: Use **kwargs in your handler signature to ensure compatibility with future updates to the signal arguments.

To use this, connect a handler to corsheaders.signals.check_request_enabled and ensure the connection is made during the Django app's ready() method.

# myapp/handlers.py
from corsheaders.signals import check_request_enabled
from myapp.models import MySite


def cors_allow_mysites(sender, request, **kwargs):
    return MySite.objects.filter(host=request.headers["origin"]).exists()


check_request_enabled.connect(cors_allow_mysites)

Optional settings to restrict which URLs and HTTP methods receive CORS headers.

• CORS_URLS_REGEX: A regex that restricts the URLs for which CORS headers are sent. Defaults to r'^.*$' (all URLs).
• CORS_ALLOW_METHODS: A list of allowed HTTP verbs. Defaults to DELETE, GET, OPTIONS, PATCH, POST, PUT. You can extend the defaults using corsheaders.defaults.default_methods.

# Restrict CORS to API paths
CORS_URLS_REGEX = r"^/api/.*$"

# Extend default allowed methods
from corsheaders.defaults import default_methods
CORS_ALLOW_METHODS = (
    *default_methods,
    "POKE",
)