---
title: "Como usar a proteção CSRF do Django"
version: 6.1
locale: pt-br
source: https://docs.djangoproject.com/pt-br/6.1/howto/csrf/
canonical: https://djangodocs.dev/pt-br/6.1/howto/csrf/
---
# Como usar a proteção CSRF do Django

Para aproveitar das vantagens da proteção CSRF nas suas views, siga estes passos:

1. The CSRF middleware is activated by default in the [`MIDDLEWARE`](/pt-br/6.1/ref/settings/#std-setting-MIDDLEWARE)
   setting. If you override that setting, remember that
   `'django.middleware.csrf.CsrfViewMiddleware'` should come before any view
   middleware that assumes that CSRF attacks have been dealt with.

   Se você o desabilitou, o que não é recomendado, você pode usar [`csrf_protect()`](/pt-br/6.1/ref/csrf/#django.views.decorators.csrf.csrf_protect) em views especifícas que você deseja proteger (veja abaixo).
2. Em qualquer template que usa um formulário POST, use a tag [`csrf_token`](/pt-br/6.1/ref/templates/builtins/#std-templatetag-csrf_token) dentro do `1` elemento se o formulário é para uma URL interna, por exemplo:

   ```html+django
   <form method="post">{% csrf_token %}
   ```

   Isso não deve feito para formulários POST para URLs externas, já que isso causaria o vazamento do token CSRF, levando a uma vulnerabilidade.
3. Nas devidas funções de view, garanta que [`RequestContext`](/pt-br/6.1/ref/templates/api/#django.template.RequestContext) é utilizado para renderizar a resposta, assim `{% csrf_token %}` irá funcionar como o esperado. Se você está usando a função [`render()`](/pt-br/6.1/topics/http/shortcuts/#django.shortcuts.render), views genéricas, ou apps contrib, você não precisa fazer isso, já que todas essas já fazem uso do `RequestContext`.

## Usando a proteção CSRF com AJAX

Mesmo que o método acima possa ser utilizado para requisições POST AJAX, existem algumas incoveniências: você precisa se lembrar de passar o token CSRF nos dados de POST em todas as requisições POST. Por esse motivo existe um método alternativo: Em cada XMLHttpRequest, defina um cabeçalho customizado `X-CSRFToken` (como especificado pela configuração [`CSRF_HEADER_NAME`](/pt-br/6.1/ref/settings/#std-setting-CSRF_HEADER_NAME)) com o valor do token CSRF. Isso geralmente é mais fácil por que muitos frameworks Javascript dão hooks que permitem que cabeçalhos sejam definidos em toda requisição.

Primeiro, você precisa pegar o token CSRF. Como fazer isso depende das configurações [`CSRF_USE_SESSIONS`](/pt-br/6.1/ref/settings/#std-setting-CSRF_USE_SESSIONS) e [`CSRF_COOKIE_HTTPONLY`](/pt-br/6.1/ref/settings/#std-setting-CSRF_COOKIE_HTTPONLY) estarem habilitadas.

### Pegando o token caso [`CSRF_USE_SESSIONS`](/pt-br/6.1/ref/settings/#std-setting-CSRF_USE_SESSIONS) e [`CSRF_COOKIE_HTTPONLY`](/pt-br/6.1/ref/settings/#std-setting-CSRF_COOKIE_HTTPONLY) sejam `False`

A fonte recomendada to token é o cookie `csrftoken`, que estará definido caso você tenha habilitado a proteção CSRF nas suas views como mencionado acima.

O nome do cookie de token CSRF é nomeado `csrftoken` por padrão, mas você pode alterar o nome do cookie na configuração [`CSRF_COOKIE_NAME`](/pt-br/6.1/ref/settings/#std-setting-CSRF_COOKIE_NAME).

Você pode pegar o token desta maneira:

```javascript
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');
```

O código acima pode ser simplificado usando a biblioteca [JavaScript Cookie](https://github.com/js-cookie/js-cookie/) que subsitutui `getCookie`:

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

> **Note**
>
> O token CSRF também está presente na DOM de maneira mascarada, mas apenas se incluso explicitamente utilizando [`csrf_token`](/pt-br/6.1/ref/templates/builtins/#std-templatetag-csrf_token) em um template. O cookie contém o token canónico, não mascarado. O :class:~django.middleware.csrf.CsrfViewMiddleware\` irá aceitar ambos. Porém, para evitar ataques [BREACH](https://www.breachattack.com/), é recomendado utilizar o token mascarado.

> **Warning**
>
> Caso sua view não esteja renderizando um template contendo a tag de template [`csrf_token`](/pt-br/6.1/ref/templates/builtins/#std-templatetag-csrf_token), o Django pode não definir o cookie do token CSRF. Isso é comum em casos onde formulários são adicionados dinamicamente à página. Para resolver esse caso, o Django dá um decorator de view que força a definição deste cookie: [`ensure_csrf_cookie()`](/pt-br/6.1/ref/csrf/#django.views.decorators.csrf.ensure_csrf_cookie).

### Pegando o token caso: [`CSRF_USE_SESSIONS`](/pt-br/6.1/ref/settings/#std-setting-CSRF_USE_SESSIONS) ou [`CSRF_COOKIE_HTTPONLY`](/pt-br/6.1/ref/settings/#std-setting-CSRF_COOKIE_HTTPONLY) sejam `True`

Se você ativar [`CSRF_USE_SESSIONS`](/pt-br/6.1/ref/settings/#std-setting-CSRF_USE_SESSIONS) ou [`CSRF_COOKIE_HTTPONLY`](/pt-br/6.1/ref/settings/#std-setting-CSRF_COOKIE_HTTPONLY) você precisa incluir o token CSRF no seu HTML e ler o token do DOM com JavaScript:

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

### Definindo o token em uma requisição AJAX

Finalmente, você precisará definir o cabeçalho na sua requisição AJAX. Using a API [fetch()](https://developer.mozilla.org/en-US/docs/Web/API/fetch):

```javascript
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 a proteção CSRF em templates Jinja2

O backend de template [`Jinja2`](/pt-br/6.1/topics/templates/#django.template.backends.jinja2.Jinja2) do Django adiciona `{{ csrf_input }}` para o contexto de todos os templates que é equivalente ao `{% csrf_token %}` na linguagem de template do Django. Por exemplo:

```html+jinja
<form method="post">{{ csrf_input }}
```

## Usando o decorador de método

Em vez de adicionar `CsrfViewMiddleware` como uma proteção geral, você pode usar o decorador [`csrf_protect()`](/pt-br/6.1/ref/csrf/#django.views.decorators.csrf.csrf_protect), que tem exatamente a mesma funcionalidade, em views específicas que precisem de proteção. É necessário usá-lo **tanto** nas views que inserem o token CSRF na sua saída, **quanto** aquelas que aceitem dados de um formulário POST. (Geralmente essas duas estão na mesma função de view, mas não necessariamente).

O uso apenas do decorador **não é recomendado**, já que se você se esquecer de usá-lo, você pode ter uma brecha de segurança. A estratégia de usar ‘Cinto e suspensório’ é aceitável, e traz consequências mínimas.

## Lidando com requisições rejeitadas

Por padrão, uma resposta ‘403 Proibido’ é enviada para o usuário caso a requisição recebida falhe nas verificações feitas pelo `CsrfViewMiddleware`. Geralmente isso é apenas visto quando realmente há um Cross Site Request Forgery, ou quando devido um erro de programação, o token CSRF não é incluído junto do formulário POST.

A página de erro, porém, não é muito amigável, então você pode definir sua própria view para lidar com esta condição. Para fazer isso, defina a configuração [`CSRF_FAILURE_VIEW`](/pt-br/6.1/ref/settings/#std-setting-CSRF_FAILURE_VIEW).

Falhas CSRF são logadas como aviso pelo logger [django.security.csrf](/pt-br/6.1/ref/logging/#django-security-logger).

## Usando a proteção CSRF com cacheamento

Se a tag de template [`csrf_token`](/pt-br/6.1/ref/templates/builtins/#std-templatetag-csrf_token) é usado por um template (ou a função `get_token` é chamada de um outro jeito), o `CsrfViewMiddleware` adicionará o cookie e um  cabeçalho `Vary: Cookie` para a resposta. Isso significa que o middleware irá funcionar com o middleware de cachê se usado conforme instruído (`UpdateCacheMiddleware` deve vir antes de qualquer outro middleware).

Porém, se você usar decoradores de cachê em views individuais, o middleware de CSRF não será capaz de definir o cabeçalho Vary ou o cookie CSRF, e a resposta será cacheada sem nenhum deles. Nesse caso, quaisquer views que precisem que um token CSRF seja inserido você deve usar o decorador [`django.views.decorators.csrf.csrf_protect()`](/pt-br/6.1/ref/csrf/#django.views.decorators.csrf.csrf_protect) primeiro:

```
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): ...
```

Se você está usando class-based views, você pode se referir à [Decorating class-based views](/pt-br/6.1/topics/class-based-views/intro/#id1).

## Testes e a proteção CSRF

O `CsrfViewMiddleware` normalmente será um grande obstáculo para testar as funções view, devido a necessidade do token CSRF estar presente em toda requisição POST. Por isso, o cliente HTTP de testes do Django foi modificado para definir uma flag nas requisições que relaxam o middleware e o decorador `csrf_protect` para que eles não rejeitem as requisições. Em todos outros casos (por exemplo enviando cookies etc.), eles se comportam da mesma maneira.

Se, por algum motivo, você *quer* que o cliente de teste realize as verificações CSRF, você pode criar uma instância do cliente de teste que força as verificações CSRF:

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

## Casos extremos

Algumas views podem ter requisitos incomuns que não se encaixam nos padrões demonstrados aqui. Algumas ferramentas podem ser úteis nessas situações. Os cenários em que elas podem ser necessárias estão descritos nesta seção.

### Desabilitando a proteção CSRF  para apenas algumas views

A maioria das views precisam de proteção CSRF, mas algumas não.

Solução: Em vez de desabilitar o middleware e aplicar `csrf_protect` para todas as views que precisam, habilite o middleware e use [`csrf_exempt()`](/pt-br/6.1/ref/csrf/#django.views.decorators.csrf.csrf_exempt).

### Definindo o token quando `CsrfViewMiddleware.process_view()` não é utilizado

Existem casos onde `CsrfViewMiddleware.process_view` pode não ter sido executado antes da sua view - os handlers 404 e 500, por exemplo - Mas você ainda precisa de um token CSRF em um formulário.

Solução: use [`requires_csrf_token()`](/pt-br/6.1/ref/csrf/#django.views.decorators.csrf.requires_csrf_token)

### Incluindo o token CSRF em uma view desprotegida

Podem existir algumas views que são desprotegidas e foram exceções pelo `csrf_exempt`, mas ainda precisam incluir um token CSRF.

Solução: use [`csrf_exempt()`](/pt-br/6.1/ref/csrf/#django.views.decorators.csrf.csrf_exempt) seguido do [`requires_csrf_token()`](/pt-br/6.1/ref/csrf/#django.views.decorators.csrf.requires_csrf_token). (ou seja `requires_csrf_token` precisa ser o decorador mais próximo da função).

### Protegendo uma view para apenas um caminho

Uma view precisa da proteção CSRF apenas sob algumas condições, e pode não precisar em outras.

Solução: use [`csrf_exempt()`](/pt-br/6.1/ref/csrf/#django.views.decorators.csrf.csrf_exempt) para toda a função da view, e [`csrf_protect()`](/pt-br/6.1/ref/csrf/#django.views.decorators.csrf.csrf_protect) para o caminho interno que precisa de proteção. Exemplo:

```
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()
```

### Protegendo uma página que usa AJAX sem um formulário HTML

Uma página faz uma requisição POST por AJAX, e a página não contém um formulário HTML com um [`csrf_token`](/pt-br/6.1/ref/templates/builtins/#std-templatetag-csrf_token) que irá causar que o cookie de CSRF obrigatório seja enviado.

Solução: use [`ensure_csrf_cookie()`](/pt-br/6.1/ref/csrf/#django.views.decorators.csrf.ensure_csrf_cookie) não view que envia a página.

## Proteção CSRF em aplicações reutilizáveis

Já que é possível para o desenvolvedor desligar o `CsrfViewMiddleware`, todas as views relevantes nos apps contrib usam o decorador `csrf_protect` para garantir a segurançar destas aplicações contra CSRF. É recomendado que os desenvolvedores de apps reutilizáveis que querem as mesmas garantias também usem o decorador `csrf_protect` nas suas views.