README.md

Security API Keys for ASP.NET Core

API Key Authentication Implementation for ASP.NET Core

Passing API Key in a Request

• Request Headers
• Query Parameters
• Cookie

Request Header

Example passing the security api key via a header

GET http://localhost:5009/users
Accept: application/json
X-API-KEY: 01HSGVBSF99SK6XMJQJYF0X3WQ

Query Parameters

Example passing the security api key via a header

GET http://localhost:5009/users?X-API-KEY=01HSGVBSF99SK6XMJQJYF0X3WQ
Accept: application/json

Security API Key Setup

Set the Security API Key

Security API key in the appsetting.json

{
  "SecurityKey": "01HSGVBSF99SK6XMJQJYF0X3WQ"
}

Multiple keys supported via semicolon delimiter

{
  "SecurityKey": "01HSGVBGWXWDWTFGTJSYFXXDXQ;01HSGVBSF99SK6XMJQJYF0X3WQ"
}

Register Services

var builder = WebApplication.CreateBuilder(args);

// add security api key scheme
builder.Services
    .AddAuthentication()
    .AddSecurityKey(); 

builder.Services.AddAuthorization();

// add security api key services
builder.Services.AddSecurityKey();
  

Configure Options

builder.Services.AddSecurityKey(options => {
    options.ConfigurationName = "Authentication:ApiKey";
    options.HeaderName = "x-api-key";
    options.QueryName = "ApiKey";
    options.KeyComparer = StringComparer.OrdinalIgnoreCase;
});

Secure Endpoints

Secure Controller with SecurityKeyAttribute. Can be at class or method level

[ApiController]
[Route("[controller]")]
public class AddressController : ControllerBase
{
    [SecurityKey]
    [HttpGet(Name = "GetAddresses")]
    public IEnumerable<Address> Get()
    {
        return AddressFaker.Instance.Generate(5);
    }

}

Secure via middleware. All endpoints will require security API key

public static class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.Services.AddAuthorization();
        builder.Services.AddSecurityKey();
        
        var app = builder.Build();
    
        // required api key for all end points
        app.UseSecurityKey();
        app.UseAuthorization();

        app.MapGet("/weather", () => WeatherFaker.Instance.Generate(5));

        app.Run();
    }
}

Secure Minimal API endpoint with filter, .NET 8+ only

public static class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.Services.AddAuthorization();
        builder.Services.AddSecurityKey();
        
        var app = builder.Build();
    
        app.UseAuthorization();

        app.MapGet("/users", () => UserFaker.Instance.Generate(10))
            .RequireSecurityKey();

        app.Run();
    }
}

Secure with Authentication Scheme

public static class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.Services
            .AddAuthentication()
            .AddSecurityKey();

        builder.Services.AddAuthorization();
        builder.Services.AddSecurityKey();
        
        var app = builder.Build();
    
        app.UseAuthentication();
        app.UseAuthorization();

        app.MapGet("/users", () => UserFaker.Instance.Generate(10))
            .RequireAuthorization();

        app.Run();
    }
}