Implementing fine-grained access control with ASP.NET Core custom endpoint metadata
Tags: dotnet, csharp, security, programming
Published: 2024-02-26 12:30:00

Endpoint metadata are pieces of information associated with each endpoint in an ASP.NET Core application. An endpoint is essentially an entry point into your web application, such as an MVC controller action or a route in a minimal API, which can process HTTP requests. Endpoint metadata allow for the description of these endpoints' characteristics and behaviors, such as authorization policies, CORS (Cross-Origin Resource Sharing) restrictions, filters, and more.

In the context of MVC controllers or API controllers, endpoint metadata are often defined using attributes, such as `[Authorize]`, or `[Produces]`. With the introduction of minimal APIs in ASP.NET Core 6 and later versions, the concept of endpoint metadata has also been extended to these lighter and more flexible models. Endpoint metadata are typically added using fluent methods, such as `RequireAuthorization()` or `RequireRateLimiting()`.

In this article, we will explore how to use your own endpoint metadata and consume them in an authorization policy to implement fine-grained access control in your ASP.NET Core application.

## Creating your own endpoint metadata

We will implement an authorization policy based on a system of granular permissions. The code you will see in the following sections is inspired by the [Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web/blob/2.17.0/src/Microsoft.Identity.Web/Policy/ScopeAuthorizationHandler.cs#L38) library, which uses these same principles to implement authorization based on OAuth 2.0 scopes.

Let's start with our fine-grained permission system. We'll define a simple enum to represent the different permissions that can be granted:

```csharp
public enum Permission
{
    Read,
    Write,
    // ...
}
```

Next, we will create an attribute that represents our endpoint metadata, allowing an endpoint to specify one or more required permissions:

```csharp
public interface IRequiredPermissionMetadata
{
    HashSet<Permission> RequiredPermissions { get; }
}

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
public class RequiredPermissionAttribute(Permission requiredPermission, params Permission[] additionalRequiredPermissions)
    : Attribute, IRequiredPermissionMetadata
{
    public HashSet<Permission> RequiredPermissions { get; } = [requiredPermission, ..additionalRequiredPermissions];
}
```

The `[RequiredPermission]` attribute can be used on your controller methods and classes like this:

```csharp
[ApiController]
[Route("[controller]")]
public class HelloController : ControllerBase
{
    [HttpGet]
    [RequiredPermission(Permission.Read, Permission.Write)]
    public IActionResult Index()
    {
        return this.Ok("Hello world");
    }
}
```

If you want to add it as endpoint metadata on minimal APIs, you can create the following extension method:

```csharp
public static TBuilder RequirePermission<TBuilder>(
    this TBuilder endpointConventionBuilder, Permission requiredPermission, params Permission[] additionalRequiredPermissions)
    where TBuilder : IEndpointConventionBuilder
{
    return endpointConventionBuilder.WithMetadata(new RequiredPermissionAttribute(requiredPermission, additionalRequiredPermissions));
}
```

Thus, you can use it in the following way:

```csharp
app.MapGet("/", () => "Hello World!")
    .RequirePermission(Permission.Read);
```

## Consuming endpoint metadata in a custom authorization requirement

Now that our endpoints are decorated with our metadata, we can create an [authorization requirement](https://learn.microsoft.com/en-us/aspnet/core/security/authorization/policies?view=aspnetcore-8.0#requirements). In ASP.NET Core, authorization policies are collections of authorization requirements that allow you to compose granular rules for controlling access to your resources.

Let's create a requirement for our permission system:

```csharp
public class PermissionAuthorizationRequirement : IAuthorizationRequirement;
```

Our authorization requirement doesn't need to contain data, as we will use an [authorization handler](https://learn.microsoft.com/en-us/aspnet/core/security/authorization/policies?view=aspnetcore-8.0#handlers) to retrieve the permissions declared on the endpoints that users are attempting to access.

```csharp
public sealed class RequiredPermissionAuthorizationHandler : AuthorizationHandler<PermissionAuthorizationRequirement>
{
    protected override Task HandleRequirementAsync(AuthorizationHandlerContext context, PermissionAuthorizationRequirement requirement)
    {
        var endpoint = context.Resource switch
        {
            HttpContext httpContext => httpContext.GetEndpoint(),
            Endpoint ep => ep,
            _ => null,
        };

        var requiredPermissions = endpoint?.Metadata.GetMetadata<IRequiredPermissionMetadata>()?.RequiredPermissions;
        if (requiredPermissions == null)
        {
            // The endpoint is not decorated with the required permission metadata
            return Task.CompletedTask;
        }

        // TODO: Implement your custom logic to check if the user has the required permissions
        var hasRequiredPermissions = true;

        if (hasRequiredPermissions)
        {
            context.Succeed(requirement);
        }

        return Task.CompletedTask;
    }
}
```

Note that we used the `EndpointMetadataCollection.GetMetadata<T>` method by providing our endpoint metadata interface. This method ensures to retrieve the metadata that implement the `IRequiredPermissionMetadata` interface and is optimized with an internal cache.

Now, all that remains is to declare our authorization policy within our application's services.

## Registering the authorization policy

Let's create a fictional authorization policy that requires the endpoints protected by this policy to be decorated with our `RequiredPermissionAttribute` metadata, and for the user to be authenticated with the `Cookies` authentication scheme. Our policy will be named `RequiredPermissions`.

```csharp
public static class RequiredPermissionDefaults
{
    public const string PolicyName = "RequiredPermission";
}

public static class RequiredPermissionAuthorizationExtensions
{
    public static AuthorizationPolicyBuilder RequireRequiredPermissions(this AuthorizationPolicyBuilder builder)
    {
        return builder.AddRequirements(new PermissionAuthorizationRequirement());
    }

    public static AuthorizationBuilder AddRequiredPermissionPolicy(this AuthorizationBuilder builder)
    {
        builder.AddPolicy(RequiredPermissionDefaults.PolicyName, policy =>
        {
            policy.RequireAuthenticatedUser();
            policy.AddAuthenticationSchemes(CookieAuthenticationDefaults.AuthenticationScheme);
            
            policy.RequireRequiredPermissions();
        });

        builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IAuthorizationHandler, RequiredPermissionAuthorizationHandler>());

        return builder;
    }
}
```

In the code above, we took the opportunity to register our `RequiredPermissionAuthorizationHandler` implementation with our application's services. This will allow our handler to be resolved by ASP.NET Core's dependency injection system.

Finally, we can register our policy within our services:

```csharp
var builder = WebApplication.CreateBuilder(args);

// TODO: Register your authentication scheme!
builder.Services.AddAuthorization();

builder.Services.AddAuthorizationBuilder()
    .AddRequiredPermissionPolicy();

builder.Services.AddAuthorization(options =>
{
    options.FallbackPolicy = options.GetPolicy(RequiredPermissionDefaults.PolicyName);
});

var app = builder.Build();

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

app.MapGet("/", () => "Hello World!")
    .RequirePermission(Permission.Read);

app.Run();
```

This setup ensures that our application utilizes the `RequiredPermissions` policy as a fallback policy, applying our fine-grained access control mechanism across all endpoints that are not already protected by another policy or are anonymous.

## Conclusion

In this article, we explored how to use endpoint metadata to implement a system of granular permissions in an ASP.NET Core application. We created our own `RequiredPermissionAttribute` metadata and consumed it in an authorization policy to control access to our resources. We also saw how to use an authorization handler to retrieve the required permissions from endpoint metadata.

It's your responsibility to implement the logic for verifying permissions in your authorization handler. The same goes for the authorization policy and the authentication scheme you wish to use.

## References

- [Policy-based authorization in ASP.NET Core (Microsoft documentation)](https://learn.microsoft.com/en-us/aspnet/core/security/authorization/policies).
- [Custom Authorization Policy Providers using IAuthorizationPolicyProvider in ASP.NET Core (Microsoft documentation)](https://learn.microsoft.com/en-us/aspnet/core/security/authorization/iauthorizationpolicyprovider).
- [Microsoft.Identity.Web's source code](https://github.com/AzureAD/microsoft-identity-web/tree/2.17.0/src/Microsoft.Identity.Web/Policy).