===========================================
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.