Traducido por Miguel A. Ponce

documentación de Django - 5.2.15.dev20260527181452

Home | Table of contents | Index | Modules

« previous | up | next »

Cómo utilizar la protección contra ataques CSRF de Django

Para aprovechar la protección contra ataques CSRF en tus vistas, sigue estos pasos:

1. El middleware de CSRF está activado por defecto en el MIDDLEWARE configuración. Si sobreescribes esa configuración, recuerda que 'django.middleware.csrf.CsrfViewMiddleware' debe venir antes de cualquier middleware de vista que asuma que los ataques CSRF han sido resueltos.

   Si lo has desactivado, lo cual no se recomienda, puedes utilizar csrf_protect() en vistas particulares que quieras proteger (ver más abajo).

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

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

   No debes hacer esto con formularios POST que apunten a URLs externas, ya que eso causaría que se filtrara el token CSRF, lo que llevaría a una vulnerabilidad.

3. En las funciones de vistas correspondientes, asegúrate de utilizar RequestContext para renderizar la respuesta para que {% csrf_token %} funcione correctamente. Si estás utilizando la función render(), vistas genericas o aplicaciones contribuyentes, ya estás cubierto ya que estas todas utilizan RequestContext.

Utilizando la protección contra ataques CSRF con AJAX

Si bien el método anterior se puede utilizar para solicitudes POST de AJAX, tiene algunas inconveniencias: debes recordar pasar el token CSRF como datos POST en cada solicitud POST. Por esta razón, hay un método alternativo: en cada XMLHttpRequest, establece una cabecera personalizada X-CSRFToken (como especifica la CSRF_HEADER_NAME configuración) con el valor del token CSRF. Esto a menudo es más fácil porque muchas bibliotecas de JavaScript proporcionan hooks que permiten establecer cabeceras en cada solicitud.

Primero, debes obtener el token CSRF. Cómo hacerlo depende de si las configuraciones CSRF_USE_SESSIONS y CSRF_COOKIE_HTTPONLY están habilitadas o no.

Obtención del 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 has habilitado la protección CSRF en tus vistas tal como se describe arriba.

La cookie del token CSRF se llama csrftoken por defecto, pero puedes controlar el nombre de la cookie mediante la configuración CSRF_COOKIE_NAME.

Puedes obtener el token de esta manera:

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 JavaScript Cookie para reemplazar getCookie.

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

Nota

El token CSRF también está presente en el DOM en forma mascarada, pero solo si se incluye explícitamente mediante csrf_token en una plantilla. La cookie contiene el token canónico y no mascarado. El middleware CsrfViewMiddleware aceptará cualquiera de los dos. Sin embargo, para proteger contra ataques BREACH, se recomienda utilizar un token mascarado.

Advertencia

Si tu vista no está renderizando una plantilla que contenga el csrf_token template tag, Django puede no establecer la cookie del token CSRF. Esto es común en casos donde los formularios se agregan dinámicamente a la página. Para abordar este caso, Django proporciona un decorador de vistas que fuerza el establecimiento de la cookie: ensure_csrf_cookie().

Obtención del token si CSRF_USE_SESSIONS o CSRF_COOKIE_HTTPONLY es True.

Si activas CSRF_USE_SESSIONS o CSRF_COOKIE_HTTPONLY, debes incluir el token CSRF en tu HTML y leer el token del DOM con JavaScript:

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

Establecer el token en la solicitud AJAX.

Finalmente, necesitarás configurar el encabezado en tu solicitud AJAX utilizando 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) {
    // ...
});

La protección CSRF en plantillas Jinja2

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

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

Uso del método decorador

En lugar de agregar CsrfViewMiddleware como protección general, puedes utilizar el decorador csrf_protect(), que tiene la misma funcionalidad exacta, en vistas particulares que necesitan la protección. Debe usarse ambos en vistas que insertan el token CSRF en la salida y en aquellas que aceptan los datos de formulario POST. (Estas son a menudo la misma función de vista, pero no siempre).

El uso del decorador por sí solo no se recomienda, ya que si lo olvidas, tendrás una brecha de seguridad. La estrategia «correa y broches» de usar ambos es aceptable y conlleva un overhead mínimo.

Manejo de solicitudes rechazadas

Por defecto, se envía una respuesta “403 Forbidden” al usuario si la solicitud entrante falla las comprobaciones realizadas por CsrfViewMiddleware. Esto debería verse solo cuando hay una genuina Cross Site Request Forgery o cuando, debido a un error de programación, el token CSRF no ha sido incluido con un formulario POST.

La página de errores, sin embargo, no es muy amigable, por lo que podrías querer proporcionar tu propia vista para manejar esta condición. Para hacer esto, configura la CSRF_FAILURE_VIEW configuración.

Los fallos CSRF se registran como advertencias en el logger django.security.csrf.

Usando la protección contra ataques CSRF

Si se utiliza el etiqueta de plantilla csrf_token (o si se llama la función get_token de alguna otra manera), CsrfViewMiddleware agregará una cookie y un encabezado Vary: Cookie a la respuesta. Esto significa que el middleware funcionará bien con el middleware de caché si se utiliza como se indica (UpdateCacheMiddleware debe ir antes que cualquier otro middleware).

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

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 estás utilizando vistas basadas en clases, puedes referirte a Decorating class-based views.

Pruebas y protección contra ataques CSRF

El CsrfViewMiddleware suele ser un gran obstáculo para las pruebas de funciones de vistas, debido a la necesidad del token CSRF que debe ser enviado con cada solicitud POST. Por esta razón, el cliente HTTP de Django para pruebas ha sido modificado para establecer una bandera en las solicitudes que relaja al middleware y al decorador csrf_protect para 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, quieres que el cliente de pruebas realice comprobaciones CSRF, puedes crear una instancia del cliente de pruebas que impone comprobaciones CSRF:

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

Casos límite

Algunas vistas pueden tener requisitos inusuales que significan que no se ajustan al patrón normal previsto aquí. Un número de utilidades puede ser útil en estas situaciones. Los escenarios en los que podrían ser necesarias se describen en la siguiente sección.

Desactivando la protección CSRF para solo unas pocas vistas

Los textos traducidos manteniendo todas sus etiquetas intactas son:

Solución: en lugar de deshabilitar el middleware y aplicar csrf_protect a todas las vistas que lo necesitan, active el middleware y utilice csrf_exempt().

Establecer el token cuando CsrfViewMiddleware.process_view() no se utiliza

Hay casos en los que CsrfViewMiddleware.process_view puede no haber corrido antes de ejecutar tu vista - 404 y 500 maneadores, por ejemplo - pero todavía necesitas el token CSRF en un formulario.

Solución: utilice requires_csrf_token()

Incluir el token CSRF en una vista no protegida

Es posible que haya algunas vistas que estén desprotegidas y hayan sido eximidas por csrf_exempt, pero todavía necesitan incluir el token CSRF.

Solución: utilice csrf_exempt() seguido de requires_csrf_token(). (es decir, requires_csrf_token debe ser el decorador más interno).

Proteger una vista solo para un camino

Una vista necesita protección CSRF bajo un conjunto de condiciones únicamente y no debe tenerla en el resto del tiempo.

Solución: utilice csrf_exempt() para la función de vista completa, y csrf_protect() para el camino dentro de ella 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()

Protegiendo una página que utiliza AJAX sin un formulario HTML

Una página realiza una solicitud POST mediante AJAX, y la página no tiene un formulario HTML con un csrf_token que causaría que se envíe el cookie CSRF requerido.

Solución: utilice ensure_csrf_cookie() en la vista que envía la página.

Protección CSRF en aplicaciones reutilizables

Dado que es posible que el desarrollador desactive el CsrfViewMiddleware, todas las vistas relevantes en contrib apps utilizan el decorador csrf_protect para asegurar la seguridad de estas aplicaciones contra CSRF. Se recomienda a los desarrolladores de otras aplicaciones reutilizables que quieran las mismas garantías que también utilicen el decorador csrf_protect en sus vistas.

Last update:

may 31, 2026

« previous | up | next »