Skip to main content

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

Project description

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/

https://travis-ci.org/ottoyiu/django-cors-headers.png?branch=master

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-cors-headers-1.2.2.tar.gz (9.6 kB view hashes)

Uploaded Source

Built Distribution

django_cors_headers-1.2.2-py2.py3-none-any.whl (14.1 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page