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

Ao usar a autenticação cookie, os endpoints de API retornam os códigos de status HTTP apropriados (401 ou 403) para erros de autenticação, em vez de redirecionar solicitações não autenticadas para páginas de login. 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 endpoints de API

O ASP.NET Core adiciona IDisableCookieRedirectMetadata aos endpoints que reconhece como endpoints de API, incluindo:

• Controladores decorados com o [ApiController] atributo.
• Pontos de extremidade de API mínimos que processam corpos de solicitação JSON ou geram respostas JSON.
• Os pontos de extremidade que utilizam tipos de retorno TypedResults.
• SignalR hubs e pontos de extremidade.

A detecção se baseia nos metadados inferidos quando o aplicativo cria seus endpoints. Ele não se baseia no Accept cabeçalho de uma solicitação de entrada e não se baseia em qual Map{Verb} método registrou a rota.

Um manipulador de API mínima cujo tipo de retorno declarado é void, IResult ou a interface TypedResults não fornece metadados por meio do seu tipo de retorno, embora os tipos concretos Ok<TValue>, como string, forneçam. Por exemplo, app.MapGet("/hello", () => "Hello").RequireAuthorization() grava uma resposta text/plain e não aceita corpo de solicitação JSON, portanto solicitações não autenticadas para ele ainda são redirecionadas para a página de login.

Comportamento padrão

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

• Páginas da Web: redirecione para a página de logon ou acesso negado com um código de status 302.
• Pontos de extremidade de API: retornar códigos de status 401 ou 403 em vez de um redirecionamento 302.

XMLHttpRequests (XHRs) recebem respostas 401 e 403 independentemente do endpoint que acessam. Esse comportamento antecede .NET 10 e não é alterado.

Configurar o comportamento de endpoints específicos

Chame DisableCookieRedirect para retornar códigos de status 401 e 403 para endpoints que não são detectados automaticamente:

var api = app.MapGroup("/api").DisableCookieRedirect();

api.MapGet("/status", () => "Ready")
   .RequireAuthorization();

Chame AllowCookieRedirect para manter os redirecionamentos de login para endpoints identificados como endpoints de API:

app.MapGet("/reports/summary", () => new { Total = 1000 })
   .RequireAuthorization()
   .AllowCookieRedirect();

Para controladores, aplique-o AllowCookieRedirectAttribute a um método de ação ou à classe de controlador:

[ApiController]
[Authorize]
[AllowCookieRedirect]
[Route("[controller]")]
public class ReportsController : ControllerBase
{
    [HttpGet("summary")]
    public object GetSummary() => new { Total = 1000 };
}

Recusar o comportamento em todo o aplicativo

Para restaurar o comportamento pré-.NET 10 para um aplicativo inteiro, habilite a opçãoMicrosoft.AspNetCore.Authentication.Cookies.IgnoreRedirectMetadata. Quando isso está habilitado, a autenticação cookie ignora os metadados do endpoint, e somente as XHRs recebem respostas 401 e 403.

Defina a opção no arquivo de projeto para que ela se aplique antes que qualquer código de aplicativo seja executado:

<ItemGroup>
  <RuntimeHostConfigurationOption
    Include="Microsoft.AspNetCore.Authentication.Cookies.IgnoreRedirectMetadata"
    Value="true" />
</ItemGroup>

A chave também pode ser definida via código. Ele é lido uma vez, na primeira vez em que cookie a autenticação é usada; portanto, chame SetSwitch antes de o host ser criado:

AppContext.SetSwitch(
    "Microsoft.AspNetCore.Authentication.Cookies.IgnoreRedirectMetadata", true);

var builder = WebApplication.CreateBuilder(args);

Considerações sobre alterações incompatíveis

A alteração introduzida no .NET 10 é uma mudança comportamental. Um aplicativo que combina cookie autenticação com endpoints que o ASP.NET Core detecta como endpoints de API retorna respostas 401 e 403 onde antes retornava um redirecionamento 302 para a página de logon ou de acesso negado. Para ver o aviso completo da alteração significativa, consulte Cookie os redirecionamentos de login são desabilitados para endpoints de API conhecidos.

Considere o impacto em cada tipo de aplicativo:

• Aplicativos Web: os pontos de extremidade de página continuam a redirecionar para a página de logon.
• Aplicações mistas: os endpoints de API retornam códigos de status, enquanto as páginas web recebem redirecionamentos, portanto, o código do navegador que seguiu o redirecionamento deve lidar com 401 e 403 em vez disso.
• Aplicações somente de API: endpoints de API detectados retornam códigos de status HTTP corretos sem configuração adicional.

Para manter o comportamento anterior, chame AllowCookieRedirect nos endpoints afetados, aplique [AllowCookieRedirect] aos controladores afetados ou habilite a chave Microsoft.AspNetCore.Authentication.Cookies.IgnoreRedirectMetadata em todo o aplicativo.

Testando os endpoints da sua API

Depois de atualizar para o ASP.NET Core no .NET 10, verifique se os endpoints da API retornam códigos de status apropriados:

[Fact]
public async Task UnauthorizedApiRequest_Returns401()
{
    var response = await client.GetAsync("/api/secure-data");

    Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);

    // The handler sets the Location header before setting the status code,
    // so the login URI is still present on the 401 response.
    Assert.NotNull(response.Headers.Location);
}

Tópicos relacionados

• Usar cookie autenticação sem ASP.NET Core Identity
• Criar APIs Web com o ASP.NET Core
• Criar respostas em aplicativos de API mínimos
• SignalR autenticação e autorização
• Cookie Os redirecionamentos de login estão desativados para endpoints de API conhecidos