How do you use policy-based authorization in ASP.NET Core Web API?

Policy-based authorization in ASP.NET Core Web API defines reusable policies that evaluate claims, roles, or custom logic to determine access. It offers a flexible and powerful way to manage authorization rules beyond simple role checks. You define these policies in your application’s startup configuration and then apply them to controllers or individual actions using the [Authorize] attribute. This approach enhances security, promotes reusability, and simplifies complex access control scenarios.

What is Policy-Based Authorization?

Policy-based authorization allows you to define authorization rules as policies. These policies evaluate claims, roles, or other custom logic to determine whether a user has the necessary permissions to access a resource. Unlike simpler role-based checks, policies enable complex authorization scenarios by combining multiple conditions. You apply these policies to controllers or actions using attributes or middleware, providing a highly flexible and extensible security model.

Role-Based vs. Policy-Based Authorization

Understanding the distinction between role-based and policy-based authorization is crucial:

• Role-based authorization is simpler, checking a user’s assigned roles directly (e.g., “Admin,” “User”). It’s like assigning keys to doors based on job titles. If you have the “Manager” role, you get access to the “Manager” room.
• Policy-based authorization is more flexible, allowing custom logic beyond just roles. It’s akin to a security guard who checks multiple factors. This allows for finer control. For example, only managers with “Project X” clearance can access the Project X room. This is achieved by checking the “Project X” claim, which offers more granularity than just the “Manager” role. Policies can combine role checks with other conditions, such as specific claims, user attributes, or even external data.

Defining Policies in ASP.NET Core

Policies are typically defined in your application’s Startup.cs file, within the ConfigureServices method, using the services.AddAuthorization() method.

Inside Startup.ConfigureServices, you use services.AddAuthorization(options => { ... });. The AddPolicy("PolicyName", policy => { ... }); method defines a new policy. Within the policy configuration, you can use various methods to specify requirements:

• RequireRole("Admin"): Enforces that the user must possess the specified role.
• RequireClaim("SpecialClaimType", "SpecialClaimValue"): Requires the user to have a specific claim with a particular value.
• RequireAssertion(context => /* custom logic */): Allows you to define custom authorization logic using a lambda expression that evaluates the current authorization context. This provides maximum flexibility.
• RequireAuthenticatedUser(): This is crucial; it ensures that only logged-in (authenticated) users are even considered for the policy, preventing accidental access by anonymous users.

Requirements and Handlers

For more complex or reusable authorization logic, ASP.NET Core introduces the concepts of Requirements and Handlers.

• A Requirement is a simple class that encapsulates a specific authorization condition (e.g., “Must be over 18,” “Must have a Premium subscription”). It implements IAuthorizationRequirement.
• A Handler is a class that contains the logic to evaluate a specific requirement. It inherits from AuthorizationHandler and implements the HandleRequirementAsync method, which checks if the user meets the condition defined by the requirement.

This separation promotes modularity and reusability. Think of a requirement as a specific condition for access, like having a “Premium” subscription. A handler is then the code that verifies this condition. This separation keeps things organized. For example, a PremiumUserRequirement simply defines the need for a premium subscription. The PremiumUserHandler checks the user’s claims to see if they have the “SubscriptionLevel” claim with a value of “Premium”. This makes it easy to reuse the PremiumUserRequirement with different handlers if the verification logic changes.

Applying Policies

Once policies are defined, you apply them using the [Authorize] attribute on controllers or individual action methods.

• The [Authorize(Policy = "PolicyName")] attribute, applied to a controller or action, enforces the specified policy. For instance, [Authorize(Policy = "AdminOnly")] would ensure only users satisfying the “AdminOnly” policy can access.
• If you apply multiple [Authorize] attributes to an action, say [Authorize(Policy = "Editor")] and [Authorize(Policy = "CanPublish")], both policies must be satisfied. This is an AND logic by default, meaning the user must be an editor AND have publishing permissions.

Policy Evaluation Flow

When a request arrives, the authorization middleware checks for [Authorize] attributes. It then executes the specified policy’s handlers. Each handler votes on whether the requirement is met using context.Succeed(requirement) (to indicate success) or context.Fail() (to indicate failure). If all requirements of a policy are met (all associated handlers succeed for that policy), the user is authorized. If any handler fails for any requirement within a policy, authorization fails, and the user is denied access.

Real-World Applications and Best Practices

Fine-Grained Control with Real-World Examples

Policy-based authorization excels in scenarios requiring fine-grained control beyond simple roles. For example, in a document management system, editors might only be allowed to edit documents in ‘Draft’ status, not ‘Published’ ones. You could create a ‘CanEditDocument’ policy that checks two things: if the user has the ‘Editor’ role AND if the document’s status (perhaps passed as a resource or claim) is ‘Draft’. This allows for managing editing permissions very precisely without creating complex role hierarchies.

Separation of Concerns

Policy-based authorization significantly improves code organization by promoting the separation of concerns. By centralizing authorization rules in policies, and further encapsulating specific logic within requirements and handlers, the codebase becomes cleaner, easier to understand, and maintain. For instance, a ‘MustBeOver18’ requirement with a handler that checks the user’s birthdate claim can be reused anywhere age verification is needed, promoting code reusability and making testing much simpler.

Unit Testing Custom Logic

Testing authorization logic is crucial for robust applications. Custom requirements and handlers can (and should) be thoroughly unit tested. When testing a handler like PremiumUserHandler, you can mock the AuthorizationHandlerContext. This allows you to simulate different user claims and verify that the handler correctly grants or denies access based on those claims, without needing a real database or authentication system. This isolated testing approach ensures that your authorization logic works reliably in various scenarios.

Leveraging Claims for Richer Authorization

Claims provide a much richer authorization model than roles alone. While roles categorize users broadly (e.g., ‘Basic’, ‘Premium’), claims offer specific pieces of information about the user (e.g., ‘SubscriptionType: Premium’, ‘HasFeature: Analytics’). This allows for more flexible and dynamic policies. For example, instead of creating complex role hierarchies for ‘Trial’ users with limited premium feature access, you can introduce a ‘SubscriptionType’ claim. Policies can then easily grant access based on this claim’s value, providing much more flexibility than roles alone.

Code Sample: Policy Definition and Application

Here’s a comprehensive example demonstrating how to define policies and apply them in an ASP.NET Core Web API.

1. Define Policies in Startup.cs

Configure authorization services and define your custom policies. We also register a custom authorization handler here.

// Startup.cs (or Program.cs in .NET 6+)
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();

        // 1. Configure Authentication (e.g., JWT Bearer, Cookie)
        // This is a placeholder; you'd configure your actual authentication scheme here.
        services.AddAuthentication("Bearer")
            .AddJwtBearer(options =>
            {
                // Configure token validation, authority, audience, etc.
                // For simplicity, this example focuses on authorization.
            });

        // 2. Configure Authorization Policies
        services.AddAuthorization(options =>
        {
            options.AddPolicy("AdminOnly", policy =>
                policy.RequireRole("Administrator")
                      .RequireAuthenticatedUser()); // Ensure user is logged in

            options.AddPolicy("DocumentEditor", policy =>
                policy.RequireClaim("DocumentStatus", "Draft") // Requires a claim for document status
                      .RequireRole("Editor") // Requires the 'Editor' role
                      .RequireAuthenticatedUser());

            options.AddPolicy("MinimumAge18", policy =>
                policy.Requirements.Add(new MinimumAgeRequirement(18)) // Uses a custom requirement
                      .RequireAuthenticatedUser());
        });

        // 3. Register Custom Authorization Handlers
        services.AddSingleton(); // Register our custom handler
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseRouting();

        // Must be between UseRouting and UseEndpoints
        app.UseAuthentication(); 
        app.UseAuthorization(); 

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

2. Create a Custom Requirement

Define a simple class that specifies a condition for authorization.

// Requirements/MinimumAgeRequirement.cs
using Microsoft.AspNetCore.Authorization;

public class MinimumAgeRequirement : IAuthorizationRequirement
{
    public int MinimumAge { get; }

    public MinimumAgeRequirement(int minimumAge)
    {
        MinimumAge = minimumAge;
    }
}

3. Create a Custom Handler

Implement the logic to evaluate the MinimumAgeRequirement.

// Handlers/MinimumAgeHandler.cs
using Microsoft.AspNetCore.Authorization;
using System.Security.Claims;
using System;
using System.Threading.Tasks;

public class MinimumAgeHandler : AuthorizationHandler
{
    protected override Task HandleRequirementAsync(AuthorizationHandlerContext context, MinimumAgeRequirement requirement)
    {
        // Check if the user has a DateOfBirth claim
        var dateOfBirthClaim = context.User.FindFirst(ClaimTypes.DateOfBirth);

        if (dateOfBirthClaim == null)
        {
            context.Fail(); // No DOB claim, cannot verify age
            return Task.CompletedTask;
        }

        // Parse the DOB and calculate age
        if (DateTime.TryParse(dateOfBirthClaim.Value, out DateTime dob))
        {
            var age = DateTime.Today.Year - dob.Year;
            // Adjust age if birthday hasn't occurred yet this year
            if (dob.Date > DateTime.Today.AddYears(-age)) age--;

            if (age >= requirement.MinimumAge)
            {
                context.Succeed(requirement); // User meets the age requirement
            }
            else
            {
                context.Fail(); // User is too young
            }
        }
        else
        {
            context.Fail(); // DOB claim is not a valid date
        }

        return Task.CompletedTask;
    }
}

4. Apply Policies in Controllers

Use the [Authorize] attribute with the Policy property on your API controllers or action methods.

// Controllers/DocumentsController.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.MVC;

[ApiController]
[Route("api/[controller]")]
public class DocumentsController : ControllerBase
{
    [HttpGet]
    public IActionResult GetPublicDocuments()
    {
        return Ok("Anyone can view these documents.");
    }

    // Requires 'Administrator' role
    [Authorize(Policy = "AdminOnly")]
    [HttpDelete("{id}")]
    public IActionResult DeleteDocument(int id)
    {
        // Logic to delete document
        return Ok($"Document {id} deleted successfully by admin.");
    }

    // Requires 'Editor' role AND 'DocumentStatus: Draft' claim
    [Authorize(Policy = "DocumentEditor")]
    [HttpPut("{id}")]
    public IActionResult EditDocument(int id)
    {
        // Logic to edit document
        return Ok($"Document {id} edited successfully (must be Editor & Draft).");
    }

    // Requires user to be 18 or older (custom policy with requirement/handler)
    [Authorize(Policy = "MinimumAge18")]
    [HttpGet("restricted-content")]
    public IActionResult GetRestrictedContent()
    {
        return Ok("Welcome to the 18+ section!");
    }
}

This setup provides a robust and flexible authorization system, allowing you to manage access based on a rich set of conditions beyond simple roles.