Site Home
Guides
LoginTry for Free

Add CSRF Middleware

Create a middleware to protect your app from Cross Site Request Forgery (CSRF) attacks.

Suggest Edits

When using the Backend Server Integration Pattern for your application, you must protect against CSRF attacks which can trick authenticated users into unknowingly submitting malicious requests.


Create CSRF Middleware

To prevent this, implement a CSRF middleware to protect your application. View our documentation for more details about this topic.

📘

Custom CSRF Protection for Modern Web Applications

ASP.NET Core's built-in antiforgery implementation is designed for traditional form posts and requires extra code for API/SPA scenarios. The approach outlined on this page is more streamlined for modern applications as it automatically makes the CSRF token available to JavaScript clients without additional configuration.


Add CSRF Helper Functions

You'll need a couple functions for use both within a CSRF middleware that you will create as well as in your Callback endpoint (e.g. CsrfUtils.cs).

// CsrfUtils.cs

using System.Security.Cryptography;
using System.Text;

using Microsoft.AspNetCore.Http;

public static class CsrfUtils
{
    private const string _xsrfCookieName = "XSRF-TOKEN";
    private const string _xsrfTokenHeaderName = "X-XSRF-TOKEN";

    // Generates new CSRF tokens.
    public static string GenerateCsrfSecret()
    {
      var secretBytes = RandomNumberGenerator.GetBytes(32);
      return Convert.ToBase64String(secretBytes);
    }

    // Updates the CSRF cookie with a new CSRF token.
    public static void UpdateCsrfTokenCookie(HttpContext httpContext, string csrfSecret)
    {
        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(csrfSecret));
        var tokenBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(csrfSecret));
        var csrfToken = Convert.ToBase64String(tokenBytes);

        httpContext.Response.Cookies.Append(_xsrfCookieName, csrfToken, new CookieOptions
        {
            HttpOnly = false, // Must be false so that your frontend AJAX client can access the value.
            Secure = false, // IMPORTANT: set to true for production environments!!
            SameSite = SameSiteMode.Strict, // If dealing with CORS, you may need to use "Lax" mode.
            Path = "/",
            // e.g. 30 minutes; Ideally, it should match your access token expiration.
            Expires = DateTimeOffset.UtcNow.AddMinutes(30),
            MaxAge = TimeSpan.FromMinutes(30)
        });
    }

    // Verifies that the CSRF token in the request header was cryptographically generated from the
    // CSRF secret in your application session.
    public static bool IsCsrfTokenValid(HttpContext httpContext, string csrfSecret)
    {
        var csrfToken = string.Empty;
        if (httpContext.Request.Headers.TryGetValue(_xsrfTokenHeaderName, out var token))
        {
            csrfToken = token.FirstOrDefault()?.ToString() ?? string.Empty;
        }

        if (string.IsNullOrEmpty(csrfSecret) || string.IsNullOrEmpty(csrfToken))
        {
            return false;
        }

        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(csrfSecret));
        var computedHash = hmac.ComputeHash(Encoding.UTF8.GetBytes(csrfSecret));
        var computedToken = Convert.ToBase64String(computedHash);
        return csrfToken == computedToken;
    }
}

Implement Middleware

Create a new file for the following CSRF middleware (e.g. CsrfMiddleware.cs).

// CsrfMiddleware.cs
using Microsoft.AspNetCore.Http;
using Wristband.AspNet.Auth;

public class CsrfMiddleware
{
    private readonly RequestDelegate _next;

    public CsrfMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        // Skip the middleware for unprotected endpoints
        var endpoint = context.GetEndpoint();
        if (endpoint?.Metadata.GetMetadata<RequireWristbandAuth>() == null)
        {
            await _next(context);
            return;
        }

        // Validate the CSRF secret from the session
        var csrfSecret = context.User.Claims.FirstOrDefault(c => c.Type == "csrfSecret")?.Value;
        if (string.IsNullOrEmpty(csrfSecret) || !CsrfUtils.IsCsrfTokenValid(context, csrfSecret))
        {
            context.Response.StatusCode = StatusCodes.Status403Forbidden;
            return;
        }

        // After validation, a new CSRF token is generated and set into the CSRF response cookie.
        CsrfUtils.UpdateCsrfTokenCookie(context, csrfSecret);
        await _next(context);
    }
}

Finally, configure the middleware in your Program.cs file:

// Program.cs

...

app.UseAuthentication();
app.UseMiddleware<AuthMiddleware>();
app.UseMiddleware<CsrfMiddleware>(); // This comes after auth middleware in the order.

// Protected routes below...

...


Protect the Session Route

You will need to apply the CSRF middleware to any protected routes that also require an authenticated user session to access. The existing RequireWristbandAuth attribute already handles authentication requirements, and you can extend it to include CSRF validation as well. While you could create a separate RequireCsrf attribute, this is generally unnecessary since protected endpoints require both authentication and CSRF protection.

// AuthRoutes.cs
using System.Security.Claims;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Wristband.AspNet.Auth;

...

// Session endpoint
app.MapGet("/session", (HttpContext httpContext) =>
{
    ...
})
// You can use this attribute for both auth and CSRF.
.WithMetadata(new RequireWristbandAuth());

...

📘

Put All Protected Routes Behind Middleware

Protect all authenticated routes - not just the Session endpoint - with the CSRF middleware. Add the attributes to any endpoint that requires an authenticated user session.

The Login, Callback, and Logout routes are meant to be accessed by unauthenticated users. Avoid sticking the CSRF middleware in front of those routes.

Updated about 1 month ago

What’s Next

Next, let's enhance the auth routes to add CSRF management logic.