Previna ataques de falsificação de solicitação entre sites (XSRF/CSRF) no ASP.NET Core

Por Fiyaz Hasan e Rick Anderson

A falsificação de solicitação entre sites é um ataque contra aplicativos hospedados na Web pelo qual um aplicativo Web mal-intencionado pode influenciar a interação entre um navegador cliente e um aplicativo Web que confia nesse navegador. Esses ataques são possíveis porque os navegadores da Web enviam alguns tipos de tokens de autenticação automaticamente a cada solicitação para um site. Essa forma de exploração também é conhecida como ataque de um clique ou sequestro de sessão porque o ataque aproveita a sessão previamente autenticada do utilizador. A falsificação de solicitação entre sites também é conhecida como XSRF ou CSRF.

Um exemplo de um ataque CSRF:

1. Um utilizador entra em www.good-banking-site.example.com usando a autenticação por formulários. O servidor autentica o usuário e emite uma resposta que inclui uma autenticação cookie. O site é vulnerável a ataques porque confia em qualquer solicitação recebida com uma autenticação válida cookie.

2. O utilizador visita um site malicioso, www.bad-crook-site.example.com.

   O site mal-intencionado, www.bad-crook-site.example.com, contém um formulário HTML semelhante ao exemplo a seguir:

   <h1>Congratulations! You're a Winner!</h1>
   <form action="https://www.good-banking-site.example.com/api/account" method="post">
       <input type="hidden" name="Transaction" value="withdraw" />
       <input type="hidden" name="Amount" value="1000000" />
       <input type="submit" value="Click to collect your prize!" />
   </form>
   

   Observe que o action do formulário envia informações para o site vulnerável, não para o site malicioso. Esta é a parte "cross-site" da CSRF.

3. O usuário seleciona o botão enviar. O navegador faz a solicitação e inclui automaticamente a autenticação cookie para o domínio solicitado, www.good-banking-site.example.com.

4. A solicitação é executada no servidor www.good-banking-site.example.com com o contexto de autenticação do usuário e pode executar qualquer ação que um usuário autenticado tenha permissão para executar.

Além do cenário em que o usuário seleciona o botão para enviar o formulário, o site mal-intencionado pode:

• Execute um script que envia automaticamente o formulário.
• Envie o envio do formulário como uma solicitação AJAX.
• Oculte o formulário usando CSS.

Esses cenários alternativos não exigem nenhuma ação ou entrada do usuário além de visitar inicialmente o site mal-intencionado.

O uso de HTTPS não impede um ataque CSRF. O site mal-intencionado pode enviar uma solicitação https://www.good-banking-site.example.com/ tão facilmente quanto pode enviar uma solicitação insegura.

Alguns ataques têm como alvo endpoints que respondem a solicitações GET, caso em que uma etiqueta de imagem pode ser usada para executar a ação. Esta forma de ataque é comum em sites de fóruns que permitem imagens, mas bloqueiam JavaScript. Os aplicativos que mudam de estado em solicitações GET, onde variáveis ou recursos são alterados, são vulneráveis a ataques mal-intencionados. As solicitações GET que mudam de estado são inseguras. Uma prática recomendada é nunca alterar o estado em uma solicitação GET.

Os ataques CSRF são possíveis contra aplicativos da Web que usam cookies para autenticação porque:

• Os navegadores armazenam cookies emitidos por um aplicativo da Web.
• Os cookies armazenados incluem cookies de sessão para utilizadores autenticados.
• Os navegadores enviam todos os cookies associados a um domínio para o aplicativo Web a cada solicitação, independentemente de como a solicitação para o aplicativo foi gerada dentro do navegador.

No entanto, os ataques CSRF não se limitam a explorar cookies. Por exemplo, as autenticações Basic e Digest também são vulneráveis. Depois que um usuário entra com autenticação Básica ou Digest, o navegador envia automaticamente as credenciais até que a sessão termine.

Neste contexto, sessão refere-se à sessão do lado do cliente durante a qual o usuário é autenticado. Não está relacionado com sessões do lado do servidor nem com middleware de sessões ASP.NET Core.

Os usuários podem se proteger contra vulnerabilidades CSRF tomando precauções:

• Saia dos aplicativos Web quando terminar de usá-los.
• Limpe os cookies do navegador periodicamente.

No entanto, as vulnerabilidades CSRF são fundamentalmente um problema com o aplicativo Web, não com o usuário final.

Fundamentos de autenticação

A autenticação baseada em Cookieé uma forma popular de autenticação. Os sistemas de autenticação baseados em tokens estão crescendo em popularidade, especialmente para aplicativos de página única (SPAs).

Autenticação baseada em Cookie

Quando um usuário se autentica usando seu nome de usuário e senha, ele recebe um token contendo um tíquete de autenticação. O token pode ser usado para autenticação e autorização. O token é armazenado como um cookie que é enviado a cada solicitação feita pelo cliente. A geração e validação disto cookie é feita através do cookie middleware de autenticação. O middleware serializa uma entidade de usuário em um cookiecriptografado. Em solicitações subsequentes, o middleware valida o cookie, recria o principal e atribui o principal à propriedade HttpContext.User.

Autenticação baseada em tokens

Quando um usuário é autenticado, ele recebe um token (não um token antifalsificação). O token contém informações do usuário na forma de declarações ou um token de referência que aponta o aplicativo para o estado do usuário mantido no aplicativo. Quando um usuário tenta acessar um recurso que requer autenticação, o token é enviado para o aplicativo com um cabeçalho de autorização extra na forma de um token de portador. Essa abordagem torna a aplicação sem estado. Em cada solicitação subsequente, o token é passado na solicitação de validação do lado do servidor. Este token não é criptografado; é codificado. No servidor, o token é decodificado para acessar suas informações. Para enviar o token em solicitações subsequentes, armazene-o no armazenamento local do navegador. Colocar um token no armazenamento local do navegador e recuperá-lo e usá-lo como um token de portador fornece proteção contra ataques CSRF. No entanto, se o aplicativo estiver vulnerável à injeção de script via XSS ou a um arquivo JavaScript externo comprometido, um ciberinvasor poderá recuperar qualquer valor do armazenamento local e enviá-lo para si mesmo. ASP.NET Core codifica todas as saídas do lado do servidor de variáveis por padrão, reduzindo o risco de XSS. Se substituir este comportamento usando Html.Raw ou códigos personalizados com entradas não confiáveis, poderá aumentar o risco de XSS.

Não se preocupe com a vulnerabilidade CSRF se o token estiver armazenado no armazenamento local do navegador. CSRF é uma preocupação quando o token é armazenado num cookie. Para obter mais informações, consulte o problema da GitHub , onde o exemplo de código SPA adiciona dois cookies.

Vários aplicativos hospedados em um domínio

Os ambientes de alojamento partilhado são vulneráveis a sequestro de sessão, CSRF no início de sessão e outros ataques.

Embora example1.contoso.net e example2.contoso.net sejam hosts diferentes, há uma relação de confiança implícita entre hosts sob o domínio *.contoso.net. Essa relação de confiança implícita permite que hosts potencialmente não confiáveis afetem os cookies uns dos outros (as políticas de mesma origem que regem as solicitações AJAX não se aplicam necessariamente aos cookies HTTP).

Os ataques que exploram cookies confiáveis entre aplicativos hospedados no mesmo domínio podem ser evitados não compartilhando domínios. Quando cada aplicativo é hospedado em seu próprio domínio, não há nenhuma relação de confiança implícita cookie para explorar.

Antifalsificação no ASP.NET Core

Advertência

ASP.NET Core implementa antifalsificação usando ASP.NET Core Data Protection. A pilha de proteção de dados deve ser configurada para funcionar numa server farm. Para obter mais informações, consulte Configurando a proteção de dados.

O middleware antifalsificação é adicionado ao contêiner de injeção de dependência quando uma das seguintes APIs é chamada em .

• AddMvc
• MapRazorPages
• MapControllerRoute
• AddRazorComponents

Para obter mais informações, consulte Antifalsificação com APIs Mínimas.

O FormTagHelper injeta tokens antifalsificação em elementos de formulário HTML. A marcação a seguir em um arquivo Razor gera automaticamente tokens antifalsificação:

<form method="post">
    <!-- ... -->
</form>

Da mesma forma, IHtmlHelper.BeginForm gera tokens antifalsificação por padrão se o método do formulário não for GET.

A geração automática de tokens antifalsificação para elementos de formulário HTML acontece quando a tag <form> contém o atributo method="post" e uma das seguintes opções é verdadeira:

• O atributo action está vazio (action="").
• O atributo action não é fornecido (<form method="post">).

A geração automática de tokens antifalsificação para elementos de formulário HTML pode ser desativada:

• Desative explicitamente os tokens antifalsificação com o atributo asp-antiforgery:

  <form method="post" asp-antiforgery="false">
      <!-- ... -->
  </form>
  

• O elemento de formulário é excluído dos Auxiliares de Tag usando o símbolo de exclusão do Auxiliar de Tag !:

  <!form method="post">
      <!-- ... -->
  </!form>
  

• Remova o FormTagHelper da visualização. O FormTagHelper pode ser removido de um modo de exibição adicionando a seguinte diretiva ao modo de exibição Razor:

  @removeTagHelper Microsoft.AspNetCore.Mvc.TagHelpers.FormTagHelper, Microsoft.AspNetCore.Mvc.TagHelpers
  

Observação

Razor Páginas são automaticamente protegidas contra XSRF/CSRF. Para obter mais informações, consulte XSRF/CSRF e Razor Pages.

A abordagem mais comum para proteger contra ataques CSRF é usar o Synchronizer Token Pattern (STP). O STP é usado quando o usuário solicita uma página com dados de formulário:

1. O servidor envia um token associado à identidade do usuário atual para o cliente.
2. O cliente envia de volta o token para o servidor para verificação.
3. Se o servidor receber um token que não corresponda à identidade do usuário autenticado, a solicitação será rejeitada.

O token é único e imprevisível. O token também pode ser usado para garantir o sequenciamento adequado de uma série de solicitações (por exemplo, garantindo a sequência de solicitação de: página 1 > página 2 > página 3). Todos os formulários nos modelos ASP.NET Core MVC e Razor Pages geram tokens antifalsificação. O seguinte par de exemplos de visualização gera tokens antifalsificação:

<form asp-action="Index" asp-controller="Home" method="post">
    <!-- ... -->
</form>

@using (Html.BeginForm("Index", "Home"))
{
    <!-- ... -->
}

Adicione explicitamente um token antifalsificação a um elemento <form> sem usar Tag Helpers com o HTML helper @Html.AntiForgeryToken:

<form asp-action="Index" asp-controller="Home" method="post">
    @Html.AntiForgeryToken()

    <!-- ... -->
</form>

Em cada um dos casos anteriores, o ASP.NET Core adiciona um campo de formulário oculto semelhante ao exemplo a seguir:

<input name="__RequestVerificationToken" type="hidden" value="CfDJ8NrAkS ... s2-m9Yw">

ASP.NET Core inclui três filtros para trabalhar com tokens antifalsificação:

• ValidateAntiForgeryToken
• AutoValidateAntiforgeryToken
• IgnoreAntiforgeryToken

Antifalsificação com AddControllers

Chamar AddControllers não habilita tokens de antifalsificação. AddControllersWithViews deve ser chamado para ter suporte de token antifalsificação integrado.

Várias guias do navegador e o Padrão de Token do Sincronizador

Não é suportado ter várias abas abertas com acessos de diferentes utilizadores, ou abrir uma aba como anónimo.

Configurar o antifalsificação com o AntiforgeryOptions

Personalize AntiforgeryOptions no ficheiro Program da aplicação:

builder.Services.AddAntiforgery(options =>
{
    // Set Cookie properties using CookieBuilder properties†.
    options.FormFieldName = "AntiforgeryFieldname";
    options.HeaderName = "X-CSRF-TOKEN-HEADERNAME";
    options.SuppressXFrameOptionsHeader = false;
});

Defina as propriedades antifalsificação cookie usando as propriedades da classe CookieBuilder, conforme mostrado na tabela a seguir.

Opção	Descrição
Cookie	Determina as configurações usadas para criar os cookies antifalsificação.
FormFieldName	O nome do campo de formulário oculto utilizado pelo sistema de proteção contra falsificação para renderizar tokens antifalsificação nas visualizações.
HeaderName	O nome do cabeçalho usado pelo sistema antifalsificação. Se null, o sistema considera apenas os dados do formulário.
SuppressXFrameOptionsHeader	Especifica se a geração do cabeçalho X-Frame-Options deve ser suprimida. Por padrão, o cabeçalho é gerado com um valor de "SAMEORIGIN". O padrão é false.

Alguns navegadores não permitem que endpoints inseguros definam cookies com um sinalizador "seguro" ou substituam cookies cujo sinalizador "seguro" esteja definido (para obter mais informações, consulte Depreciar a modificação de cookies "seguros" de origens não seguras). Como misturar pontos de extremidade seguros e inseguros é um cenário comum em aplicações, o ASP.NET Core relaxa a restrição da política segura em alguns cookies, como o antiforjação cookie, ao definir o cookie de SecurePolicy como CookieSecurePolicy.None. Mesmo que um utilizador mal-intencionado roube um antifalsificação cookie, ele também deve roubar o token antifalsificação que normalmente é enviado por meio de um campo de formulário (mais comum) ou através de um cabeçalho de solicitação separado (menos comum), além de roubar a autenticação cookie. Os cookies relacionados com autenticação ou autorização utilizam uma política mais forte do que CookieSecurePolicy.Nonea .

Opcionalmente, pode proteger o token de antifalsificação cookie em ambientes nãoDevelopment seguros usando o protocolo Secure Sockets Layer (SSL), somente sobre HTTPS, com a seguinte definição de propriedades AntiforgeryOptions.Cookie no ficheiro da Program aplicação.

if (!builder.Environment.IsDevelopment())
{
    builder.Services.AddAntiforgery(o =>
    {
        o.Cookie.SecurePolicy = CookieSecurePolicy.Always;
    });
}

Para obter mais informações, consulte CookieAuthenticationOptions.

Gere tokens antifalsificação com IAntiforgery

IAntiforgery fornece a API para configurar recursos antifalsificação. IAntiforgery pode ser solicitado em Program.cs usando WebApplication.Services. O exemplo a seguir usa middleware da página inicial do aplicativo para gerar um token antifalsificação e enviá-lo na resposta como um cookie:

app.UseRouting();

app.UseAuthorization();

var antiforgery = app.Services.GetRequiredService<IAntiforgery>();

app.Use((context, next) =>
{
    var requestPath = context.Request.Path.Value;

    if (string.Equals(requestPath, "/", StringComparison.OrdinalIgnoreCase)
        || string.Equals(requestPath, "/index.html", StringComparison.OrdinalIgnoreCase))
    {
        var tokenSet = antiforgery.GetAndStoreTokens(context);
        context.Response.Cookies.Append("XSRF-TOKEN", tokenSet.RequestToken!,
            new CookieOptions { HttpOnly = false });
    }

    return next(context);
});

O exemplo anterior define um cookie chamado XSRF-TOKEN. O cliente pode ler essa cookie e fornecer seu valor como um cabeçalho anexado às solicitações AJAX. Por exemplo, o Angular inclui proteção XSRF integrada que, por padrão, lê um cookie chamado XSRF-TOKEN.

Exigir validação antifalsificação

O filtro de ação ValidateAntiForgeryToken pode ser aplicado a uma ação individual, a um controlador ou globalmente. As solicitações feitas para ações que têm esse filtro aplicado são bloqueadas, a menos que a solicitação inclua um token antifalsificação válido:

[HttpPost]
[ValidateAntiForgeryToken]
public IActionResult Index()
{
    // ...

    return RedirectToAction();
}

O atributo ValidateAntiForgeryToken requer um token para solicitações para os métodos de ação que ele marca, incluindo solicitações HTTP GET. Se o atributo ValidateAntiForgeryToken for aplicado nos controladores do aplicativo, ele poderá ser substituído pelo atributo IgnoreAntiforgeryToken.

Valide automaticamente tokens antifalsificação apenas para métodos HTTP inseguros

Em vez de aplicar amplamente o atributo ValidateAntiForgeryToken e, em seguida, substituí-lo por atributos IgnoreAntiforgeryToken, o atributo AutoValidateAntiforgeryToken pode ser usado. Esse atributo funciona de forma idêntica ao atributo ValidateAntiForgeryToken, exceto que ele não requer tokens para solicitações feitas usando os seguintes métodos HTTP:

• OBTER
• CABEÇA
• OPÇÕES
• RASTREIO

Recomendamos o uso de AutoValidateAntiforgeryToken de forma ampla para cenários que não sejam de API. Esse atributo garante que as ações POST sejam protegidas por padrão. A alternativa é ignorar tokens de antifalsificação por padrão, a menos que ValidateAntiForgeryToken seja aplicado individualmente aos métodos de ação. É mais provável, neste cenário, que um método de ação POST seja deixado desprotegido por engano, deixando o aplicativo vulnerável a ataques CSRF. Todos os POSTs devem enviar o token antifalsificação.

As APIs não têm um mecanismo automático para enviar a parte nãocookie do token. A implementação provavelmente depende da implementação do código do cliente. Alguns exemplos são mostrados abaixo:

Exemplo de nível de classe:

[AutoValidateAntiforgeryToken]
public class HomeController : Controller

Exemplo global:

builder.Services.AddControllersWithViews(options =>
{
    options.Filters.Add(new AutoValidateAntiforgeryTokenAttribute());
});

Substituir atributos antifalsificação globais ou de controlador

O filtro IgnoreAntiforgeryToken é usado para eliminar a necessidade de um token antifalsificação para uma determinada ação (ou controlador). Quando aplicado, este filtro substitui os filtros ValidateAntiForgeryToken e AutoValidateAntiforgeryToken especificados a um nível superior (globalmente ou num controlador).

[IgnoreAntiforgeryToken]
public IActionResult IndexOverride()
{
    // ...

    return RedirectToAction();
}

Atualizar os tokens após a autenticação

Os tokens devem ser atualizados depois de o utilizador ser autenticado, redirecionando-o para uma vista ou página Razor Páginas.

JavaScript, AJAX e SPAs

Em aplicativos tradicionais baseados em HTML, os tokens antifalsificação são passados para o servidor usando campos de formulário ocultos. Em aplicativos e SPAs modernos baseados em JavaScript, muitas solicitações são feitas programaticamente. Essas solicitações AJAX podem usar outras técnicas, como cabeçalhos de solicitação ou cookies, para enviar o token.

Se os cookies forem usados para armazenar tokens de autenticação e autenticar solicitações de API no servidor, o CSRF é um problema potencial. Se o armazenamento local for usado para armazenar o token, a vulnerabilidade CSRF poderá ser atenuada porque os valores do armazenamento local não são enviados automaticamente para o servidor a cada solicitação. Usar o armazenamento local para armazenar o token antifalsificação no cliente e enviar o token como um cabeçalho de solicitação é uma abordagem recomendada.

Blazor

Para obter mais informações, consulte ASP.NET Core Blazor authentication and authorization.

JavaScript

Usando JavaScript com visualizações, o token pode ser criado usando um serviço de dentro da visualização. Injete o serviço de IAntiforgery na visualização e ligue para GetAndStoreTokens:

@inject Microsoft.AspNetCore.Antiforgery.IAntiforgery Antiforgery

@{
    ViewData["Title"] = "JavaScript";

    var requestToken = Antiforgery.GetAndStoreTokens(Context).RequestToken;
}

<input id="RequestVerificationToken" type="hidden" value="@requestToken" />

<button id="button" class="btn btn-primary">Submit with Token</button>
<div id="result" class="mt-2"></div>

@section Scripts {
<script>
    document.addEventListener("DOMContentLoaded", () => {
        const resultElement = document.getElementById("result");

        document.getElementById("button").addEventListener("click", async () => {

            const response = await fetch("@Url.Action("FetchEndpoint")", {
                method: "POST",
                headers: {
                    RequestVerificationToken:
                        document.getElementById("RequestVerificationToken").value
                }
            });

            if (response.ok) {
                resultElement.innerText = await response.text();
            } else {
                resultElement.innerText = `Request Failed: ${response.status}`
            }
        });
    });
</script>
}

O exemplo anterior usa JavaScript para ler o valor de campo oculto para o cabeçalho AJAX POST.

Esta abordagem elimina a necessidade de lidar diretamente com a configuração de cookies do servidor ou lê-los a partir do cliente. No entanto, quando não for possível injetar o serviço IAntiforgery, use JavaScript para acessar tokens em cookies:

• Tokens de acesso em uma solicitação adicional ao servidor, tipicamente same-origin.
• Use o conteúdo do cookiepara criar um cabeçalho com o valor do token.

Supondo que o script envie o token em um cabeçalho de solicitação chamado X-XSRF-TOKEN, configure o serviço antifalsificação para procurar o cabeçalho X-XSRF-TOKEN:

builder.Services.AddAntiforgery(options => options.HeaderName = "X-XSRF-TOKEN");

O exemplo a seguir adiciona um ponto de extremidade protegido que grava o token de solicitação em um cookielegível por JavaScript:

app.UseAuthorization();
app.MapGet("antiforgery/token", (IAntiforgery forgeryService, HttpContext context) =>
{
    var tokens = forgeryService.GetAndStoreTokens(context);
    context.Response.Cookies.Append("XSRF-TOKEN", tokens.RequestToken!,
            new CookieOptions { HttpOnly = false });

    return Results.Ok();
}).RequireAuthorization();

O exemplo a seguir usa JavaScript para fazer uma solicitação AJAX para obter o token e fazer outra solicitação com o cabeçalho apropriado:

var response = await fetch("/antiforgery/token", {
    method: "GET",
    headers: { "Authorization": authorizationToken }
});

if (response.ok) {
    // https://developer.mozilla.org/docs/web/api/document/cookie
    const xsrfToken = document.cookie
        .split("; ")
        .find(row => row.startsWith("XSRF-TOKEN="))
        .split("=")[1];

    response = await fetch("/JavaScript/FetchEndpoint", {
        method: "POST",
        headers: { "X-XSRF-TOKEN": xsrfToken, "Authorization": authorizationToken }
    });

    if (response.ok) {
        resultElement.innerText = await response.text();
    } else {
        resultElement.innerText = `Request Failed: ${response.status}`
    }
} else {    
    resultElement.innerText = `Request Failed: ${response.status}`
}

Observação

Quando o token antifalsificação é fornecido no cabeçalho da solicitação e na carga útil do formulário, somente o token no cabeçalho é validado.

Antifalsificação com APIs mínimas

Chame AddAntiforgery e UseAntiforgery(IApplicationBuilder) para registar os serviços de antifalsificação na DI. Os tokens antifalsificação são usados para mitigar ataques de falsificação de solicitação entre sites.

var builder = WebApplication.CreateBuilder();

builder.Services.AddAntiforgery();

var app = builder.Build();

app.UseAntiforgery();

app.MapGet("/", () => "Hello World!");

app.Run();

O middleware de antifalsificação de software:

• O não interrompe a execução do restante do pipeline de solicitação?
• Define o IAntiforgeryValidationFeature no HttpContext.Features da solicitação atual.

O token antifalsificação só é validado se:

• O ponto de extremidade contém metadados que implementam IAntiforgeryMetadata quando RequiresValidation=trueocorre.
• O método HTTP associado ao endpoint é um método HTTP relevante do tipo POST, PUT ou PATCH.
• A solicitação está associada a um ponto de extremidade válido.

O middleware antifalsificação não interrompe o pipeline de processamento de pedidos. O código do endpoint é sempre executado, mesmo que a validação do token falhe. Para observar o resultado da validação do token, resolva o IAntiforgeryValidationFeature de HttpContext.Features e inspecione a propriedade IsValid ou a propriedade Error para detalhes de falha. Esta abordagem é útil quando os endpoints requerem tratamento personalizado para validação antifalsificação falhada.

Nota: Quando ativado manualmente, o middleware antifalsificação deve ser executado após o middleware de autenticação e autorização para impedir a leitura de dados de formulário quando o usuário não é autenticado.

Por defeito, as APIs Mínimas que aceitam dados de formulário requerem validação de tokens antifalsificação e falham antes de executar o código da aplicação se a validação antifalsificação não for bem-sucedida.

Considere o seguinte método GenerateForm:

public static string GenerateForm(string action, 
    AntiforgeryTokenSet token, bool UseToken=true)
{
    string tokenInput = "";
    if (UseToken)
    {
        tokenInput = $@"<input name=""{token.FormFieldName}""
                         type=""hidden"" value=""{token.RequestToken}"" />";
    }

    return $@"
    <html><body>
        <form action=""{action}"" method=""POST"" enctype=""multipart/form-data"">
            {tokenInput}
            <input type=""text"" name=""name"" />
            <input type=""date"" name=""dueDate"" />
            <input type=""checkbox"" name=""isCompleted"" />
            <input type=""submit"" />
        </form>
    </body></html>
";
}

O código anterior tem três argumentos, a ação, o token antifalsificação e um bool indicando se o token deve ser usado.

Considere o seguinte exemplo:

using Microsoft.AspNetCore.Antiforgery;
using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder();

builder.Services.AddAntiforgery();

var app = builder.Build();

app.UseAntiforgery();

// Pass token
app.MapGet("/", (HttpContext context, IAntiforgery antiforgery) =>
{
    var token = antiforgery.GetAndStoreTokens(context);
    return Results.Content(MyHtml.GenerateForm("/todo", token), "text/html");
});

// Don't pass a token, fails
app.MapGet("/SkipToken", (HttpContext context, IAntiforgery antiforgery) =>
{
    var token = antiforgery.GetAndStoreTokens(context);
    return Results.Content(MyHtml.GenerateForm("/todo",token, false ), "text/html");
});

// Post to /todo2. DisableAntiforgery on that endpoint so no token needed.
app.MapGet("/DisableAntiforgery", (HttpContext context, IAntiforgery antiforgery) =>
{
    var token = antiforgery.GetAndStoreTokens(context);
    return Results.Content(MyHtml.GenerateForm("/todo2", token, false), "text/html");
});

app.MapPost("/todo", ([FromForm] Todo todo) => Results.Ok(todo));

app.MapPost("/todo2", ([FromForm] Todo todo) => Results.Ok(todo))
                                                .DisableAntiforgery();

app.Run();

class Todo
{
    public required string Name { get; set; }
    public bool IsCompleted { get; set; }
    public DateTime DueDate { get; set; }
}

public static class MyHtml
{
    public static string GenerateForm(string action, 
        AntiforgeryTokenSet token, bool UseToken=true)
    {
        string tokenInput = "";
        if (UseToken)
        {
            tokenInput = $@"<input name=""{token.FormFieldName}""
                             type=""hidden"" value=""{token.RequestToken}"" />";
        }

        return $@"
        <html><body>
            <form action=""{action}"" method=""POST"" enctype=""multipart/form-data"">
                {tokenInput}
                <input type=""text"" name=""name"" />
                <input type=""date"" name=""dueDate"" />
                <input type=""checkbox"" name=""isCompleted"" />
                <input type=""submit"" />
            </form>
        </body></html>
    ";
    }
}

No código anterior, posta para:

• /todo exige um token antifalsificação válido.
• /todo2 não exige um token antifalsificação válido porque DisableAntiforgery é chamado.

app.MapPost("/todo", ([FromForm] Todo todo) => Results.Ok(todo));

app.MapPost("/todo2", ([FromForm] Todo todo) => Results.Ok(todo))
                                                .DisableAntiforgery();

Advertência

A chamada .DisableAntiforgery() desativa a proteção contra ataques CSRF (Cross-Site Request Forgery) para o endpoint. Isto só deve ser usado quando um endpoint não está vulnerável a ataques CSRF, tais como:

• Endpoints que não podem ser chamados a partir de um navegador (por exemplo, APIs internas)
• Endpoints protegidos com autenticação não baseada em cookie (por exemplo, tokens bearer ou chaves de API)
• Endpoints internos ou de infraestrutura que não dependem de cookies de utilizador

Não desative a validação antifalsificação para endpoints acessíveis ao navegador que dependem de cookies para autenticação ou que processam dados de formulários submetidos pelo utilizador, pois isso expõe a sua aplicação a ataques CSRF.

Um POST para:

• /todo do formulário gerado pelo endpoint / é bem-sucedido porque o token antifalsificação é válido.
• /todo do formulário gerado pelo /SkipToken falha porque o antifalsificação não está incluído.
• /todo2 do formulário gerado pelo ponto de extremidade /DisableAntiforgery tem sucesso porque a proteção contra falsificação não é necessária.

app.MapPost("/todo", ([FromForm] Todo todo) => Results.Ok(todo));

app.MapPost("/todo2", ([FromForm] Todo todo) => Results.Ok(todo))
                                                .DisableAntiforgery();

Quando um formulário é enviado sem um token antifalsificação válido:

• No Development ambiente, é lançada uma exceção.
• No Production ambiente, uma mensagem é registada.

Limitações do método HTTP e da interação HttpMethodOverrideMiddleware

Para o caminho de antifalsificação baseado em middleware, AntiforgeryMiddleware e UseAntiforgery() validam os tokens de antifalsificação apenas para pedidos HTTP do tipo POST, PUT e PATCH. Outros métodos HTTP, como o DELETE, não são validados automaticamente.

Para validar tokens de proteção antifalsificação para outros métodos HTTP, resolva IAntiforgery através da DI e chame ValidateRequestAsync ou IsRequestValidAsync explicitamente:

app.MapDelete("/item/{id}", async (int id, IAntiforgery antiforgery, HttpContext context) =>
{
    await antiforgery.ValidateRequestAsync(context);
    // Process the DELETE request
});

Advertência

Quando HttpMethodOverrideMiddleware está configurado com FormFieldName (modo de campo de formulário) e colocado antes de AntiforgeryMiddleware, um pedido POST pode ser substituído por DELETE (ou outro método não validado). Como AntiforgeryMiddleware valida apenas POST, PUT e PATCH, o pedido substituído contorna a validação anti-falsificação.

Para proteger estes endpoints:

• Prefira colocar HttpMethodOverrideMiddleware após a validação antifalsificação quando o seu pipeline o permitir.
• Evite sobrescrições de campos de formulário para endpoints que dependam da validação antifalsificação.
• Se a substituição do campo de formulário tiver de ser executada primeiro, valide explicitamente o token anti-falsificação usando IAntiforgery.ValidateRequestAsync.

Para detalhes de configuração, consulte o middleware ASP.NET Core.

Cookies de autenticação e antifalsificação do Windows

Ao usar a Autenticação do Windows, os pontos de extremidade da aplicação devem ser protegidos contra ataques CSRF da mesma maneira que são protegidos os cookies. O navegador envia implicitamente o contexto de autenticação para o servidor e os endpoints precisam ser protegidos contra ataques CSRF.

Estender a antifalsificação

O tipo IAntiforgeryAdditionalDataProvider permite que os desenvolvedores estendam o comportamento do sistema anti-CSRF ao incluir dados adicionais em cada token. O método GetAdditionalData é chamado cada vez que um token de campo é gerado, e o valor de retorno é incorporado no token gerado. Um implementador pode retornar um carimbo de data/hora, um nonce ou qualquer outro valor e, em seguida, chamar ValidateAdditionalData para validar esses dados quando o token for validado. O nome de usuário do cliente já está incorporado nos tokens gerados, portanto, não há necessidade de incluir essas informações. Se um token incluir dados suplementares, mas nenhum IAntiForgeryAdditionalDataProvider estiver configurado, os dados suplementares não serão validados.

Recursos adicionais

• Host ASP.NET Core numa web farm