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/

Setup

Install by downloading the source and running:

python setup.py install

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 the 304 not-modified responses, causing errors in some browsers.

Configuration

Add 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

Default:

    CORS_ORIGIN_ALLOW_ALL = False

CORS_ORIGIN_WHITELIST: specify a list of origin hostnames that are authorized to make a cross-site HTTP request

Example:

    CORS_ORIGIN_WHITELIST = (
        'google.com',
        'hostname.example.com'
    )


Default:

    CORS_ORIGIN_WHITELIST = ()

CORS_ORIGIN_REGEX_WHITELIST: specify a regex list of origin hostnames that are authorized to make a cross-site HTTP request; Useful when you have a large amount of subdomains for instance.

Example:

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


Default:

    CORS_ORIGIN_REGEX_WHITELIST = ()

You may optionally specify these options in settings.py to override the defaults. Defaults are shown below:

CORS_URLS_REGEX: specify a URL regex for which to enable the sending of CORS headers; Useful when you only want to enable CORS for specific URLs, e. g. for a REST API under /api/.

Example:

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

Default:

    CORS_URLS_REGEX = '^.*$'

CORS_ALLOW_METHODS: specify the allowed HTTP methods that can be used when making the actual request

Default:

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

CORS_ALLOW_HEADERS: specify which non-standard HTTP headers can be used when making the actual request

Default:

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

CORS_EXPOSE_HEADERS: specify which HTTP headers are to be exposed to the browser

Default:

    CORS_EXPOSE_HEADERS = ()

CORS_PREFLIGHT_MAX_AGE: specify the number of seconds a client/browser can cache the preflight response

Note: A preflight request is an extra request that is made when making a "not-so-simple" request (eg. content-type is not application/x-www-form-urlencoded) to determine what requests the server actually accepts. Read more about it here: [http://www.html5rocks.com/en/tutorials/cors/](http://www.html5rocks.com/en/tutorials/cors/)

Default:

    CORS_PREFLIGHT_MAX_AGE = 86400

CORS_ALLOW_CREDENTIALS: specify whether or not cookies are allowed to be included in cross-site HTTP requests (CORS).

Default:

    CORS_ALLOW_CREDENTIALS = False

CORS_REPLACE_HTTPS_REFERER: specify whether to replace the HTTP_REFERER header if CORS checks pass so that CSRF django middleware checks will work with https

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

Default:

    CORS_REPLACE_HTTPS_REFERER = False

CORS_ENDPOINT_OVERRIDES: a list of (regex, override) pairs that override settings for certain URLs.

Example:

    CORS_ENDPOINT_OVERRIDES = [
        (r'/api/user/.*$', {
            'CORS_ORIGIN_WHITELIST': ['https://secure.mydomain.com'],
        }),
        (r'/api/public/.*$', {
            'CORS_ORIGIN_ALLOW_ALL': True,
        }),
    ]

Default:

    CORS_ENDPOINT_OVERRIDES = []