mirror of
https://github.com/django/django.git
synced 2025-08-03 02:23:12 +00:00
d63241ebc7
This initial work adds a pair of settings to configure specific CSP directives for enforcing or reporting policy violations, a new `django.middleware.csp.ContentSecurityPolicyMiddleware` to apply the appropriate headers to responses, and a context processor to support CSP nonces in templates for safely inlining assets. Relevant documentation has been added for the 6.0 release notes, security overview, a new how-to page, and a dedicated reference section. Thanks to the multiple reviewers for their precise and valuable feedback. Co-authored-by: Natalia <124304+nessita@users.noreply.github.com>
100 lines
3.2 KiB
Text
100 lines
3.2 KiB
Text
===========================================
|
|
How to use Django's Content Security Policy
|
|
===========================================
|
|
|
|
.. _csp-config:
|
|
|
|
Basic config
|
|
============
|
|
|
|
To enable Content Security Policy (CSP) in your Django project:
|
|
|
|
1. Add the CSP middleware to your :setting:`MIDDLEWARE` setting::
|
|
|
|
MIDDLEWARE = [
|
|
# ...
|
|
"django.middleware.csp.ContentSecurityPolicyMiddleware",
|
|
# ...
|
|
]
|
|
|
|
2. Configure the CSP policies in your ``settings.py`` using either
|
|
:setting:`SECURE_CSP` or :setting:`SECURE_CSP_REPORT_ONLY` (or both). The
|
|
:ref:`CSP Settings docs <csp-settings>` provide more details about the
|
|
differences between these two::
|
|
|
|
from django.utils.csp import CSP
|
|
|
|
# To enforce a CSP policy:
|
|
SECURE_CSP = {
|
|
"default-src": [CSP.SELF],
|
|
# Add more directives to be enforced.
|
|
}
|
|
|
|
# Or for report-only mode:
|
|
SECURE_CSP_REPORT_ONLY = {
|
|
"default-src": [CSP.SELF],
|
|
# Add more directives as needed.
|
|
"report-uri": "/path/to/reports-endpoint/",
|
|
}
|
|
|
|
.. _csp-nonce-config:
|
|
|
|
Nonce config
|
|
============
|
|
|
|
To use nonces in your CSP policy, beside the basic config, you need to:
|
|
|
|
1. Include the :attr:`~django.utils.csp.CSP.NONCE` placeholder value in the CSP
|
|
settings. This only applies to ``script-src`` or ``style-src`` directives::
|
|
|
|
from django.utils.csp import CSP
|
|
|
|
SECURE_CSP = {
|
|
"default-src": [CSP.SELF],
|
|
# Allow self-hosted scripts and script tags with matching `nonce` attr.
|
|
"script-src": [CSP.SELF, CSP.NONCE],
|
|
# Example of the less secure 'unsafe-inline' option.
|
|
"style-src": [CSP.SELF, CSP.UNSAFE_INLINE],
|
|
}
|
|
|
|
2. Add the :func:`~django.template.context_processors.csp` context processor to
|
|
your :setting:`TEMPLATES` setting. This makes the generated nonce value
|
|
available in the Django templates as the ``csp_nonce`` context variable::
|
|
|
|
TEMPLATES = [
|
|
{
|
|
"BACKEND": "django.template.backends.django.DjangoTemplates",
|
|
"OPTIONS": {
|
|
"context_processors": [
|
|
# ...
|
|
"django.template.context_processors.csp",
|
|
],
|
|
},
|
|
},
|
|
]
|
|
|
|
3. In your templates, add the ``nonce`` attribute to the relevant inline
|
|
``<style>`` or ``<script>`` tags, using the ``csp_nonce`` context variable:
|
|
|
|
.. code-block:: html+django
|
|
|
|
<style nonce="{{ csp_nonce }}">
|
|
/* These inline styles will be allowed. */
|
|
</style>
|
|
|
|
<script nonce="{{ csp_nonce }}">
|
|
// This inline JavaScript will be allowed.
|
|
</script>
|
|
|
|
.. admonition:: Caching and Nonce Reuse
|
|
|
|
The :class:`~django.middleware.csp.ContentSecurityPolicyMiddleware`
|
|
automatically handles generating a unique nonce and inserting the
|
|
appropriate ``nonce-<value>`` source expression into the
|
|
``Content-Security-Policy`` (or ``Content-Security-Policy-Report-Only``)
|
|
header when the nonce is used in a template.
|
|
|
|
To ensure correct behavior, make sure both the HTML and the header are
|
|
generated within the same request and not served from cache. See the
|
|
reference documentation on :ref:`csp-nonce` for implementation details and
|
|
important caching considerations.
|