django-cors-headers 1.2.2

django-cors-headers is a Django application for handling the server headers required for Cross-Origin Resource Sharing (CORS).

django-cors-headers

A Django App that adds CORS (Cross-Origin Resource Sharing) headers to responses.

Although JSON-P is useful, it is strictly limited to GET requests. CORS builds on top of XmlHttpRequest to allow developers to make cross-domain requests, similar to same-domain requests. Read more about it here: http://www.html5rocks.com/en/tutorials/cors/

Requirements

Tested with all combinations of:

• Python: 2.7, 3.5

• Django: 1.8, 1.9, 1.10

Setup

Install from pip:

pip install django-cors-headers

and then add it to your installed apps:

INSTALLED_APPS = (
    ...
    'corsheaders',
    ...
)

You will also need to add a middleware class to listen in on responses:

MIDDLEWARE_CLASSES = [
    ...
    'corsheaders.middleware.CorsMiddleware',
    'django.middleware.common.CommonMiddleware',
    ...
]

Note that CorsMiddleware needs to come before Django’s CommonMiddleware if you are using Django’s USE_ETAGS = True setting, otherwise the CORS headers will be lost from 304 Not-Modified responses, causing errors in some browsers.

Configuration

Configure the middleware’s behaviour in your Django settings. You must add the hosts that are allowed to do cross-site requests to CORS_ORIGIN_WHITELIST, or set CORS_ORIGIN_ALLOW_ALL to True to allow all hosts.

CORS_ORIGIN_ALLOW_ALL

If True, the whitelist will not be used and all origins will be accepted. Defaults to False.

CORS_ORIGIN_WHITELIST

A list of origin hostnames that are authorized to make cross-site HTTP requests. Defaults to [].

Example:

CORS_ORIGIN_WHITELIST = (
    'google.com',
    'hostname.example.com',
    'localhost:8000',
    '127.0.0.1:9000'
)

CORS_ORIGIN_REGEX_WHITELIST

A list of regexes that match origin regex list of origin hostnames that are authorized to make cross-site HTTP requests. Defaults to []. Useful when CORS_ORIGIN_WHITELIST is impractical, such as when you have a large number of subdomains.

Example:

CORS_ORIGIN_REGEX_WHITELIST = ('^(https?://)?(\w+\.)?google\.com$', )

---

The following are optional settings, for which the defaults probably suffice.

CORS_URLS_REGEX

A regex which restricts the URL’s for which the CORS headers will be sent. Defaults to r'^.*$', i.e. match all URL’s. Useful when you only need CORS on a part of your site, e.g. an API at /api/.

Example:

CORS_URLS_REGEX = r'^/api/.*$'

CORS_ALLOW_METHODS

A list of HTTP verbs that are allowed for the actual request. Defaults to:

CORS_ALLOW_METHODS = (
    'GET',
    'POST',
    'PUT',
    'PATCH',
    'DELETE',
    'OPTIONS',
)

The default can be imported as corsheaders.defaults.default_methods so you can just extend it with your custom methods. This allows you to keep up to date with any future changes. For example:

from corsheaders.defaults import default_methods

CORS_ALLOW_METHODS = default_methods + (
    'POKE',
)

CORS_ALLOW_HEADERS

The list of non-standard HTTP headers that can be used when making the actual request. Defaults to:

CORS_ALLOW_HEADERS = (
    'x-requested-with',
    'content-type',
    'accept',
    'origin',
    'authorization',
    'x-csrftoken',
    'user-agent',
    'accept-encoding',
)

The default can be imported as corsheaders.defaults.default_headers so you can extend it with your custom headers. This allows you to keep up to date with any future changes. For example:

from corsheaders.defaults import default_headers

CORS_ALLOW_HEADERS = default_headers + (
    'my-custom-header',
)

CORS_EXPOSE_HEADERS

The list of HTTP headers that are to be exposed to the browser. Defaults to [].

CORS_PREFLIGHT_MAX_AGE

The number of seconds a client/browser can cache the preflight response. Defaults to 86400.

Note: A preflight request is an extra request that is made when making a “not-so-simple” request (e.g. Content-Type is not application/x-www-form-urlencoded) to determine what requests the server actually accepts. Read more about it in the HTML 5 Rocks CORS tutorial.

CORS_ALLOW_CREDENTIALS

If True, cookies will be allowed to be included in cross-site HTTP requests. Defaults to False.

CORS_REPLACE_HTTPS_REFERER

If True, the HTTP_REFERER header will get replaced when CORS checks pass, so that the Django CSRF middleware checks work with HTTPS. Defaults to False.

Note: With this feature enabled, you also need to add corsheaders.middleware.CorsPostCsrfMiddleware after django.middleware.csrf.CsrfViewMiddleware in your MIDDLEWARE_CLASSES to undo the header replacement.

CORS_MODEL

If set, this should be the path to a model to look up allowed origins, in the form app.modelname. Defaults to None.

The model should have one field, a CharField called cors, that in each instance contains an allowed origin. django-cors-headers supplies such a model for you; set the setting to corsheaders.CorsModel to use it.

Signals

If you have a use case that requires more than just the above configuration, you can attach code to check if a given request should be allowed. For example, this can be used to read the list of origins you allow from a model. Attach any number of handlers to the check_request_enabled Django signal, which provides the request argument (use **kwargs in your handler to protect against any future arguments being added). If any handler attached to the signal returns a truthy value, the request will be allowed.

For example you might define a handler like this:

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

from .models import MySite

def cors_allow_mysites(sender, request, **kwargs):
    return MySite.objects.filter(host=request.host).exists()

check_request_enabled.connect(cors_allow_mysites)

Then connect it at app ready time using a Django AppConfig:

# myapp/__init__.py

default_app_config = 'myapp.apps.MyAppConfig'

# myapp/apps.py

from django.apps import AppConfig

class MyAppConfig(AppConfig):
    name = 'myapp'

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

A common use case for the signal is to allow all origins to access a subset of URL’s, whilst allowing a normal set of origins to access all URL’s. This isn’t possible using just the normal configuration, but it can be achieved with a signal handler.

First set CORS_ORIGIN_WHITELIST to the list of trusted origins that are allowed to access every URL, and then add a handler to check_request_enabled to allow CORS regardless of the origin for the unrestricted URL’s. For example:

# 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)

Credits

django-cors-headers was created by Otto Yiu (@ottoyiu) and has been worked on by 25+ contributors. Thanks to every contributor, and if you want to get involved please don’t hesitate to make a pull request.

History

Pending

• New release notes go here.

1.2.2 (2016-10-05)

• Add CorsModel.__str__ for human-readable text

• Add a signal that allows you to add code for more intricate control over when CORS headers are added.

1.2.1 (2016-09-30)

• Made settings dynamically respond to changes, and which allows you to import the defaults for headers and methods in order to extend them.

1.2.0 (2016-09-28)

• Drop Python 2.6 support.

• Drop Django 1.3-1.7 support, as they are no longer supported.

• Confirmed Django 1.9 support (no changes outside of tests were necessary).

• Added Django 1.10 support.

• Package as a universal wheel.

1.1.0 (2014-12-15)

• django-cors-header now supports Django 1.8 with its new application loading system! Thanks @jpadilla for making this possible and sorry for the delay in making a release.

1.0.0 (2014-12-13)

django-cors-headers is all grown-up :) Since it’s been used in production for many many deployments, I think it’s time we mark this as a stable release.

• Switching this middleware versioning over to semantic versioning

• #46 add user-agent and accept-encoding default headers

• #45 pep-8 this big boy up

0.13 (2014-08-14)

• Add support for Python 3

• Updated tests

• Improved docuemntation

• Small bugfixes

0.12 (2013-09-24)

• Added an option to selectively enable CORS only for specific URLs

0.11 (2013-09-24)

• Added the ability to specify a regex for whitelisting many origin hostnames at once

0.10 (2013-09-05)

• Introduced port distinction for origin checking

• Use urlparse for Python 3 support

• Added testcases to project

0.06 (2013-02-18)

• Add support for exposed response headers

0.05 (2013-01-26)

• Fixed middleware to ensure correct response for CORS preflight requests

0.04 (2013-01-25)

• Add Access-Control-Allow-Credentials control to simple requests

0.03 (2013-01-22)

• Bugfix to repair mismatched default variable names

0.02 (2013-01-19)

• Refactor/pull defaults into separate file

0.01 (2013-01-19)

• Initial release