SimpleW.Helper.BasicAuth 26.0.0

SimpleW.Helper.BasicAuth

<br/>

Features

SimpleW.Helper.BasicAuth is the reusable HTTP Basic auth engine for SimpleW.

It lets you:

• parse Authorization: Basic ...
• validate username/password pairs
• build a HttpPrincipal
• send a 401 Basic challenge response

This package does not decide which route must be protected. That policy stays in your middleware.

Getting Started

Minimal helper usage:

using System;
using SimpleW;
using SimpleW.Helper.BasicAuth;

namespace Sample {
    class Program {

        static async Task Main() {

            var server = new SimpleWServer(System.Net.IPAddress.Any, 2015);

            BasicAuthHelper basic = new(options => {
                options.Users = [
                    new BasicUser("admin", "secret")
                ];
            });

            server.UseMiddleware(async (session, next) => {

                // restore the basicauth principal
                if (basic.TryAuthenticate(session, out HttpPrincipal principal)) {
                    session.Principal = principal;
                }

                // fast path
                if (session.Metadata.Has<AllowAnonymousAttribute>()) {
                    await next().ConfigureAwait(false);
                    return;
                }

                // check principal
                BasicAuthAttribute? auth = session.Metadata.Get<BasicAuthAttribute>();
                if (auth != null && !session.Principal.IsAuthenticated) {
                    await basic.SendChallengeAsync(session, auth.Realm).ConfigureAwait(false);
                    return;
                }

                await next().ConfigureAwait(false);
            });

            server.MapController<AdminController>("/api");

            await server.RunAsync();
        }
    }

    [Route("/admin")]
    [BasicAuth("Admin Area")]
    public class AdminController : Controller {

        [Route("GET", "/me")]
        public object Me() {
            return new {
                user = Principal.Name
            };
        }

        [AllowAnonymous]
        [Route("GET", "/health")]
        public object Health() {
            return new { ok = true };
        }

    }
}

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = false, Inherited = true)]
public sealed class BasicAuthAttribute : Attribute, IHandlerMetadata {

    public BasicAuthAttribute(string realm = "Restricted") {
        Realm = realm;
    }

    public string Realm { get; }

}

In a helper-only integration, BasicAuthAttribute is typically an application-defined metadata attribute.

If you want a ready-to-use metadata-driven module that restores the principal and enforces [BasicAuth] / [AllowAnonymous] for you, use SimpleW.Service.BasicAuth.

Documentation

To check out docs, visit simplew.net.

Changelog

Detailed changes for each release are documented in the CHANGELOG.

Contribution

Feel free to report issue.

License

This library is under the MIT License.