# documentación de Django - 5.2.8

# Cómo utilizar la protección CSRF de Django

Para aprovechar la protección CSRF en sus vistas, siga estos pasos:

1. El middleware CSRF está activado de forma predeterminada en la configuración `MIDDLEWARE`. Si redefine esa configuración, recuerde que `'django.middleware.csrf.CsrfViewMiddleware'` debe aparecer antes de cualquier middleware de vista que asuma que se han tratado los ataques CSRF.

   Si lo desactivó, lo cual no se recomienda, puede usar `csrf_protect()` en vistas particulares que desee proteger (ver más abajo).

2. En cualquier plantilla que utilice un formulario POST, utilice la etiqueta `csrf_token` dentro del elemento `<form>` si el formulario es para una dirección URL interna, por ejemplo:

       <form method="post">{% csrf_token %}

   Esto no debe hacerse para los formularios POST que se dirigen a URL externas, ya que eso provocaría que se filtrara el token CSRF, lo que provocaría una vulnerabilidad.

3. En las funciones de vista correspondientes, asegúrese de que `RequestContext` se utiliza para representar la respuesta de modo que `{% csrf_token %}` funcione correctamente. Si está utilizando la función `render()`, vistas genéricas o aplicaciones contrib, ya está cubierto, ya que todas usan `RequestContext`.

## Uso de la protección CSRF con AJAX

Si bien el método anterior se puede usar para solicitudes AJAX POST, tiene algunos inconvenientes: debe recordar pasar el token CSRF como datos POST con cada solicitud POST. Por esta razón, existe un método alternativo: en cada XMLHttpRequest, establezca un encabezado personalizado `X-CSRFToken` (como se especifica en ajuste `CSRF_HEADER_NAME`) el valor del valor del token CSRF. Esto suele ser más fácil porque muchos marcos de JavaScript proporcionan ganchos que permiten establecer encabezados en cada solicitud.

Primero, debe obtener el token CSRF. Cómo hacerlo depende de si la configuración `CSRF_USE_SESSIONS` y `CSRF_COOKIE_HTTPONLY` está habilitada o no.

### Obtener el token si `CSRF_USE_SESSIONS` y `CSRF_COOKIE_HTTPONLY` son `False`

La fuente recomendada para el token es la cookie `csrftoken`, que se establecerá si ha habilitado la protección CSRF para sus vistas como se describe anteriormente.

La cookie de token CSRF se denomina `csrftoken` de forma predeterminada, pero puede controlar el nombre de la cookie a través de la configuración `CSRF_COOKIE_NAME`.

Puede obtener el token así:

    function getCookie(name) {
        let cookieValue = null;
        if (document.cookie && document.cookie !== '') {
            const cookies = document.cookie.split(';');
            for (let i = 0; i < cookies.length; i++) {
                const cookie = cookies[i].trim();
                // Does this cookie string begin with the name we want?
                if (cookie.substring(0, name.length + 1) === (name + '=')) {
                    cookieValue = decodeURIComponent(cookie.substring(name.length + 1));
                    break;
                }
            }
        }
        return cookieValue;
    }
    const csrftoken = getCookie('csrftoken');

El código anterior podría simplificarse utilizando la biblioteca de cookies de JavaScript para reemplazar `getCookie`:

    const csrftoken = Cookies.get('csrftoken');

Nota

El token CSRF también está presente en el DOM en forma enmascarada, pero solo si se incluye explícitamente usando `csrf_token` en una plantilla. La cookie contiene el token canónico y desenmascarado. `CsrfViewMiddleware` aceptará cualquiera de los dos. Sin embargo, para protegerse contra los ataques BREACH, se recomienda usar un token enmascarado.

Advertencia

Si su vista no representa una plantilla que contiene la etiqueta de plantilla `csrf_token`, es posible que Django no establezca la cookie de token CSRF. Esto es común en los casos en que los formularios se agregan dinámicamente a la página. Para abordar este caso, Django proporciona un decorador de vistas que fuerza la configuración de la cookie: `ensure_csrf_cookie()`.

### Obtener el token si `CSRF_USE_SESSIONS` o `CSRF_COOKIE_HTTPONLY` es `True`

Si activa `CSRF_USE_SESSIONS` o `CSRF_COOKIE_HTTPONLY`, debe incluir el token CSRF en su HTML y leer el token del DOM con JavaScript:

    {% csrf_token %}
    <script>
    const csrftoken = document.querySelector('[name=csrfmiddlewaretoken]').value;
    </script>

### Configuración del token en la solicitud de AJAX

Finalmente, deberá configurar el encabezado en su solicitud AJAX. Usando la API fetch():

    const request = new Request(
        /* URL */,
        {
            method: 'POST',
            headers: {'X-CSRFToken': csrftoken},
            mode: 'same-origin' // Do not send CSRF token to another domain.
        }
    );
    fetch(request).then(function(response) {
        // ...
    });

## Usando protección CSRF en plantillas de Jinja2

El backend de plantillas `Jinja2` de Django agrega `{{ csrf_input }}` al contexto de todas las plantillas, lo cual es equivalente a `{% csrf_token %}` en el lenguaje de plantillas de Django. Por ejemplo:

    <form method="post">{{ csrf_input }}

## Usando el método decorador

En lugar de agregar `CsrfViewMiddleware` como una protección general, puedes usar el decorador `csrf_protect()`, que tiene exactamente la misma funcionalidad, en vistas específicas que necesiten la protección. Debe ser utilizado tanto en vistas que insertan el token CSRF en la salida, como en aquellas que aceptan los datos de formulario POST. (A menudo, estas son la misma función de vista, pero no siempre).

El uso del decorador por sí solo no se recomienda, ya que si olvida usarlo, tendrá una vulnerabilidad de seguridad. La estrategia de “cinturón y tirantes” de usar ambos está bien, e incurrirá en un costo mínimo.

## Manejo de solicitudes rechazadas

Por defecto, se envía una respuesta “403 Forbidden” al usuario si una solicitud entrante no supera las comprobaciones realizadas por CsrfViewMiddleware. Esto normalmente solo debería observarse cuando hay una verdadera falsificación de solicitud entre sitios, o cuando, debido a un error de programación, el token CSRF no se ha incluido con un formulario POST.

La página de error, sin embargo, no es muy amigable, por lo que es posible que desee proporcionar su propia vista para manejar esta condición. Para hacer esto, establezca la configuración `CSRF_FAILURE_VIEW`.

Los fallos de CSRF se registran como advertencias en el logger :ref:django.security.csrf.<django-security-logger>

## Uso de la protección CSRF con almacenamiento en caché

Si la etiqueta de plantilla `csrf_token` esta siendo usada por otra plantilla (o la función `get_token` se llama de otra manera), `CsrfViewMiddleware` añadirá una cookie y un encabezado `Vary: Cookie` a la respuesta. Esto significa que el middleware funcionara bien con el caché si se usa según las instrucciones (`UpdateCacheMiddleware` va antes que los demás middleware).

Sin embargo, si utilizas decoradores de caché en vistas individuales, el middleware CSRF aún no habrá podido establecer el encabezado Vary o la cookie CSRF, y la respuesta se almacenará en caché sin ninguno de ellos. En este caso, en cualquier vista que requiera que se inserte un token CSRF, debes usar primero el decorador `django.views.decorators.csrf.csrf_protect()`

    from django.views.decorators.cache import cache_page
    from django.views.decorators.csrf import csrf_protect

    @cache_page(60 * 15)
    @csrf_protect
    def my_view(request): ...

Si esta usando vistas basadas en clases, puede consultar Decorating class-based views.

## Pruebas y protección CSRF

El `CsrfViewMiddleware` suele ser un gran obstáculo para probar las funciones de vista, debido a la necesidad del token CSRF que debe enviarse con cada solicitud POST. Por esta razón, el cliente HTTP de Django para pruebas se ha modificado para establecer una bandera en las solicitudes que relaja el middleware y el decorador `csrf_protect`, de modo que ya no rechacen las solicitudes. En todos los demás aspectos (por ejemplo, enviar cookies, etc.), se comportan igual.

Si, por alguna razón, deseas que el cliente de pruebas realice comprobaciones CSRF, puedes crear una instancia del cliente de pruebas que aplique estas comprobaciones:

    >>> from django.test import Client
    >>> csrf_client = Client(enforce_csrf_checks=True)

## Casos extremos

Ciertas vistas pueden tener requisitos inusuales que significan que no se ajustan al patrón normal contemplado aquí. Varios utilitarios pueden ser útiles en estas situaciones. Los escenarios en los que podrían ser necesarios se describen en la siguiente sección.

### Deshabilitar la protección CSRF solo para algunas vistas

La mayoría de las vistas requieren protección CSRF, pero algunas no.

Solución: antes de deshabilitar el middleware y aplicar `csrf_protect` a todas las views que lo necesite, habilita el middleware y usa `csrf_exempt()`.

### Configurar el token cuando `CsrfViewMiddleware.process_view()` no está en uso

Hay casos cuando `CsrfViewMiddleware.process_view` puede no haberse ejecutado antes de la ejecución de tu view - por ejemplo los handlers 404 y 500 - pero aún así necesitas el token CSRF en un formulario.

Solución: usa `requires_csrf_token()`

### Incluir el token CSRF en una view sin proteger

Puede que haya algunas views que estén desprotegidas y hayan sido eximidas por `csrf_exempt`, pero aún así necesita incluir el Token CSRF.

Solución: usa `csrf_exempt()` seguido de `requires_csrf_token()`. (es decir, `requires_csrf_token` debería ser el decorador mas interno).

### Proteger una view para un solo path

Una view necesita protección CSRF bajo un solo conjunto de condiciones y no debe tenerlo por todo el resto del tiempo.

Solución: usa `csrf_exempt()` para toda la función view y `csrf_protect()` para el path dentro de él que necesita protección. Ejemplo:

    from django.views.decorators.csrf import csrf_exempt, csrf_protect

    @csrf_exempt
    def my_view(request):
        @csrf_protect
        def protected_path(request):
            do_something()

        if some_condition():
            return protected_path(request)
        else:
            do_something_else()

### Proteger una página que usa AJAX sin un formulario HTML

Una página hace una PBULICACIÓN vía AJAX y la página no tiene un formulario HTML con un `csrf_token` eso provocaría que la cookie CSRF requerida sea enviada.

Solución: usa `ensure_csrf_cookie()` en la view que envía la página.

## Protección CSRF en aplicaciones reutilizables

Porque es posible para el desarrollador apagar el `CsrfViewMiddleware`, todas las views importantes de apps contrib usa el decorador `csrf_protect` para garantizar la seguridad de estas aplicaciones contra el CSRF. Se recomienda a los desarrolladores de las apps reutilizables que quieran la misma garantía también utilicen el decorador `csrf_protect` en sus views.