Comportamento da autenticação do endpoint da API no ASP.NET Core

Ao utilizar a autenticação cookie, os pontos finais da API devolvem os códigos de estado HTTP adequados (como 401 ou 403) para falhas de autenticação, em vez de redirecionarem pedidos não autenticados para páginas de início de sessão. Esse comportamento, que é mais adequado para acesso à API programática, foi introduzido no ASP.NET Core no .NET 10.

Como o ASP.NET Core identifica os endpoints da API

ASP.NET Core aplica automaticamente esse comportamento a pontos de extremidade que reconhece como relacionados à API, incluindo:

  • Controladores decorados com o [ApiController] atributo
  • Pontos finais mínimos da API registados com MapGet, MapPost, MapPut, MapDelete, etc.
  • Pontos de acesso que solicitam explicitamente respostas JSON
  • SignalR hubs e pontos finais

Comportamento padrão e personalização

Por predefinição, o ASP.NET Core aplica a lógica de autenticação cookie consoante o tipo de endpoint:

  • Páginas Web: Redirecionar para páginas de início de sessão
  • Pontos de extremidade da API: retornam códigos de status 401 ou 403 sem redirecionamentos

Configurando o comportamento

Embora o comportamento padrão funcione para a maioria dos cenários, ele pode ser personalizado, se necessário:

builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options =>
    {
        options.LoginPath = "/Account/Login";
        // The framework automatically handles API endpoints
        // No additional configuration needed
    });

Se você precisar substituir a deteção automática para pontos de extremidade específicos, use o [Authorize] atributo com esquemas de autenticação específicos ou implemente manipuladores de autenticação personalizados.

Considerações sobre migração

Essa alteração de comportamento introduzida no .NET 10 foi projetada para ser ininterrupta para aplicativos existentes:

  • Aplicativos Web: Continue a funcionar como antes com redirecionamentos de página de login
  • Aplicativos mistos: os pontos de extremidade da API recebem códigos de status adequados, enquanto as páginas da Web recebem redirecionamentos
  • Aplicativos somente API: Beneficie-se de códigos de status HTTP adequados sem configuração adicional

Testar os endpoints da sua API

Depois de atualizar para o ASP.NET Core 10, verifique se os pontos finais da API devolvem os códigos de estado apropriados:

[Test]
public async Task UnauthorizedApiRequest_Returns401()
{
    var response = await client.GetAsync("/api/secure-data");
    Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);
    Assert.False(response.Headers.Location != null); // No redirect
}
  • Last updated on