Custom Authorization Filter in ASP.NET Core Web API

Back to: ASP.NET Core Web API Tutorials

Custom Authorization Filter in ASP.NET Core Web API

In this article, I will discuss How to Create Custom Authorization Filters in ASP.NET Core Web API Applications with Examples. Please read our previous article discussing Authorization Filters in ASP.NET Core Web API Applications.

What is a Custom Authorization Filter?

In ASP.NET Core Web API, authorization filters are components that execute early in the HTTP request pipeline to determine whether a user has permission to access a specific API endpoint (a controller or action method). This step occurs after authentication (which verifies the user’s identity) but before the actual controller method runs.

The framework provides a built-in [Authorize] attribute that allows you to enforce authorization based on simple criteria like roles, policies, or claims. For instance, you might restrict an endpoint so that only users with the “Admin” role can access it.

However, many real-world applications require more complex and custom business rules that [Authorize] cannot directly express. This is where Custom Authorization Filters come in:

  • They allow you to write custom logic to decide who gets access.
  • You can inspect any user property or claim.
  • You can enforce additional conditions such as subscription status, account verification, or custom flags.
  • You can define how to handle unauthorized users, for example, returning a custom JSON message or a specific HTTP status code.
Real-Time Example

Imagine an API with premium features accessible only to users whose email addresses are verified. Even if a user is authenticated, they should not access these features unless their email is verified. The [Authorize] attribute alone cannot check email verification status because it only supports roles and policies. So, you create a Custom Authorization Filter that:

  • Reads a custom claim like “IsEmailVerified” from the user’s JWT token.
  • Returns 403 Forbidden if the email is not verified.
  • Otherwise, allows the request to proceed.
Different Ways to Implement a Custom Authorization Filter in ASP.NET Core:

There are 3 different ways to create a Custom Authorization Filter in ASP.NET Core Web API. They are as follows:

  • Implement IAuthorizationFilter (Synchronous): Create a class implementing this interface and override OnAuthorization for synchronous checks.
  • Implement IAsyncAuthorizationFilter (Asynchronous): For async checks like database lookups, implement this interface and override OnAuthorizationAsync.
  • Inherit from AuthorizeAttribute: Create a custom attribute by extending AuthorizeAttribute. This allows you to inject extra checks alongside built-in role/policy mechanisms.
ASP.NET Core Web API Project Setup

First, create a new ASP.NET Core Web API Project with the name CustomAuthFilterDemo. We will use JWT (JSON Web Tokens) for authentication. Please install the following JwtBearer NuGet Package by executing the below command in the Package Manager Console.

Install-Package Microsoft.AspNetCore.Authentication.JwtBearer

Add JWT Secret in Configuration:

Please modify the appsettings.json file as follows. Here, we are adding a key that will be used to generate and validate the JWT token. The SecretKey will also be used to sign JWT tokens. In production, use environment variables or secret managers for better security.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "JwtSettings": {
    "SecretKey": "d3011f8b98bbc1aa1c4ff1a7d4864fc72d9ee150bd682cf4e612d6321f57821d"
  }
}

Please use the following site to generate the JWT Secret key.

https://jwtsecret.com/generate

Configure JWT Authentication in the Program.cs:

Modify Program.cs as follows to add JWT authentication:

using CustomAuthFilterDemo.Filters;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using System.Text;
namespace CustomAuthFilterDemo
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);

            // Read the JWT secret key from the appsettings.json configuration file.
            // This key will be used to sign and validate JWT tokens.
            var jwtSettings = builder.Configuration.GetSection("JwtSettings");
            var secretKey = jwtSettings["SecretKey"] ?? "d3011f8b98bbc1aa1c4ff1a7d4864fc72d9ee150bd682cf4e612d6321f57821d";

            // Register MVC controllers with the application.
            // Also, configure JSON options to keep property names as defined in the C# models.
            builder.Services.AddControllers()
            .AddJsonOptions(options =>
            {
                // Disable camelCase in JSON output, preserve property names as defined in C# classes
                options.JsonSerializerOptions.PropertyNamingPolicy = null;
            });

            // Register Authentication with JWT Bearer scheme
            builder.Services.AddAuthentication(options =>
            {
                // These two options set JWT Bearer as the default scheme for authentication and challenge.
                // This means the middleware will look for JWT tokens in incoming requests by default.

                // Set the default scheme used for authentication — this means how the app will try to authenticate incoming requests
                options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;

                // Set the default challenge scheme — this is how the app will challenge unauthorized requests
                options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
            })
            .AddJwtBearer(options =>
            {
                // Configure parameters for validating incoming JWT tokens
                options.TokenValidationParameters = new TokenValidationParameters
                {
                    // Do NOT validate the issuer (the token's "iss" claim)
                    ValidateIssuer = false,

                    // Do NOT validate the audience (the token's "aud" claim)
                    ValidateAudience = false,

                    // Ensure the token's signature matches the signing key (to verify token integrity)
                    ValidateIssuerSigningKey = true,

                    // The key used to sign tokens — must match the key used to generate tokens
                    IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(secretKey)) // Use a symmetric key from configuration for token validation.
                };
            });

            builder.Services.AddEndpointsApiExplorer();
            builder.Services.AddSwaggerGen();
            
            var app = builder.Build();

            // Configure the HTTP request pipeline.
            if (app.Environment.IsDevelopment())
            {
                app.UseSwagger();
                app.UseSwaggerUI();
            }

            app.UseHttpsRedirection();

            // Add authentication middleware to validate JWT tokens in incoming requests.
            app.UseAuthentication();  // MUST come before UseAuthorization

            // Add authorization middleware to check user permissions for accessing resources.
            app.UseAuthorization();

            app.MapControllers();

            app.Run();
        }
    }
}
Create the User Model

First, create a folder named Models at the project root directory. Then, inside the Models folder, add a class named User.cs and copy and paste the following code. We will store the user list in memory objects.

namespace CustomAuthFilterDemo.Models
{
    public class User
    {
        public int Id { get; set; }
        public string Email { get; set; } = string.Empty;
        public string Password { get; set; } = string.Empty;

        // IsEmailVerified, True: Verified and False: Not Verified
        public bool IsEmailVerified { get; set; }

        // KYC Status, True: Verified and False: Not Verified
        public bool KYCStatus { get; set; }

        // Roles assigned to the user, comma-separated
        public string Roles { get; set; } = string.Empty;
    }
}
Creating LoginDTO:

To generate the JWT Token, we need the user’s email and password; for this, we need a DTO. So, inside the Models folder, create a class file named LoginDTO.cs and then copy and paste the following code.

using System.ComponentModel.DataAnnotations;
namespace CustomAuthFilterDemo.Models
{
    public class LoginDTO
    {
        [Required(ErrorMessage = "Email is required.")]
        [EmailAddress(ErrorMessage = "Invalid email format.")]
        public string Email { get; set; } = null!;

        [Required(ErrorMessage = "Password is required.")]
        [MinLength(6, ErrorMessage = "Password must be at least 6 characters long.")]
        public string Password { get; set; } = null!;
    }
}
Creating User Service:

Create a class file named UserService.cs and then copy and paste the following code. This will be our in-memory data store. In real time, you need to work with a database, but for simplicity, we are hardcoding the data.

namespace CustomAuthFilterDemo.Models
{
    public class UserService
    {
        // In-memory hardcoded users list for demo (simulate a user database)
        private readonly List<User> _users = new List<User>()
        {
            new User {Id = 1, Email ="Alice@Example.com",  Password = "alice123", 
                IsEmailVerified = true, KYCStatus = true, Roles = "Admin,Manager"  },
            new User {Id = 2, Email ="Bob@Example.com",  Password = "bob123", 
                IsEmailVerified = true, KYCStatus = false, Roles = "User"  },
            new User {Id = 3, Email ="Charlie@Example.com", Password = "charlie123", 
                IsEmailVerified = false, KYCStatus = false, Roles = "Manager,User"  }
        };

        public User? ValidateUser(LoginDTO loginDTO)
        {
            // Find a user in our hardcoded list that matches the provided email and password (case-insensitive email check)
            return _users.FirstOrDefault(u =>
                u.Email.Equals(loginDTO.Email, StringComparison.OrdinalIgnoreCase)
                && u.Password == loginDTO.Password);
        }

        public async Task<bool> IsKycVerifiedAsync(int userId)
        {
            var user = _users.FirstOrDefault(x => x.Id == userId && x.KYCStatus == true);

            // Simulate async DB/API call
            await Task.Delay(TimeSpan.FromSeconds(1));

            if(user != null)
            {
                return user.KYCStatus;
            }

            return false;
        }
    }
}
Register the User Service in the Dependency Injection Container

Add this to the Program.cs before builder.Build():

builder.Services.AddScoped<UserService>();

Create AuthController for Token Generation

Create a new API Empty Controller named AuthController within the Controllers folder, and then copy and paste the following code. The user needs to call the Login endpoint by providing valid credentials to get the JWT token.

using CustomAuthFilterDemo.Models;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.IdentityModel.Tokens;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;
namespace CustomAuthFilterDemo.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class AuthController : ControllerBase
    {
        private readonly IConfiguration _configuration;
        private UserService _userService;

        public AuthController(IConfiguration configuration, UserService userService)
        {
            _configuration = configuration;
            _userService = userService;
        }

        // This endpoint is accessible by anyone, even unauthenticated users
        [HttpPost("login")]
        [AllowAnonymous]
        public IActionResult Login([FromBody] LoginDTO login)
        {
            // Find a user in our hardcoded list that matches the provided email and password (case-insensitive email check)
            var user = _userService.ValidateUser(login);

            if (user == null)
            {
                // If no matching user, credentials are invalid — respond with 401 Unauthorized status code
                return Unauthorized("Invalid username or password");
            }

            // Create a list of claims to embed inside the JWT token for this user
            var claims = new List<Claim>
            {
                // Claim to identify the user by their email address
                new Claim(ClaimTypes.Name, user.Email),

                // Custom claim with user's unique Id
                new Claim("UserId", user.Id.ToString()),

                 // Custom claim with user's Email Verified Status
                new Claim("IsEmailVerified", user.IsEmailVerified.ToString()),
            };

            // Add claims for each role assigned to the user (roles are comma-separated string)
            var roles = user.Roles.Split(',', StringSplitOptions.RemoveEmptyEntries);
            foreach (var role in roles)
            {
                // Add a role claim for each role
                claims.Add(new Claim(ClaimTypes.Role, role.Trim()));
            }

            // Generate a symmetric security key from the secret configured in appsettings.json
            var secretKey = _configuration.GetValue<string>("JwtSettings:SecretKey") ?? "d3011f8b98bbc1aa1c4ff1a7d4864fc72d9ee150bd682cf4e612d6321f57821d";
            var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(secretKey));

            // Specify signing credentials using HMAC SHA256 algorithm and the generated key
            var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

            // Create a JWT token embedding the claims, with no issuer/audience for simplicity, and expiration set to 30 minutes from now
            var token = new JwtSecurityToken(
                issuer: null, // No specific issuer specified.
                audience: null, // No specific audience specified.
                claims: claims,
                expires: DateTime.UtcNow.AddMinutes(30), // Token valid for 30 minutes
                signingCredentials: creds);

            // Serialize the JWT token to a string
            var tokenString = new JwtSecurityTokenHandler().WriteToken(token);

            // Return the JWT token string as JSON to the client
            return Ok(new { Token = tokenString });
        }
    }
}
Creating a Custom Authorization Filter using IAuthorizationFilter

The IAuthorizationFilter is an interface in ASP.NET Core used to create synchronous custom authorization filters. Filters implementing this interface run early in the request pipeline, before the controller action executes, allowing us to check if the user is authorized to access the resource.

First, create a folder named Filters at the project root directory. Then, inside the Filters folder, create a class file named EmailVerifiedAuthorizationFilter.cs and copy and paste the following code.

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
namespace CustomAuthFilterDemo.Filters
{
    public class EmailVerifiedAuthorizationFilter : IAuthorizationFilter
    {
        public void OnAuthorization(AuthorizationFilterContext context)
        {
            var user = context.HttpContext.User;

            // Not authenticated → return custom JSON with 401
            if (!user.Identity?.IsAuthenticated ?? false)
            {
                var payload = new
                {
                    Status = 401,
                    Error = "Unauthenticated",
                    Message = "Authentication required. Please login to access this resource."
                };

                // Return custom JSON response for 401 Unauthorized
                context.Result = new JsonResult(payload)
                {
                    StatusCode = StatusCodes.Status401Unauthorized // 401
                };
                return;
            }

            // Check IsEmailVerified claim → return custom JSON with 403
            var isEmailVerified = user.FindFirst("IsEmailVerified")?.Value;

            if (isEmailVerified?.ToLower() != "true")
            {
                var payload = new
                {
                    Status = 403,
                    Error = "Forbidden",
                    Message = "Your Email is not verified. Please contact support."
                };

                // Return custom JSON response for 403 Forbidden
                context.Result = new JsonResult(payload)
                {
                    StatusCode = StatusCodes.Status403Forbidden // 403
                };
                return;
            }

            // Authorized - do nothing, allow request to proceed
        }
    }
}
Code Explanation:
  • JsonResult allows you to return arbitrary JSON data.
  • You set the StatusCode property to control the HTTP status code (e.g., 401 or 403).
  • Your API client will receive your custom JSON object with the status and message instead of the default empty or minimal response.
  • This is very useful for frontend apps or API consumers that expect a structured error message.
What is the OnAuthorization Method, and When/Who Invokes It?

The OnAuthorization is a method defined by the IAuthorizationFilter interface. It contains the custom authorization logic that we want to run synchronously before a controller action executes. It receives an AuthorizationFilterContext parameter, which provides access to:

  • The current HTTP context (context.HttpContext),
  • The authenticated user (context.HttpContext.User),
  • Route data, request info, and
  • Allows you to short-circuit the request by setting the context.Result.

The ASP.NET Core MVC framework invokes OnAuthorization automatically as part of the request processing pipeline. You, as the developer, do not call OnAuthorization directly. Specifically, it is called before the controller action method executes, during the filter pipeline phase.

Register the Custom Filter in the Dependency Injection Container

Add this to the Program.cs before builder.Build():

builder.Services.AddScoped<EmailVerifiedAuthorizationFilter>();

API Controller Applying the Custom Authorization Filter:

Create a new API Empty Controller named PremiumController within the Controllers folder and then copy and paste the following code:

using CustomAuthFilterDemo.Filters;
using Microsoft.AspNetCore.Mvc;
namespace CustomAuthFilterDemo.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    // Apply custom authorization filter to entire controller
    [ServiceFilter(typeof(EmailVerifiedAuthorizationFilter))] 
    public class PremiumController : ControllerBase
    {
        // GET api/premium/data
        [HttpGet("data")]
        public async Task<IActionResult> GetPremiumDataAsync()
        {
            // Simulate async work, e.g., fetching data from database or service
            await Task.Delay(100); // Replace with real async calls

            var premiumData = new
            {
                Message = "Welcome to the premium content area!",
                Timestamp = DateTime.UtcNow
            };

            // Return 200 OK with premium data JSON
            return Ok(premiumData);
        }

        // GET api/premium/features
        [HttpGet("features")]
        public IActionResult GetPremiumFeatures()
        {
            var features = new[]
            {
                "Ad-free experience",
                "Exclusive articles",
                "Priority support",
                "Early access to new content"
            };

            return Ok(features);
        }
    }
}
What is the [ServiceFilter] Attribute, and when should it be used?

The [ServiceFilter] is an attribute used to apply a filter class registered in the Dependency Injection (DI) container. It tells ASP.NET Core to resolve the filter instance from the DI container at runtime, so dependencies can be injected into your filter. We Use [ServiceFilter]:

  • When your filter needs dependencies (like a DB context, service, configuration, logger).
  • When you want to control filter lifetime (e.g., Scoped, Singleton, Transient) via DI.
  • When your filter isn’t just static logic but depends on the application’s services.

ASP.NET Core will get an instance of ActiveAccountAuthorizationFilter from DI, call OnAuthorization for each request, and enforce your authorization logic.

When to Use IAuthorizationFilter?
  • When your authorization logic is simple and synchronous (no async DB calls or external APIs).
  • You want to centralize custom authorization logic across controllers or actions.
  • You prefer filter-based authorization rather than policy-based or middleware.
  • Your checks depend on user claims, roles, or request context that can be evaluated synchronously.
Creating a Custom Authorization Filter using IAsyncAuthorizationFilter

The IAsyncAuthorizationFilter is an interface in ASP.NET Core used to create asynchronous custom authorization filters. It allows us to perform async operations such as database queries, external API calls, or any I/O bound work during authorization.

Suppose we have a financial Web API where only users whose KYC (Know Your Customer) is verified in the database are allowed to access sensitive endpoints. The KYC status can’t be trusted from the token alone; it must be checked in the database asynchronously each time the user tries to access these endpoints.

Create the Async Authorization Filter

Create a class file named KYCVerifiedAuthorizationFilter.cs within the Filters folder and then copy and paste the following code.

using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.AspNetCore.Mvc;
using CustomAuthFilterDemo.Models;
namespace CustomAuthFilterDemo.Filters
{
    public class KYCVerifiedAuthorizationFilter : IAsyncAuthorizationFilter
    {
        private readonly UserService _userService;

        // Inject any service you need (DB, API, etc.)
        public KYCVerifiedAuthorizationFilter(UserService userService)
        {
            _userService = userService;
        }

        public async Task OnAuthorizationAsync(AuthorizationFilterContext context)
        {
            var user = context.HttpContext.User;

            // Check if user is authenticated
            if (!user.Identity?.IsAuthenticated ?? false)
            {
                var payload = new
                {
                    Status = 401,
                    Error = "Unauthenticated",
                    Message = "Authentication required. Please login to access this resource."
                };

                // Return custom JSON response for 401 Unauthorized
                context.Result = new JsonResult(payload)
                {
                    StatusCode = StatusCodes.Status401Unauthorized // 401
                };
                return;
            }

            // Get UserId from claims
            var userId = user.FindFirst("UserId")?.Value;
            if (string.IsNullOrEmpty(userId))
            {
                var payload = new
                {
                    Status = 401,
                    Error = "BadRequest",
                    Message = "User ID not found in token. Token expired or Invalid"
                };

                context.Result = new JsonResult(payload)
                { 
                    StatusCode = 400 
                };
                return;
            }

            // Check KYC status asynchronously
            var isKycVerified = await _userService.IsKycVerifiedAsync(Convert.ToInt32(userId));

            if (!isKycVerified)
            {
                var payload = new
                {
                    Status = 401,
                    Error = "Forbidden",
                    Message = "KYC verification required. Please complete KYC process."
                };

                context.Result = new JsonResult(payload)
                { 
                    StatusCode = 403 
                };
                return;
            }

            // KYC verified: allow request to proceed
        }
    }
}
Register the Custom Filter in the Dependency Injection Container

Add this to the Program.cs before builder.Build():

builder.Services.AddScoped<KYCVerifiedAuthorizationFilter>();

Apply the Filter to an API Controller or Action:

Modify the PremiumController as follows.

using CustomAuthFilterDemo.Filters;
using Microsoft.AspNetCore.Mvc;
namespace CustomAuthFilterDemo.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    // Apply custom authorization filter to entire controller
    [ServiceFilter(typeof(KYCVerifiedAuthorizationFilter))]
    public class PremiumController : ControllerBase
    {
        [HttpGet("exclusive")]
        public IActionResult GetExclusiveContent()
        {
            // Only accessible if user is KYC-verified
            return Ok(new
            {
                Message = "Premium content for KYC verified users only.",
                Timestamp = DateTime.UtcNow
            });
        }
    }
}
When to Use IAsyncAuthorizationFilter?

IAsyncAuthorizationFilter is designed for asynchronous authorization logic in your Web API. Use it specifically when your authorization checks involve operations that require awaiting async tasks, such as:

When Authorization Depends on External or Database Calls: If you need to fetch user permissions, roles, or subscription status from a database asynchronously. If you integrate with external identity providers, license servers, or API gateways that require async HTTP calls. Example: Checking if a user’s subscription is still active by querying a user subscription table asynchronously.

When Authorization Requires Time-Consuming or IO-Bound Operations: Accessing remote caches or distributed systems asynchronously. Calling microservices or third-party APIs to verify authorization claims. Performing complex permission calculations that rely on async data sources.

To Avoid Blocking Threads on Async Operations: Using synchronous authorization logic (IAuthorizationFilter) for async operations can cause thread starvation or scalability issues. Implementing IAsyncAuthorizationFilter lets ASP.NET Core handle async authorization efficiently without blocking request threads.

When Your Authorization Logic Must Run Before Action Execution and Needs Async Support: When you want to keep authorization logic outside of controllers/services but it requires async code, IAsyncAuthorizationFilter executes asynchronously at the authorization stage before the action method runs.

When Building Real-Time or High-Performance Applications: Async filters help improve server responsiveness and throughput in applications that have heavy or frequent authorization checks involving async calls.

Creating a Custom Authorization Filter using AuthorizeAttribute

The built-in [Authorize] attribute in ASP.NET Core derives from AuthorizeAttribute. This base class implements both IAuthorizationFilter and IAsyncAuthorizationFilter. When you decorate a controller/action with [Authorize], under the hood it runs its OnAuthorization(…) (or OnAuthorizationAsync(…)) to enforce authentication + any policy/role we have set. By inheriting from it, we will get all that behavior for free, and only need to inject our extra rules.

Suppose we have an API where only users who are both in the “Admin” role AND have a “VerifiedEmail” claim set to “true” should be allowed to access certain sensitive endpoints. The built-in [Authorize(Roles = “Admin”)] only checks the role. We want to enforce both role and an extra business rule (verified email).

So, create a class file named AdminAndVerifiedEmailAttribute.cs within the Filters folder and then copy and paste the following code.

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
namespace CustomAuthFilterDemo.Filters
{
    public class AdminAndVerifiedEmailAttribute : AuthorizeAttribute, IAuthorizationFilter
    {
        public void OnAuthorization(AuthorizationFilterContext context)
        {
            var user = context.HttpContext.User;

            // Not authenticated → return custom JSON with 401
            if (!user.Identity?.IsAuthenticated ?? false)
            {
                var payload = new
                {
                    Status = 401,
                    Error = "Unauthenticated",
                    Message = "Authentication required. Please login to access this resource."
                };

                // Return custom JSON response for 401 Unauthorized
                context.Result = new JsonResult(payload)
                {
                    StatusCode = StatusCodes.Status401Unauthorized // 401
                };
                return;
            }

            // Check if user is in "Admin" role
            if (!user.IsInRole("Admin"))
            {
                var payload = new
                {
                    Status = 401,
                    Error = "Unauthenticated",
                    Message = "Admin Role Required"
                };

                // Return custom JSON response for 403 Forbidden
                context.Result = new JsonResult(payload)
                {
                    StatusCode = StatusCodes.Status403Forbidden // 403
                };
                return;
            }

            // Check IsEmailVerified claim → return custom JSON with 403
            var isEmailVerified = user.FindFirst("IsEmailVerified")?.Value;

            if (isEmailVerified?.ToLower() != "true")
            {
                var payload = new
                {
                    Status = 403,
                    Error = "Forbidden",
                    Message = "Your Email is not verified. Please contact support."
                };

                // Return custom JSON response for 403 Forbidden
                context.Result = new JsonResult(payload)
                {
                    StatusCode = StatusCodes.Status403Forbidden // 403
                };
                return;
            }

            // Authorized - do nothing, allow request to proceed
        }
    }
}
Applying the Attribute to a Controller or Action:

Modify the PremiumController as follows.

using CustomAuthFilterDemo.Filters;
using Microsoft.AspNetCore.Mvc;
namespace CustomAuthFilterDemo.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class PremiumController : ControllerBase
    {
        [HttpGet("secure-data")]
        [AdminAndVerifiedEmail]
        public IActionResult GetSecureData()
        {
            // Only accessible if user is KYC-verified
            return Ok(new
            {
                Message = "This data is only accessible to users with admin role and verified emails.",
                Timestamp = DateTime.UtcNow
            });
        }
    }
}
When to Use Custom Authorization Filters in ASP.NET Core Web API

Authorization is a core security concern in any Web API. While ASP.NET Core provides built-in authorization mechanisms like the [Authorize] attribute and policy-based authorization, there are specific situations where Custom Authorization Filters become necessary or advantageous. The following are some of the scenarios where you should consider using custom authorization filters:

When Built-in Authorization Attributes Are Not Enough

The default [Authorize] attribute supports basic role-based or policy-based authorization. However, real-world business needs often require more complex authorization rules such as:

  • Checking multiple dynamic conditions together (e.g., roles + subscription status + time of day).
  • Applying custom business rules that don’t fit into roles or claims.
  • Conditional authorization that depends on request parameters or headers.

In these cases, custom authorization filters let you implement your own logic centrally.

When Authorization Depends on External Data or Complex Logic

Sometimes you need to:

  • Query a database to verify a user’s current subscription, license validity, or account status.
  • Call an external API or microservice to check if the user’s session is still valid or if they have premium access.
  • Enforce time-sensitive access rules (e.g., only allow access during business hours).
  • Implement feature flags or A/B testing logic for access control.

A custom authorization filter lets you execute this logic at the authorization stage, preventing unauthorized users from accessing the resource before the controller runs.

When You Need Centralized Authorization Logic

Imagine multiple controllers or actions require the same custom authorization logic — for example, only users with an active subscription can access any premium API endpoint.

  • Instead of repeating the same checks in every controller or action, a custom authorization filter encapsulates this logic once. You then apply it globally, on a controller, or on specific actions, achieving:
  • Code Reusability and the DRY principle
  • Easier maintenance and updates to authorization logic
  • Cleaner controllers and action methods
When You Want to Customize Authorization Failure Responses or Behavior

The built-in [Authorize] attribute returns generic 401 (Unauthorized) or 403 (Forbidden) responses. If you want to:

  • Return custom error messages explaining why access was denied.
  • Log unauthorized access attempts with more details.
  • Redirect users or perform special side effects on authorization failure.
  • Integrate with custom logging or monitoring systems.

Custom authorization filters provide full control over the authorization pipeline, letting you customize the response or add logging before the request is blocked.

When You Need to Enforce Context-Aware Access Control

Authorization requirements might depend on the specific resource being accessed or the request context. For example:

  • Only allow a user to access resources they own (e.g., order or profile).
  • Limit access based on query parameters or headers.
  • Verify IP address or geolocation restrictions.
  • Check API keys or tokens beyond the default authentication.

Custom authorization filters can access the full request context (HttpContext, route data, headers, etc.) and make decisions accordingly.

Custom Authorization Filters in ASP.NET Core Web API provide a powerful, flexible way to enforce security beyond simple roles or policies. They help keep your API secure by centralizing authorization logic, supporting complex business rules, and enabling customized responses to unauthorized access attempts.

In the next article, I will discuss the Resource Filters in an ASP.NET Core Web API Application. In this article, I explain How to Create Custom Authorization Filters in ASP.NET Core Web API Applications with Examples. I hope you enjoy this article on Custom Authorization Filters in ASP.NET Core Web API.

Leave a Reply

Your email address will not be published. Required fields are marked *