Add support for anti-forgery middleware

[captainsafia]

Background and Motivation

MVC currently supports anti-forgery token validation via an endpoint filter. Similar constructs do not exist for minimal APIs. This proposal outlines support for an anti-forgery middleware, similar to CORS or authorization middleware, that will run anti-forgery token checks on endpoints with the appropriate metadata.

Proposed API

All APIs are net new.

// Assembly: Microsoft.AspNetCore.Antiforgery
namespace Microsoft.AspNetCore.Builder;

public static class AntiforgeryApplicationBuilderExtensions
{
  public static IApplicationBuilder UseAntiforgery(this IApplicationBuilder builder) { }
}

Note: The IAntiforgeryMetadata interface needs to reside in the Http.Abstractions assembly so that it can be consumed by the RequestDelegateFactory, the endpoint middleware, and Blazor SSR components.

// Assembly: Microsoft.AspNetCore.Http.Abstractions
namespace Microsoft.AspNetCore.Antiforgery;

public interface IAntiforgeryMetadata
{
  public bool Required { get; }
}

// Assembly: Microsoft.AspNetCore.Antiforgery
namespace Microsoft.AspNetCore.Antiforgery;

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
public class RequireAntiforgeryTokenAttribute(bool required = true) : Attribute, IAntiforgeryMetadata
{
  public bool Required { get; }
}

// Assembly: Microsoft.AspNetCore.Antiforgery
namespace Microsoft.AspNetCore.Antiforgery;

public interface IAntiforgeryValidationFeature
{
    public bool IsValid { get; }
    public AntiforgeryValidationException? Exception { get; }
}

Usage Examples

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAntiforgery();

var app = builder.Build();

app.UseAntiforgery();

// Anti-forgery token validation happens for this endpoint
app.MapPost("/todo", ([FromForm] Todo todo) => Results.Ok(todo));

app.Run();

Alternative Designs

This API proposal does not include public default implementations of antiforgery metadata types (e.g. AntiforgeryMetadata : IAntiforgeryMetadata) or extension methods for disabling anti-forgery.

Anti-forgery metadata with anti-forgery enabled is automatically added for endpoints that contain a source coming from a form. We anticipate that users will implement their own extension methods for disabling anti-forgery on a given endpoint.

public static RouteHandlerBuilder DisableAntiforgery(this RouteHandlerBuilder builder)
{
  builder.WithMetadata(new RequireAntiforgeryTokenAttribute(false));
  return builder;
}

Risks

Nothing ventured, nothing gained.

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[halter73]

What's the plan for getting the antiforgery token to the client? I realize that for minimal APIs in particular, this will probably need to be done with custom logic in the app, but IAntiForgeryTokenSet.GetAndStoreTokens(HttpContext) isn't exactly the most convenient API to use. See https://learn.microsoft.com/en-us/aspnet/core/security/anti-request-forgery?view=aspnetcore-7.0#generate-antiforgery-tokens-with-iantiforgery. Have we looked at improving that at all?

Anti-forgery metadata with anti-forgery enabled is automatically added for endpoints that contain a source coming from a form.

Will we throw at startup if there's anti-forgery metadata without any call to UseAntiforgery()? It seems like the right thing to do, but minimal added IFromFormMetadata in .NET 7, so it could be a big break.

[captainsafia]

What's the plan for getting the antiforgery token to the client?

Blazor forms support this via 78bec18. MVC has the existing infrastructure via @Html.BeginForm and @AntiforgeryToken.

Have we looked at improving that at all?

Not in the currently open PR, but I don't believe the changeset to support this will require API review so it should be feasible to add it later on.

Will we throw at startup if there's anti-forgery metadata without any call to UseAntiforgery()? I

Yes, similar to other security-related middlewares like CORS and auth.

[halter73]

API Review Notes:

• What about [ValidateAntiForgeryToken]?
  • We're still designing MVC integration.
  • There's no current plan to implement IAntiforgeryMetadata.
• What if I add [RequireAntiforgeryToken] to an MVC action or controller?
  • Like any other endpoint, it just works if you add the middleware which we'll validate.
• What if [ValidateAntiForgeryToken] to a minimal endpoint?
  • It doesn't work today, but it could be more surprising in the future.
  • We plan to throw at startup if this attribute is detected on a non-MVC endpoint.
    • This might also be hard to detect if [ValidateAntiForgeryToken] is added if it doesn't implement IAntiforgeryMetadata, but we could detect it at startup.
• "Validate" is more accurate the "Require" but we've burned the first name.
  • Could we re-use [ValidateAntiForgeryToken]? Are people going to actually write out this attribute much in practice? If not, we can just do the metadata interface with internal implementations. @javiercn Are you okay with keeping the attribute internal?
• Do we need to ensure that the IAntiforgeryValidationFeature is actually looked validate?
  • It could be bad if people incorrectly thought UseAntiforgery prevented invalid request from continuing at all.
  • Most endpoints would respect the feature, but what if you used MapPost(RequestDelegate)?
    • Documentation should make it clear you need to look at the feature
  • As a comparison, we'll yell at you if you call UseAuthentciation() without UseAuthorization()
  • We should ensure the form is poisoned for endpoints that require antiforgery tokens which are either not present or invalid
• Do we want an extension method for HttpContext or HttpRequest that allows you to check IAntiforgeryValidationFeature.IsValid
  • This could also be a non-extension method
  • We could add it later if we find consumers are need to resolve this feature a lot.
• IAntiforgeryMetadata could go in Microsoft.AspNetCore.Http.Metadata like some of the IFrom* metadata, but we think this is more similar to IAuthorizeData and belongs in a feature-specific namespace.
• Would we consider just adding the DisableAntiforgery() extension method?
  • If you're just doing bearer token auth or something like that, antiforgery isn't really necessary.
  • People with only non-browser clients could get really annoyed that the workaround requires implementing IAntiforgeryMetadata yourself and adding it to the endpoint metadata. @martincostello What do you think?

We're happy with the following, but we want more feedback if we also need the attribute and the extension method to disable it.

// Assembly: Microsoft.AspNetCore.Http.Abstractions
namespace Microsoft.AspNetCore.Antiforgery;

public interface IAntiforgeryMetadata
{
  public bool Required { get; }
}

// Assembly: Microsoft.AspNetCore.Antiforgery
namespace Microsoft.AspNetCore.Antiforgery;

public interface IAntiforgeryValidationFeature
{
    public bool IsValid { get; }
    public AntiforgeryValidationException? Exception { get; }
}

[martincostello]

People with only non-browser clients could get really annoyed that the workaround requires implementing IAntiforgeryMetadata yourself and adding it to the endpoint metadata. @martincostello What do you think?

Having a way to disable the antiforgery where you know it isn't a problem with a method that does it for you without having to implement an interface yourself sounds a good idea to me. I guess a middleground would be exposing a public type with that interface that you can use to do that but I think that would look a bit "ick".

app.MapPost("whatever", () => { }).DisableAntiforgery(); // 👍
app.MapPost("whatever", () => { }).AddMetadata(new DisableAntiforgeryAttribute()); // 👎

public sealed class DisableAntiforgeryAttribute
{
    public bool Required => false;
}

[captainsafia]

I guess a middleground would be exposing a public type with that interface that you can use to do that but I think that would look a bit "ick".

Interesting feedback because that's what I outlined as a note in the alternative designs section here.

I have no strong opposition to exposing a public method, other than the reservations I have about them in general after adding too many extension methods too soon for OpenAPI support 😅 .

It's a fairly cheap and non-consequential API to add so I don't see a harm in providing an extension method (and no public implementation of the interface).

[martincostello]

Just to clarify, I think that would only be "ick" if that's in the user's application code and they're implementing it themselves as they define their endpoints. I don't have a problem with that how it being implemented under the hood in the runtime 😄

[captainsafia]

Some updates to this API proposal:

1. To support being able to check the IAntiforgeryValidationFeature automatically when reading forms for minimal APIs, we need to move this from the Microsoft.AspNetCore.Antiforgeryassembly to the Microsoft.AspNetCore.Http.Features assembly. To avoid cyclic dependencies, the type of the Exception property needs to be changed.

-// Assembly: Microsoft.AspNetCore.Antiforgery
+ // Assembly: Microsoft.AspNetCore.Http.Features
namespace Microsoft.AspNetCore.Antiforgery;

public interface IAntiforgeryValidationFeature
{
    public bool IsValid { get; }
-    public AntiforgeryValidationException? Exception { get; }
+    public Exception? Exception { get; }
}

2. Add support for a DisableAntiforgery extension method to support opting out of the on-by-default antiforgery token check for certain endpoints.

namespace Microsoft.AspNetCore.Builder;

public static class RoutingEndpointConventionBuilderExtensions
{
    public static TBuilder DisableAntiforgery<TBuilder>(this TBuilder builder) where TBuilder : IEndpointConventionBuilder
}