SimpleAuth.Authentication.Basic 1.0.0

AspNetCore.Authentication.Basic

This project contains an implementation of Basic Authentication Scheme for ASP.NET Core. See the RFC-7617.

Add Basic Authentication

To add Basic authentication in .NET Core, we need to modify Program.cs file. If you are using .NET Core version 5 or less, you have to add the modifications in the Startup.cs file inside the ConfigureServices method.

Add the code to configure Basic authentication right above the builder.Services.AddAuthentication() line:

builder.Services.AddAuthentication()
                .AddBasic(BasicDefaults.AuthenticationScheme);

Basic Authentication Configuration

To configure Basic authentication, we need use delegate from overloaded method AddBasic(string authenticationScheme, Action<BasicOptions> configure):

builder.Services.AddAuthentication()
                .AddBasic(BasicDefaults.AuthenticationScheme, configure => {
                    //some options will be here
                });

User credentials separator

User credentials (user-id and password) constructs by concatenating the user-id, a single colon (':') character, and the password. If your credentials is separated by another symbol, then it can be configured with the option CredentialsSeparator:

builder.Services.AddAuthentication()
                .AddBasic(BasicDefaults.AuthenticationScheme, configure => {
                    //Default option value is single colon (':')
                    configure.CredentialsSeparator = '~'
                });

Credentials encoding scheme

By default user credentials encoded by Base64 into a sequence of US-ASCII characters. If your credentials is by another algorithm or scheme, then it can be configured with the option EncodedHeaderDecoder:

builder.Services.AddAuthentication()
                .AddBasic(BasicDefaults.AuthenticationScheme, configure => {
                    configure.EncodedHeaderDecoder = credentials => DecodeCretentialsToString(credentials);
                });

Or you can use EncodedHeaderAsyncDecoder for asynchronous decode:

builder.Services.AddAuthentication()
                .AddBasic(BasicDefaults.AuthenticationScheme, configure => {
                    configure.EncodedHeaderAsyncDecoder = async (credentials, cancellationToken) => await DecodeCretentialsToStringAsync(credentials, cancellationToken);
                });

If both the EncodedHeaderAsyncDecoder and EncodedHeaderDecoder options are implemented, BasicHandler will use only EncodedHeaderAsyncDecoder to work:

builder.Services.AddAuthentication()
                .AddBasic(BasicDefaults.AuthenticationScheme, configure => {
                    //This one will be used
                    configure.EncodedHeaderAsyncDecoder = async (credentials, cancellationToken) => await DecodeCretentialsToStringAsync(credentials, cancellationToken);

                    //This one will be ignored
                    configure.EncodedHeaderDecoder = credentials => DecodeCretentialsToString(credentials);
                });

ClaimsPrincipal object creation

After decoding user credentials, it will be split into two separed strings (user-id and password). Then user-id and password will be used to create Claim[] by ClaimsFactory option for final ClaimsIdentity. By default this ClaimsFactory creates Claim[] with only one Claim with type NameIdentifier. If you need add another claims or get claims from storage, you can overload ClaimsFactory option:

builder.Services.AddAuthentication()
                .AddBasic(BasicDefaults.AuthenticationScheme, configure => {
                    configure.ClaimsFactory = (userId, password) => GetUserClaimsFromStorage(userId, password);
                });

Or you can use AsyncClaimsFactory for asynchronous Claim[] create:

builder.Services.AddAuthentication()
                .AddBasic(BasicDefaults.AuthenticationScheme, configure => {
                    configure.AsyncClaimsFactory = async (userId, password, cancellationToken) => await GetUserClaimsFromStorageAsync(userId, password, cancellationToken);
                });

Same as when you use header decoding option, if both the AsyncClaimsFactory and ClaimsFactory options are implemented, BasicHandler will use only AsyncClaimsFactory to work:

builder.Services.AddAuthentication()
                .AddBasic(BasicDefaults.AuthenticationScheme, configure => {
                    //This one will be used
                    configure.AsyncClaimsFactory = async (userId, password, cancellationToken) => await GetUserClaimsFromStorageAsync(userId, password, cancellationToken);

                    //This one will be ignored
                    configure.ClaimsFactory = (userId, password) => GetUserClaimsFromAnotherStorage(userId, password);
                });

Basic Authentication Events

The following events may occur during Basic authentication, which we can handle:

• OnMessageReceived - Invoked when a protocol message is first received.
• OnFailed - Invoked if authentication fails during request processing. The exceptions will be re-thrown after this event unless suppressed.
• OnChallenge - Invoked before a challenge is sent back to the caller.
• OnForbidden - Invoked if authorization fails and results in a Forbidden response.

All this events is part of BasicEvents object.

Events handling is the same as in other authentication schemes:

builder.Services.AddAuthentication()
                .AddBasic(BasicDefaults.AuthenticationScheme, configure => {
                    configure.Events = new BasicEvents()
                    {
                        OnMessageReceived = context => {
                            //handle this event
                            return Task.CompletedTask;
                        }
                    }
                });