Cuemon.AspNetCore.Authentication

Overview

Cuemon.AspNetCore.Authentication extends Microsoft.AspNetCore.Authentication with package-owned Basic, Digest access, and HMAC authentication flows. It combines typed authorization headers, fluent header builders, authentication handlers, and middleware so an ASP.NET Core application can parse credentials, issue challenges, and sign requests without re-implementing protocol formatting or signature calculation.

The package also builds on Cuemon.AspNetCore for middleware composition and adds the shared options and replay-protection pieces those schemes need. That includes a common AuthenticationOptions base, scheme-specific options, and digest nonce tracking through INonceTracker and the in-memory MemoryNonceTracker.

Key APIs

AuthenticationOptions is the shared base for the package's authentication schemes and centralizes the parts every flow needs, including the scheme name, secure-connection enforcement, the unauthorized response callback, and the delegate that turns an Authorization header string into a typed header model.

BasicAuthenticationHandler plugs Basic authentication into the ASP.NET Core handler pipeline and turns a validated BasicAuthorizationHeader plus the configured authenticator delegate into an AuthenticationTicket or an unauthorized result with the scheme challenge.

BasicAuthorizationHeaderBuilder creates a BasicAuthorizationHeader from username and password input, guards required fields, and rejects invalid usernames that contain the credential separator before emitting the encoded header value.

DigestAuthenticationOptions controls the moving parts of digest access authentication, including realm and opaque generation, nonce generation and expiry parsing, digest algorithm selection, authenticator callbacks, and the option to read HA1 values from server-side storage instead of recomputing them from plaintext passwords.

DigestAuthorizationHeaderBuilder assembles the digest field set from a challenge or request context and can compute HA1, HA2, and the final response value for both auth and auth-int, which makes it the main consumer-facing API for producing conforming digest headers.

MemoryNonceTracker is the built-in INonceTracker implementation for digest authentication. It stores nonce-count entries in memory and periodically removes stale entries, which gives the digest middleware a package-provided place to record and check nonce state during replay detection.

HmacAuthorizationHeaderBuilder derives the canonical request from HttpRequest or HttpRequestMessage, selects signed headers, computes the payload hash and string-to-sign, and produces the HmacAuthorizationHeader value that the package's HMAC authentication flow validates.

Basic usage

using System;
using System.Globalization;
using System.Net.Http;
using Codebelt.Extensions.Xunit;
using Cuemon.AspNetCore.Authentication.Hmac;
using Xunit;

namespace MyProject.Tests;

public class HmacRequestSigningTest : Test
{
    public HmacRequestSigningTest(ITestOutputHelper output) : base(output)
    {
    }

    [Fact]
    public void Build_ShouldSignOutboundRequestWithStableHeader()
    {
        var timestamp = DateTime.Parse("2022-07-10T12:50:42.0000000Z", CultureInfo.InvariantCulture, DateTimeStyles.RoundtripKind);
        using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.cuemon.net/");
        request.Headers.Date = timestamp;
        request.Headers.Host = "api.cuemon.net";

        var header = new HmacAuthorizationHeaderBuilder()
            .AddFromRequest(request)
            .AddClientId("AKIAIOSFODNN7EXAMPLE")
            .AddClientSecret("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY")
            .AddCredentialScope("some-limiting-scope")
            .Build();

        TestOutput.WriteLine(header.ToString());
        Assert.Equal("HMAC Credential=AKIAIOSFODNN7EXAMPLE/some-limiting-scope, SignedHeaders=host;date, Signature=ae1fa2ff4e715d92fd91f2d2027a587377662d0c40fa47a7b9155d5aa6b0e308", header.ToString());
    }
}

Use this pattern when an outbound ASP.NET Core integration needs a reproducible HMAC Authorization header built from the request metadata instead of hand-assembling canonical strings and signatures. It matters because the builder keeps header selection, timestamp handling, credential scope, and signature formatting aligned with the package's authentication flow.

Installation

dotnet add package Cuemon.AspNetCore.Authentication

Usage guidance

Use this package when an ASP.NET Core application needs Basic, Digest, or HMAC authentication wired into the framework pipeline with package-provided handlers, middleware, options, and authorization-header builders. If you only need the ASP.NET Core authentication abstractions themselves or only need lower-level header and cryptography helpers outside an ASP.NET Core application, the framework APIs or the lower-level Cuemon packages are the better fit.