Gedrag van API-eindpuntverificatie in ASP.NET Core

Wanneer u cookie-authenticatie gebruikt, geven de API-eindpunten de juiste HTTP-statuscodes (401 of 403) terug voor authenticatiefouten, in plaats van niet-geverifieerde verzoeken door te sturen naar inlogpagina's. Dit gedrag, dat geschikter is voor programmatische API-toegang, is geïntroduceerd in ASP.NET Core in .NET 10.

Hoe ASP.NET Core API-eindpunten identificeert

ASP.NET Core voegt toe IDisableCookieRedirectMetadata aan de eindpunten die worden herkend als API-eindpunten, waaronder:

  • Controllers ingericht met het [ApiController] kenmerk.
  • Minimale API-eindpunten die JSON-aanvraagteksten lezen of JSON-antwoorden schrijven.
  • Eindpunten die gebruikmaken van TypedResults retourtypen.
  • SignalR hubs en eindpunten.

Detectie is gebaseerd op metagegevens die worden afgeleid wanneer de app de eindpunten bouwt. Deze is niet gebaseerd op de Accept header van een binnenkomende aanvraag en is niet gebaseerd op de methode die Map{Verb} de route heeft geregistreerd.

Een minimale API-handler waarvan het gedeclareerde retourtype void, IResult of de interface TypedResults is, levert via het retourtype geen metagegevens op, hoewel concrete typen van Ok<TValue>, zoals string, dat wel doen. Zo schrijft app.MapGet("/hello", () => "Hello").RequireAuthorization() bijvoorbeeld een text/plain reactie en accepteert het geen JSON-aanvraagbody, zodat niet-geverifieerde verzoeken nog steeds worden omgeleid naar de inlogpagina.

Standaardgedrag

Standaard past ASP.NET Core verificatielogica toe cookie op basis van het eindpunttype:

  • Webpagina's: omleiden naar de aanmeldings- of toegang geweigerde pagina met een 302-statuscode.
  • API-eindpunten: retourneert 401- of 403-statuscodes in plaats van een 302-omleiding.

XMLHttpRequests (XHR's) ontvangen 401- en 403-responses, ongeacht op welk eindpunt ze zijn gericht. Dat gedrag dateert van vóór .NET 10 en is ongewijzigd.

Opmerking

Metagegevens van eindpunten hebben alleen invloed op de challenge-(401)- en forbid-(403)-paden. Omleidingen na afmelden worden niet beïnvloed. Wanneer een afmeldingsaanvraag een omleidings-URI of een geldige retour-URL opgeeft, worden niet-XHR-aanvragen omgeleid zoals vóór .NET 10. XHR-gedrag is ongewijzigd.

Het gedrag voor specifieke eindpunten configureren

Aanroep DisableCookieRedirect om 401- en 403-statuscodes te retourneren voor eindpunten die niet automatisch worden gedetecteerd:

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

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

Aanroep AllowCookieRedirect om aanmeldingsomleidingen te bewaren voor eindpunten die worden gedetecteerd als API-eindpunten:

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

Voor controllers past u de AllowCookieRedirectAttribute methode toe op een actie of op de controllerklasse:

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

Important

IAllowCookieRedirectMetadata overschrijft IDisableCookieRedirectMetadata ongeacht de volgorde waarin de metagegevens worden toegevoegd. Het aanroepen van DisableCookieRedirect na AllowCookieRedirect op hetzelfde eindpunt herstelt het gedrag van de statuscode niet.

Dit gedrag voor de hele app uitschakelen

Als u het gedrag van vóór .NET 10 voor een hele app wilt herstellen, schakelt u de Microsoft.AspNetCore.Authentication.Cookies.IgnoreRedirectMetadata schakeloptie in. Wanneer dit is ingeschakeld, negeert cookie-authenticatie endpointmetadata en resulteren alleen XHR-verzoeken in 401- en 403-responses.

Stel de schakeloptie in het projectbestand in, zodat deze van toepassing is voordat app-code wordt uitgevoerd:

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

De schakelaar kan ook in code ingesteld worden. Het wordt eenmaal gelezen, de eerste keer dat cookie verificatie wordt gebruikt, dus roep SetSwitch aan voordat de host wordt gebouwd:

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

var builder = WebApplication.CreateBuilder(args);

Overwegingen bij brekende wijzigingen

De wijziging die in .NET 10 is geïntroduceerd, is een gedragswijziging. Een app die verificatie combineert cookie met eindpunten die ASP.NET Core detecteert als API-eindpunten, retourneert 401- en 403-antwoorden waarbij eerder een 302-omleiding naar de aanmeldings- of toegang geweigerde pagina werd geretourneerd. Zie Cookieomleidingen voor aanmeldingen zijn uitgeschakeld voor bekende API-eindpunten voor de volledige melding over de wijziging met belangrijke gevolgen.

Houd rekening met de gevolgen voor elk type app:

  • Webtoepassingen: Pagina-eindpunten blijven omleiden naar de aanmeldingspagina.
  • Gemengde toepassingen: API-eindpunten retourneren statuscodes terwijl webpagina's omleidingen krijgen. Browsercode die de omleiding heeft gevolgd, moet in plaats daarvan 401 en 403 verwerken.
  • ALLEEN-API-toepassingen: gedetecteerde API-eindpunten retourneren de juiste HTTP-statuscodes zonder aanvullende configuratie.

Als u het vorige gedrag wilt behouden, roept u AllowCookieRedirect aan voor de betreffende eindpunten, past u [AllowCookieRedirect] toe op de betreffende controllers of schakelt u de Microsoft.AspNetCore.Authentication.Cookies.IgnoreRedirectMetadata-schakelaar in voor de hele app.

Uw API-eindpunten testen

Nadat u een upgrade hebt uitgevoerd naar ASP.NET Core in .NET 10, controleert u of uw API-eindpunten de juiste statuscodes retourneren:

[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);
}