Creating A Custom Authentication Filter In ASP.NET Core MVC

ASP.NET Core MVC provides several layers for securing an application, including authentication middleware, authorization policies, endpoint metadata and MVC filters. A custom filter becomes useful when a project has a rule that does not fit neatly into a standard policy, such as checking a tenant, validating a legacy session, or requiring a particular claim for selected controllers.

The important design decision is knowing what the filter should own. Authentication establishes who the caller is, while authorization decides whether that identity may access a resource. In most applications, the authentication handler should validate a cookie, bearer token or OpenID Connect response before an MVC filter applies extra business rules.

For Australian teams, that distinction also supports privacy and operational requirements. An application hosted in Sydney or Melbourne may need clear handling for personal information under the Privacy Act 1988 and the Australian Privacy Principles, while users in Perth, Brisbane or regional areas may experience different latency and connectivity. A small, predictable filter helps keep those concerns visible without turning every controller action into a security implementation.

Choose The Right Filter Boundary

A custom authentication filter is often described as a component that logs a user in. In ASP.NET Core MVC, that is usually an inaccurate boundary. Authentication handlers should validate credentials and create a ClaimsPrincipal; a filter can then challenge unauthenticated requests or reject identities that fail application-specific checks.

Use middleware when the rule applies to every request, including static files, minimal APIs or background endpoints. Use an authorization policy when the rule can be expressed through claims, roles or a custom AuthorizationHandler. An MVC authorization filter is appropriate when the decision depends on MVC metadata, controller conventions or a legacy application contract.

For example, a business portal might accept a valid cookie but require a tenant_id claim before opening an account screen. A filter can enforce that requirement consistently. It should not parse passwords, call an external identity provider on every request, or duplicate token validation already performed by the configured authentication scheme.

Understand The MVC Request Pipeline

The normal request path starts with routing and authentication middleware. Once the request reaches MVC, authorization filters run before model binding and action execution. This makes an authorization filter a useful gate for tenant checks or claim validation, because an invalid request can be stopped before application code performs expensive work.

A filter can set context.Result to a ChallengeResult when no authenticated identity exists. A challenge tells the configured authentication handler what to do: a cookie handler may redirect to a sign-in page, while a bearer handler normally returns HTTP 401. If the user is authenticated but lacks permission, the correct response is generally ForbidResult, which produces HTTP 403 or invokes the handler’s forbidden behaviour.

That distinction matters for browser applications and APIs. Redirecting a mobile client or JavaScript request to an HTML login page often creates confusing failures. Cookie authentication can be configured with separate redirect behaviour for API paths, or a bearer scheme can be selected for API controllers.

Build The Custom Authentication Filter

The following filter uses the configured cookie scheme to authenticate the request, then checks for a tenant claim. It implements IAsyncAuthorizationFilter, which places it at the authorization stage rather than waiting until the action filter stage.

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;

public sealed class RequireTenantFilter : IAsyncAuthorizationFilter
{
    private readonly IAuthenticationService _authentication;

    public RequireTenantFilter(IAuthenticationService authentication)
    {
        _authentication = authentication;
    }

    public async Task OnAuthorizationAsync(
        AuthorizationFilterContext context)
    {
        if (context.Filters.Any(f => f is IAllowAnonymousFilter))
            return;

        var result = await _authentication.AuthenticateAsync(
            context.HttpContext,
            "Cookies");

        if (!result.Succeeded || result.Principal?.Identity?.IsAuthenticated != true)
        {
            context.Result = new ChallengeResult("Cookies");
            return;
        }

        var tenantId = result.Principal.FindFirst("tenant_id")?.Value;

        if (string.IsNullOrWhiteSpace(tenantId))
        {
            context.Result = new ForbidResult("Cookies");
            return;
        }

        context.HttpContext.User = result.Principal;
        context.HttpContext.Items["TenantId"] = tenantId;
    }
}

The filter does not issue a token or redirect directly. It delegates that behaviour to the authentication scheme, which keeps the implementation aligned with the rest of the application. The IAllowAnonymousFilter check also prevents a login or health endpoint from being accidentally blocked.

Avoid placing sensitive values in HttpContext.Items unless the lifetime and visibility are understood. A tenant identifier is generally acceptable when it is already present as a trusted claim, but the application should still enforce tenant boundaries when querying data. A filter is a gate, not a substitute for row-level access control.

Register And Apply The Filter

Dependency injection is preferable to constructing a filter with new, because the filter may need a logger, a tenant service or an authentication component. A TypeFilterAttribute offers a convenient attribute-based application while allowing constructor dependencies to be resolved by the service container.

[AttributeUsage(
    AttributeTargets.Class | AttributeTargets.Method,
    AllowMultiple = false)]
public sealed class RequireTenantAttribute : TypeFilterAttribute
{
    public RequireTenantAttribute()
        : base(typeof(RequireTenantFilter))
    {
    }
}

Apply it to a controller or a particular action:

[RequireTenant]
public class ReportsController : Controller
{
    public IActionResult Index()
    {
        var tenantId = HttpContext.Items["TenantId"] as string;
        return View(new ReportsViewModel(tenantId!));
    }
}

The application must register and configure the authentication scheme before the filter runs. With cookie authentication, UseAuthentication() must appear before UseAuthorization() and before endpoint mapping in the request pipeline.

builder.Services
    .AddAuthentication("Cookies")
    .AddCookie("Cookies", options =>
    {
        options.LoginPath = "/account/sign-in";
    });

builder.Services.AddAuthorization();
builder.Services.AddControllersWithViews();

var app = builder.Build();

app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();

app.MapDefaultControllerRoute();
app.Run();

If every action in a controller needs the rule, apply the attribute at controller level. If most of the application requires it, a policy or a global authorization convention is usually easier to audit than attaching attributes across dozens of classes.

Handle Claims And Failure Paths

Claims should be treated as statements issued by a trusted authentication system, not as values supplied directly by a browser. A tenant claim should be created after the identity provider or account service has verified the user’s relationship with that tenant. If a user can switch tenants, the active tenant should be selected through a controlled workflow and revalidated against server-side membership data.

The filter should return the smallest useful amount of information. A 401 response means the request lacks a valid authenticated identity; a 403 response means an identity exists but is not permitted. Avoid revealing whether a tenant, account or internal role exists, since detailed errors can help an attacker map the system.

Logging should record the route, correlation identifier, authentication outcome and reason code, without writing access tokens, session cookies or unnecessary personal data. This is particularly relevant for organisations handling customer records under Australian privacy obligations. Retention schedules and access controls should cover security logs as well as application databases.

Protect APIs And Distributed Deployments

A filter that works for an MVC page may be unsuitable for a JSON endpoint. API clients normally expect a status code and structured response rather than a sign-in redirect. For mixed applications, use explicit authentication schemes and test both browser and API paths so a failed request behaves correctly for each client.

Authentication state also becomes more complicated when an application runs across multiple instances. Containerised .NET workloads deployed through Azure Kubernetes Service need consistent cookie configuration, key-ring persistence and clock synchronisation. The AKS orchestration guide provides relevant context for teams designing that deployment model.

Cookie data protection keys must be shared between instances, or a user authenticated by one pod may appear logged out when the next request reaches another pod. Token validation must use consistent issuer, audience and signing-key settings. A filter should remain stateless where possible, relying on the authenticated principal and a short-lived service lookup rather than storing security decisions in process memory.

Australian applications may also need to consider where identity and audit data are processed. A Sydney-based deployment does not automatically satisfy every contractual or regulatory requirement, so data residency, provider terms and cross-border transfers should be assessed with the organisation’s privacy team.

Test And Operate Safely

Tests should cover an unauthenticated request, an authenticated user without a tenant claim, a valid tenant identity and an anonymous endpoint. Include checks for both ChallengeResult and ForbidResult, because confusing those outcomes can cause broken redirects or misleading API responses.

Integration tests should run through the real authentication middleware rather than mocking only the filter. Verify that claims are populated as expected, that the filter executes before the controller action, and that AllowAnonymous remains effective for sign-in, password recovery and health endpoints.

Operational tests should include expired cookies, rotated signing keys, multiple application instances and a clock difference between servers. Load testing from Australian locations such as Sydney, Melbourne and Perth can reveal latency in remote identity calls. The final design should make authentication central, authorization explicit and custom MVC behaviour narrow enough to review during security audits.