Simple Authentication for ASP.NET Core

A library to easily integrate Authentication in ASP.NET Core projects. Currently it supports JWT Bearer, API Key and Basic Authentication in both Controller-based and Minimal API projects.

[!IMPORTANT] Update from Version 2.x to 3.x Swashbuckle (Swagger) support has been moved out from SimpleAuthentication. If you're using the AddSimpleAuthentication extension method with AddSwaggerGen, now you need to install the SimpleAuthentication.Swashbuckle package.

Installation

The library is available on NuGet. Search for SimpleAuthenticationTools in the Package Manager GUI or run the following command in the .NET CLI:

dotnet add package SimpleAuthenticationTools

Usage video

Take a look at a quick demo showing how to integrate the library:

Configuration

Authentication can be fully configured adding an Authentication section in the appsettings.json file:

"Authentication": {
    "DefaultScheme": "Bearer", // Optional
    "JwtBearer": {
        "SchemeName": "Bearer" // Default: Bearer
        //"NameClaimType": "user_name", // Default: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
        //"RoleClaimType": "user_role", // Default: http://schemas.microsoft.com/ws/2008/06/identity/claims/role
        "SecurityKey": "supersecretsecuritykey42!", // Required
        "Algorithm": "HS256", // Default: HS256
        "Issuers": [ "issuer" ], // Optional
        "Audiences": [ "audience" ], // Optional
        "ExpirationTime": "01:00:00", // Default: No expiration
        "ClockSkew": "00:02:00", // Default: 5 minutes
    },
    "ApiKey": {
        "SchemeName": "ApiKey", // Default: ApiKey
        // You can specify either HeaderName, QueryStringKey or both
        "HeaderName": "x-api-key",
        "QueryStringKey": "code",
        //"NameClaimType": "user_name", // Default: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
        //"RoleClaimType": "user_role", // Default: http://schemas.microsoft.com/ws/2008/06/identity/claims/role
        // Uncomment this line if you want to validate the API Key against a fixed value.
        // Otherwise, you need to register an IApiKeyValidator implementation that will be used
        // to validate the API Key.
        //"ApiKeyValue": "f1I7S5GXa4wQDgLQWgz0",
        "UserName": "ApiUser" // Required if ApiKeyValue is used
    },
    "Basic": {
        "SchemeName": "Basic", // Default: Basic
        //"NameClaimType": "user_name", // Default: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
        //"RoleClaimType": "user_role", // Default: http://schemas.microsoft.com/ws/2008/06/identity/claims/role
        // Uncomment the following lines if you want to validate user name and password
        // against fixed values.
        // Otherwise, you need to register an IBasicAuthenticationValidator implementation
        // that will be used to validate the credentials.
        //"UserName": "marco",
        //"Password": "P@$$w0rd"
    }
}

You can configure only the kind of authentication you want to use, or you can include all of them.

The DefaultScheme attribute is used to specify what kind of authentication must be configured as default. Allowed values are the values of the SchemeName attributes.

Registering authentication at Startup

using SimpleAuthentication;

var builder = WebApplication.CreateBuilder(args);

// ...
// Registers authentication schemes and services using IConfiguration information (see above).
builder.Services.AddSimpleAuthentication(builder.Configuration);

// ...

var app = builder.Build();

//...
// The following middlewares aren't strictly necessary in .NET 7.0 or higher, because they are automatically
// added when detecting that the corresponding services have been registered. However, you may
// need to call them explicitly if the default middlewares configuration is not correct for your
// app, for example when you need to use CORS.
// Check https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/middleware
// for more information.
//app.UseAuthentication();
//app.UseAuthorization();

//...

app.Run();

Integrating with Swashbuckle

If you're using Swashbuckle (Swagger) to document your API, you can integrate the authentication configuration with the Swagger documentation. Search for SimpleAuthenticationTools.Swashbuckle in the Package Manager GUI or run the following command in the .NET CLI:

dotnet add package SimpleAuthenticationTools.Swashbuckle

Then, you can use the AddSimpleAuthentication extension method:

builder.Services.AddSwaggerGen(options =>
{
    // ...
    // Add this line to integrate authentication with Swagger.
    options.AddSimpleAuthentication(builder.Configuration);
});

Integrating with Microsoft.AspNetCore.OpenApi (.NET 9 or later)

Starting from version 9, .NET offers built-in support for OpenAPI. If you're using the AddOpenApi extension method to provide OpenAPI support, you just need to add the corresponding extension method in its declaration (no extra package required):

builder.Services.AddOpenApi(options =>
{
    // ...
    // Add this line to integrate authentication with OpenAPI.
    options.AddSimpleAuthentication(builder.Configuration);
});

Creating a JWT Bearer

When using JWT Bearer authentication, an implementation of the IJwtBearerService interface is automatically registered to create a valid JWT Bearer, according to the settings you have specified in the appsettings.json file:

app.MapPost("api/auth/login", async (LoginRequest loginRequest, IJwtBearerService jwtBearerService) =>
{
    // Check for login rights...

    // Add custom claims (optional).
    var claims = new List<Claim>
    {
        new(ClaimTypes.GivenName, "Marco"),
        new(ClaimTypes.Surname, "Minerva")
    };

    var token = await jwtBearerService.CreateTokenAsync(loginRequest.UserName, claims);
    return TypedResults.Ok(new LoginResponse(token));
});

public record class LoginRequest(string UserName, string Password);

public record class LoginResponse(string Token);

The IJwtBearerService.CreateToken method allows to specify the issuer and the audience of the token. If you don't specify any value, the first ones defined in appsettings.json will be used.

Supporting multiple API Keys/Basic Authentication credentials

When using API Key or Basic Authentication, you can specify multiple fixed values for authentication:

"Authentication": {
    "ApiKey": {
        "ApiKeys": [
            {
                "Value": "key-1",
                "UserName": "UserName1"
            },
            {
                "Value": "key-2",
                "UserName": "UserName2"
            }
        ]
    },
    "Basic": {
        "Credentials": [
            {
                "UserName": "UserName1",
                "Password": "Password1"
            },
            {
                "UserName": "UserName2",
                "Password": "Password2"
            }
        ]
    }
}

With this configuration, authentication will succeed if any of these credentials are provided.

Assigning roles to API Keys and Basic Authentication credentials

You can optionally specify roles for each API Key or Basic Authentication credential. When authentication succeeds, the specified roles will be automatically added as role claims to the user's identity.

For single credentials, you can specify roles directly:

"Authentication": {
    "ApiKey": {
        "ApiKeyValue": "f1I7S5GXa4wQDgLQWgz0",
        "UserName": "ApiUser",
        "Roles": ["Administrator"]
    },
    "Basic": {
        "UserName": "marco",
        "Password": "P@$$w0rd",
        "Roles": ["Administrator"]
    }
}

For multiple credentials, you can specify roles for each credential:

"Authentication": {
    "ApiKey": {
        "ApiKeys": [
            {
                "Value": "key-1",
                "UserName": "UserName1",
                "Roles": ["Administrator", "User"]
            },
            {
                "Value": "key-2",
                "UserName": "UserName2",
                "Roles": ["User"]
            }
        ]
    },
    "Basic": {
        "Credentials": [
            {
                "UserName": "UserName1",
                "Password": "Password1",
                "Roles": ["Manager", "User"]
            },
            {
                "UserName": "UserName2",