Implement ASP.NET Core antiforgery protection with cryptographic double-submit pattern (#709)

Implement antiforgery protection using ASP.NET Core’s built-in
cryptographic double-submit pattern to prevent CSRF (Cross-Site Request
Forgery) attacks. This mechanism generates a secure, `HttpOnly` cookie
containing a server-side token and requires an `x-xsrf-token` Header in
non-GET requests. The token includes the user's `ClaimUid` and is
validated on every request that mutates data (`POST`, `PUT`, `DELETE`,
etc.)

A new antiforgery middleware has been introduced to enforce this
validation across the application, except for explicitly excluded
endpoints like the Application Insights tracking API. The
`upload-avatar` endpoint has been updated to remove the previous
antiforgery bypass.

Additional security improvements:
- Antiforgery cookies now use the `__Host_` prefix. This special prefix
ensures that modern browsers enforce the cookie to be sent only over
HTTPS and only to the same origin, providing an additional layer of
security.
- Requests failing antiforgery validation return a `400 Bad Request`
response with a traceable error message.

To simplify automated testing, antiforgery validation can be disabled
using an environment variable, allowing tests to run without requiring a
valid token. Setting up the cryptographic double-submit pattern in tests
would add unnecessary complexity.

### Downstream projects  

The `refresh_token` and `access_token` cookie names have been changed to
`__Host_refresh_token` and `__Host_access_token`. As a result:
- All logged-in users will be required to reauthenticate after this
release.
- The previous `refresh_token` cookie will remain orphaned in the
browser but will no longer be used.

Add the following to `EndpointBaseTest.cs` to bypass antiforgery
validation in test environments:

```csharp
// Set the environment variable to bypass antiforgery validation on the server. ASP.NET uses a cryptographic
// double-submit pattern that encrypts the user's ClaimUid in the token, which is complex to replicate in tests
Environment.SetEnvironmentVariable("BypassAntiforgeryValidation", "true");
```

### Checklist

- [x] I have added tests, or done manual regression tests
- [x] I have updated the documentation, if necessary

Author: tjementum

application/account-management/Api/Endpoints/UserEndpoints.cs

@@ -45,7 +45,7 @@ public void MapEndpoints(IEndpointRouteBuilder routes)
 
         group.MapPost("/me/update-avatar", async Task<ApiResult> (IFormFile file, IMediator mediator)
             => await mediator.Send(new UpdateAvatarCommand(file.OpenReadStream(), file.ContentType))
-        ).DisableAntiforgery(); // Disable anti-forgery until we implement it
+        );
 
         group.MapDelete("/me/remove-avatar", async Task<ApiResult> (IMediator mediator)
             => await mediator.Send(new RemoveAvatarCommand())

application/account-management/Tests/EndpointBaseTest.cs

@@ -105,6 +105,10 @@ protected EndpointBaseTest()
         var memberAccessToken = AccessTokenGenerator.Generate(DatabaseSeeder.Tenant1Member.Adapt<UserInfo>());
         AuthenticatedMemberHttpClient = _webApplicationFactory.CreateClient();
         AuthenticatedMemberHttpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", memberAccessToken);
+
+        // Set the environment variable to bypass antiforgery validation on the server. ASP.NET uses a cryptographic
+        // double-submit pattern that encrypts the user's ClaimUid in the token, which is complex to replicate in tests
+        Environment.SetEnvironmentVariable("BypassAntiforgeryValidation", "true");
     }
 
     protected SqliteConnection Connection { get; }

application/account-management/WebApp/shared/lib/api/client.ts

@@ -11,6 +11,23 @@ const apiClient = createFetchClient<paths>({
 });
 apiClient.use(createAuthenticationMiddleware());
 
+// Add middleware to include antiforgery token only for non-GET requests
+apiClient.use({
+  onRequest: (params) => {
+    const request = params.request;
+    if (request instanceof Request && request.method !== "GET") {
+      request.headers.set("x-xsrf-token", getAntiforgeryToken());
+    }
+    return request;
+  }
+});
+
+// Get the antiforgery token from the meta tag
+const getAntiforgeryToken = () => {
+  const metaTag = document.querySelector('meta[name="antiforgeryToken"]');
+  return metaTag?.getAttribute("content") ?? "";
+};
+
 export const api = createClient(apiClient);
 
 export type Schemas = components["schemas"];

application/back-office/Tests/EndpointBaseTest.cs

@@ -105,6 +105,10 @@ protected EndpointBaseTest()
         var memberAccessToken = AccessTokenGenerator.Generate(DatabaseSeeder.Tenant1Member.Adapt<UserInfo>());
         AuthenticatedMemberHttpClient = _webApplicationFactory.CreateClient();
         AuthenticatedMemberHttpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", memberAccessToken);
+
+        // Set the environment variable to bypass antiforgery validation on the server. ASP.NET uses a cryptographic
+        // double-submit pattern that encrypts the user's ClaimUid in the token, which is complex to replicate in tests
+        Environment.SetEnvironmentVariable("BypassAntiforgeryValidation", "true");
     }
 
     protected SqliteConnection Connection { get; }

application/shared-kernel/SharedKernel/Antiforgery/AntiforgeryMiddleware.cs

@@ -0,0 +1,47 @@
+using Microsoft.AspNetCore.Antiforgery;
+using Microsoft.AspNetCore.Http;
+
+namespace PlatformPlatform.SharedKernel.Antiforgery;
+
+public sealed class AntiforgeryMiddleware(IAntiforgery antiforgery, ILogger<AntiforgeryMiddleware> logger) : IMiddleware
+{
+    public async Task InvokeAsync(HttpContext context, RequestDelegate next)
+    {
+        if (context.GetEndpoint()?.Metadata.GetMetadata<IAntiforgeryMetadata>()?.RequiresValidation == false)
+        {
+            // Skip validation for endpoints with disabled antiforgery
+            await next(context);
+            return;
+        }
+
+        if (bool.TryParse(Environment.GetEnvironmentVariable("BypassAntiforgeryValidation"), out _))
+        {
+            logger.LogDebug("Bypassing antiforgery validation due to environment variable setting");
+            await next(context);
+            return;
+        }
+
+        if (!await antiforgery.IsRequestValidAsync(context))
+        {
+            var traceId = Activity.Current?.Id ?? context.TraceIdentifier;
+
+            logger.LogWarning(
+                "Antiforgery validation failed for {Method} {Path}. TraceId: {TraceId}",
+                context.Request.Method,
+                context.Request.Path,
+                traceId
+            );
+
+            await Results.Problem(
+                title: "Invalid Antiforgery Token",
+                detail: "Antiforgery validation failed for request.",
+                statusCode: StatusCodes.Status400BadRequest,
+                extensions: new Dictionary<string, object?> { { "traceId", traceId } }
+            ).ExecuteAsync(context);
+
+            return;
+        }
+
+        await next(context);
+    }
+}

application/shared-kernel/SharedKernel/Authentication/AuthenticationTokenHttpKeys.cs

@@ -2,13 +2,18 @@ namespace PlatformPlatform.SharedKernel.Authentication;
 
 public static class AuthenticationTokenHttpKeys
 {
-    public const string RefreshTokenCookieName = "refresh_token";
-
-    public const string AccessTokenCookieName = "access_token";
-
     public const string RefreshTokenHttpHeaderKey = "x-refresh-token";
 
     public const string AccessTokenHttpHeaderKey = "x-access-token";
 
+    public const string AntiforgeryTokenHttpHeaderKey = "x-xsrf-token";
+
     public const string RefreshAuthenticationTokensHeaderKey = "x-refresh-authentication-tokens-required";
+
+    // __Host prefix ensures the cookie is sent only to the host, requires Secure, HTTPS, Path=/ and no Domain specified
+    public const string RefreshTokenCookieName = "__Host_Refresh_Token";
+
+    public const string AccessTokenCookieName = "__Host_Access_Token";
+
+    public const string AntiforgeryTokenCookieName = "__Host_Xsrf_Token";
 }

application/shared-kernel/SharedKernel/Configuration/ApiDependencyConfiguration.cs

@@ -5,6 +5,8 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using NJsonSchema.Generation;
+using PlatformPlatform.SharedKernel.Antiforgery;
+using PlatformPlatform.SharedKernel.Authentication;
 using PlatformPlatform.SharedKernel.Endpoints;
 using PlatformPlatform.SharedKernel.ExecutionContext;
 using PlatformPlatform.SharedKernel.Middleware;
@@ -54,11 +56,18 @@ public static IServiceCollection AddApiServices(this IServiceCollection services
             .AddExceptionHandler<GlobalExceptionHandler>()
             .AddTransient<TelemetryContextMiddleware>()
             .AddTransient<ModelBindingExceptionHandlerMiddleware>()
+            .AddTransient<AntiforgeryMiddleware>()
             .AddProblemDetails()
             .AddEndpointsApiExplorer()
             .AddApiEndpoints(assemblies)
             .AddOpenApiConfiguration(assemblies)
             .AddAuthConfiguration()
+            .AddAntiforgery(options =>
+                {
+                    options.Cookie.Name = AuthenticationTokenHttpKeys.AntiforgeryTokenCookieName;
+                    options.HeaderName = AuthenticationTokenHttpKeys.AntiforgeryTokenHttpHeaderKey;
+                }
+            )
             .AddHttpForwardHeaders();
     }
 
@@ -86,6 +95,8 @@ public static WebApplication UseApiServices(this WebApplication app)
             .UseForwardedHeaders()
             .UseAuthentication() // Must be above TelemetryContextMiddleware to ensure authentication happens first
             .UseAuthorization()
+            .UseAntiforgery()
+            .UseMiddleware<AntiforgeryMiddleware>()
             .UseMiddleware<TelemetryContextMiddleware>() // It must be above ModelBindingExceptionHandlerMiddleware to ensure that model binding problems are annotated correctly
             .UseMiddleware<ModelBindingExceptionHandlerMiddleware>() // Enable support for proxy headers such as X-Forwarded-For and X-Forwarded-Proto. Should run before other middleware
             .UseOpenApi(options => options.Path = "/openapi/v1.json"); // Adds the OpenAPI generator that uses the ASP. NET Core API Explorer

application/shared-kernel/SharedKernel/Endpoints/TrackEndpoints.cs

@@ -20,7 +20,7 @@ public class TrackEndpoints : IEndpoints
     // </summary>
     public void MapEndpoints(IEndpointRouteBuilder routes)
     {
-        routes.MapPost("/api/track", Track).AllowAnonymous();
+        routes.MapPost("/api/track", Track).AllowAnonymous().DisableAntiforgery();
     }
 
     [OpenApiIgnore]

application/shared-kernel/SharedKernel/SinglePageApp/SinglePageAppFallbackExtensions.cs

@@ -1,5 +1,6 @@
 using System.Text.Encodings.Web;
 using System.Text.Json;
+using Microsoft.AspNetCore.Antiforgery;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.AspNetCore.Http;
@@ -38,7 +39,12 @@ public static IApplicationBuilder UseSinglePageAppFallback(this WebApplication a
             }
         );
 
-        app.MapFallback((HttpContext context, IExecutionContext executionContext, SinglePageAppConfiguration singlePageAppConfiguration) =>
+        app.MapFallback((
+                HttpContext context,
+                IExecutionContext executionContext,
+                IAntiforgery antiforgery,
+                SinglePageAppConfiguration singlePageAppConfiguration
+            ) =>
             {
                 if (context.Request.Path.Value?.Contains("/api/", StringComparison.OrdinalIgnoreCase) == true ||
                     context.Request.Path.Value?.Contains("/internal-api/", StringComparison.OrdinalIgnoreCase) == true)
@@ -50,7 +56,10 @@ public static IApplicationBuilder UseSinglePageAppFallback(this WebApplication a
 
                 SetResponseHttpHeaders(singlePageAppConfiguration, context.Response.Headers, "text/html; charset=utf-8");
 
-                var html = GetHtmlWithEnvironment(singlePageAppConfiguration, executionContext.UserInfo);
+                var antiforgeryHttpHeaderToken = GenerateAntiforgeryTokens(antiforgery, context);
+
+                var html = GetHtmlWithEnvironment(singlePageAppConfiguration, executionContext.UserInfo, antiforgeryHttpHeaderToken);
+
                 return context.Response.WriteAsync(html);
             }
         );
@@ -62,7 +71,11 @@ public static IApplicationBuilder UseSinglePageAppFallback(this WebApplication a
             .UseRequestLocalization(SinglePageAppConfiguration.SupportedLocalizations);
     }
 
-    private static void SetResponseHttpHeaders(SinglePageAppConfiguration singlePageAppConfiguration, IHeaderDictionary responseHeaders, StringValues contentType)
+    private static void SetResponseHttpHeaders(
+        SinglePageAppConfiguration singlePageAppConfiguration,
+        IHeaderDictionary responseHeaders,
+        StringValues contentType
+    )
     {
         // No cache headers
         responseHeaders.Append("Cache-Control", "no-cache, no-store, must-revalidate");
@@ -82,7 +95,32 @@ private static void SetResponseHttpHeaders(SinglePageAppConfiguration singlePage
         responseHeaders.Append("Content-Type", contentType);
     }
 
-    private static string GetHtmlWithEnvironment(SinglePageAppConfiguration singlePageAppConfiguration, UserInfo userInfo)
+    private static string GenerateAntiforgeryTokens(IAntiforgery antiforgery, HttpContext context)
+    {
+        // ASP.NET Core antiforgery system uses a cryptographic double-submit pattern with two tokens:
+        // - A secret cookie token that only the server can read (session-based)
+        // - A public request token that the SPA sends as a header for state-changing requests like POST/PUT/DELETE
+
+        var antiforgeryTokenSet = antiforgery.GetAndStoreTokens(context);
+
+        if (antiforgeryTokenSet.CookieToken is not null)
+        {
+            // A new antiforgery cookie is only generated once, as it must remain constant across browser tabs to avoid validation failures
+            context.Response.Cookies.Append(
+                AuthenticationTokenHttpKeys.AntiforgeryTokenCookieName,
+                antiforgeryTokenSet.CookieToken!,
+                new CookieOptions { HttpOnly = true, Secure = true, SameSite = SameSiteMode.Strict, Path = "/" }
+            );
+        }
+
+        return antiforgeryTokenSet.RequestToken!;
+    }
+
+    private static string GetHtmlWithEnvironment(
+        SinglePageAppConfiguration singlePageAppConfiguration,
+        UserInfo userInfo,
+        string antiforgeryHttpHeaderToken
+    )
     {
         var userInfoEncoded = JsonSerializer.Serialize(userInfo, SinglePageAppConfiguration.JsonHtmlEncodingOptions);
 
@@ -92,6 +130,7 @@ private static string GetHtmlWithEnvironment(SinglePageAppConfiguration singlePa
         html = html.Replace("%ENCODED_RUNTIME_ENV%", singlePageAppConfiguration.StaticRuntimeEnvironmentEscaped);
         html = html.Replace("%ENCODED_USER_INFO_ENV%", userInfoEscaped);
         html = html.Replace("%LOCALE%", userInfo.Locale);
+        html = html.Replace("%ANTIFORGERY_TOKEN%", antiforgeryHttpHeaderToken);
 
         foreach (var variable in singlePageAppConfiguration.StaticRuntimeEnvironment)
         {

application/shared-webapp/build/plugin/RunTimeEnvironmentPlugin.ts

@@ -48,7 +48,8 @@ export function RunTimeEnvironmentPlugin<E extends {} = Record<string, unknown>>
             // Define the runtime environment variables as part of the template
             meta: {
               runtimeEnv: "%ENCODED_RUNTIME_ENV%",
-              userInfoEnv: "%ENCODED_USER_INFO_ENV%"
+              userInfoEnv: "%ENCODED_USER_INFO_ENV%",
+              antiforgeryToken: "%ANTIFORGERY_TOKEN%"
             },
             // Add the CDN URL placeholder to the script and link tags in the template file
             tags(tags) {