Compartilhar via

Comportamento de autenticação de ponto de extremidade de API no ASP.NET Core

Ao usar cookie a autenticação, os pontos de extremidade de API retornam os códigos de status HTTP apropriados (como 401 ou 403) para falhas de autenticação em vez de redirecionar solicitações não autenticadas para páginas de logon. Esse comportamento, que é mais adequado para acesso à API programática, foi introduzido no ASP.NET Core no .NET 10.

Como ASP.NET Core identifica pontos de extremidade de 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 de extremidade mínimos de API registrados com MapGet, MapPost, MapPut, etc MapDelete.
  • Pontos de extremidade que solicitam explicitamente respostas JSON
  • SignalR hubs e pontos de extremidade

Comportamento e personalização padrão

Por padrão, ASP.NET Core aplica cookie a lógica de autenticação com base no tipo de ponto de extremidade:

  • Páginas da Web: Redirecionar para páginas de logon
  • Pontos de extremidade de API: retornar 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 detecçã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 não interromper aplicativos existentes:

  • Aplicativos Web: continue funcionando como antes com redirecionamentos de página de logon
  • Aplicativos mistos: os pontos de extremidade de API obtêm códigos de status adequados enquanto as páginas da Web recebem redirecionamentos
  • Aplicativos somente API: se beneficiam de códigos de status HTTP adequados sem configuração adicional

Testando seus pontos de extremidade de API

Depois de atualizar para o ASP.NET Core 10, verifique se os pontos de extremidade da API retornam códigos de status 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